Improve agama-web-server documentation and startup (#1273)

* Extend `agama-web-server` documentation.
* Do not require a D-Bus connection to just display the help.

rust/agama-server/src/agama-web-server.rs

@@ -35,17 +35,25 @@ const TOKEN_FILE: &str = "/run/agama/token";
 
 #[derive(Subcommand, Debug)]
 enum Commands {
-    /// Start the API server.
+    /// Starts the API server.
+    ///
+    /// This command starts the server in the given ports. The secondary port, if enabled, uses SSL.
+    /// If no certificate is specified, agama-web-server generates a self-signed one.
     Serve(ServeArgs),
-    /// Display the API documentation in OpenAPI format.
+    /// Generates the API documentation in OpenAPI format.
     Openapi,
 }
 
+/// Manage Agama's HTTP/JSON API.
+///
+/// Agama's public interface is composed by an HTTP/JSON API and a WebSocket. Using this API is
+/// possible to inspect or change the configuration, start the installation process and monitor
+/// changes and progress. This program, agama-web-server, implements such an API.
+///
+/// To start the API, use the "serve" command. If you want to get an OpenAPI representation, just go
+/// for the "doc" command.
 #[derive(Parser, Debug)]
-#[command(
-    version,
-    about = "Starts the Agama web-based API.",
-    long_about = None)]
+#[command(max_term_width = 100)]
 struct Cli {
     #[command(subcommand)]
     pub command: Commands,
@@ -64,36 +72,29 @@ fn find_web_ui_dir() -> PathBuf {
 
 #[derive(Args, Debug)]
 struct ServeArgs {
-    // Address/port to listen on (":::80" listens for both IPv6 and IPv4
-    // connections unless manually disabled in /proc/sys/net/ipv6/bindv6only)
-    #[arg(long, default_value = ":::80", help = "Primary address to listen on")]
+    // Address/port to listen on. ":::80" listens for both IPv6 and IPv4
+    // connections unless manually disabled in /proc/sys/net/ipv6/bindv6only.
+    /// Primary port to listen on
+    #[arg(long, default_value = ":::80")]
     address: String,
-    #[arg(
-        long,
-        default_value = None,
-        help = "Optional secondary address to listen on"
-    )]
+
+    /// Optional secondary address to listen on
+    #[arg(long, default_value = None)]
     address2: Option<String>,
-    #[arg(
-        long,
-        default_value = None,
-        help = "Path to the SSL private key file in PEM format"
-    )]
+
+    /// Path to the SSL private key file in PEM format
+    #[arg(long, default_value = None)]
     key: Option<String>,
-    #[arg(
-        long,
-        default_value = None,
-        help = "Path to the SSL certificate file in PEM format"
-    )]
+
+    /// Path to the SSL certificate file in PEM format
+    #[arg(long, default_value = None)]
     cert: Option<String>,
-    // Agama D-Bus address
-    #[arg(
-        long,
-        default_value = "unix:path=/run/agama/bus",
-        help = "The D-Bus address for connecting to the Agama service"
-    )]
+
+    /// The D-Bus address for connecting to the Agama service
+    #[arg(long, default_value = "unix:path=/run/agama/bus")]
     dbus_address: String,
-    // Directory containing the web UI code.
+
+    // Directory containing the web UI code
     #[arg(long)]
     web_ui_dir: Option<PathBuf>,
 }
@@ -292,6 +293,7 @@ async fn start_server(address: String, service: Router, ssl_acceptor: SslAccepto
 /// Start serving the API.
 /// `options`: command-line arguments.
 async fn serve_command(args: ServeArgs) -> anyhow::Result<()> {
+    _ = helpers::init_locale();
     init_logging().context("Could not initialize the logger")?;
 
     let (tx, _) = channel(16);
@@ -376,7 +378,6 @@ impl Termination for CliResult {
 #[tokio::main]
 async fn main() -> CliResult {
     let cli = Cli::parse();
-    _ = helpers::init_locale();
 
     if let Err(error) = run_command(cli).await {
         eprintln!("{:?}", error);

rust/package/agama.changes

@@ -1,3 +1,11 @@
+-------------------------------------------------------------------
+Wed May 29 11:16:11 UTC 2024 - Imobach Gonzalez Sosa <[email protected]>
+
+- Improve command-line interface help (gh#openSUSE/agama#1269 and
+  (gh#openSUSE/agama#1273).
+- agama-web-server connects to D-Bus only when needed
+  (gh#openSUSE/agama#1273).
+
 -------------------------------------------------------------------
 Wed May 29 10:40:21 UTC 2024 - Imobach Gonzalez Sosa <[email protected]>