Merge branch 'main' into docstrings

CONTRIBUTING.md

@@ -8,7 +8,7 @@ If any other issue occurs
 1. Make sure you locally checked out the head of the main branch
    - `git stash --include-untracked && git checkout main && git pull`
 2. Make sure all tests pass
-   - `cargo test`
+   - `cargo test --workspace --all-features`
 3. Make sure the current version in `rosenpass/Cargo.toml` matches that in the [last release on GitHub](https://github.com/rosenpass/rosenpass/releases)
    - Only normal releases count, release candidates and draft releases can be ignored
 4. Pick the kind of release that you want to make (`major`, `minor`, `patch`, `rc`, ...)

Cargo.lock

@@ -1210,9 +1210,9 @@ checksum = "830d08ce1d1d941e6b30645f1a0eb5643013d835ce3779a5fc208261dbe10f55"
 
 [[package]]
 name = "libc"
-version = "0.2.162"
+version = "0.2.166"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "18d287de67fe55fd7e1581fe933d965a5a9477b38e949cfa9f8574ef01506398"
+checksum = "c2ccc108bbc0b1331bd061864e7cd823c0cab660bbe6970e66e2c0614decde36"
 
 [[package]]
 name = "libcrux"
@@ -2058,9 +2058,9 @@ dependencies = [
 
 [[package]]
 name = "rustix"
-version = "0.38.39"
+version = "0.38.40"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "375116bee2be9ed569afe2154ea6a99dfdffd257f533f187498c2a8f5feaf4ee"
+checksum = "99e4ea3e1cdc4b559b8e5650f9c8e5998e3e5c1343b4eaf034565f32318d63c0"
 dependencies = [
  "bitflags 2.6.0",
  "errno",
@@ -2113,18 +2113,18 @@ checksum = "61697e0a1c7e512e84a621326239844a24d8207b4669b41bc18b32ea5cbf988b"
 
 [[package]]
 name = "serde"
-version = "1.0.214"
+version = "1.0.215"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f55c3193aca71c12ad7890f1785d2b73e1b9f63a0bbc353c08ef26fe03fc56b5"
+checksum = "6513c1ad0b11a9376da888e3e0baa0077f1aed55c17f50e7b2397136129fb88f"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.214"
+version = "1.0.215"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "de523f781f095e28fa605cdce0f8307e451cc0fd14e2eb4cd2e98a355b147766"
+checksum = "ad1e866f866923f252f05c889987993144fb74e722403468a4ebd70c3cd756c0"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2154,9 +2154,9 @@ dependencies = [
 
 [[package]]
 name = "serial_test"
-version = "3.1.1"
+version = "3.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b4b487fe2acf240a021cf57c6b2b4903b1e78ca0ecd862a71b71d2a51fed77d"
+checksum = "1b258109f244e1d6891bf1053a55d63a5cd4f8f4c30cf9a1280989f80e7a1fa9"
 dependencies = [
  "futures",
  "log",
@@ -2168,9 +2168,9 @@ dependencies = [
 
 [[package]]
 name = "serial_test_derive"
-version = "3.1.1"
+version = "3.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "82fe9db325bcef1fbcde82e078a5cc4efdf787e96b3b9cf45b50b529f2083d67"
+checksum = "5d69265a08751de7844521fd15003ae0a888e035773ba05695c5c759a6f89eef"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2339,18 +2339,18 @@ checksum = "23d434d3f8967a09480fb04132ebe0a3e088c173e6d0ee7897abbdf4eab0f8b9"
 
 [[package]]
 name = "thiserror"
-version = "1.0.68"
+version = "1.0.69"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02dd99dc800bbb97186339685293e1cc5d9df1f8fae2d0aecd9ff1c77efea892"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
 dependencies = [
  "thiserror-impl",
 ]
 
 [[package]]
 name = "thiserror-impl"
-version = "1.0.68"
+version = "1.0.69"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a7c61ec9a6f64d2793d8a45faba21efbe3ced62a886d44c36a009b2b519b4c7e"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
 dependencies = [
  "proc-macro2",
  "quote",

Cargo.toml

@@ -35,7 +35,7 @@ doc-comment = "0.3.3"
 base64ct = { version = "1.6.0", default-features = false }
 zeroize = "1.8.1"
 memoffset = "0.9.1"
-thiserror = "1.0.68"
+thiserror = "1.0.69"
 paste = "1.0.15"
 env_logger = "0.10.2"
 toml = "0.7.8"
@@ -50,7 +50,7 @@ log = { version = "0.4.22" }
 clap = { version = "4.5.20", features = ["derive"] }
 clap_mangen = "0.2.24"
 clap_complete = "4.5.37"
-serde = { version = "1.0.214", features = ["derive"] }
+serde = { version = "1.0.215", features = ["derive"] }
 arbitrary = { version = "1.4.1", features = ["derive"] }
 anyhow = { version = "1.0.93", features = ["backtrace", "std"] }
 mio = { version = "1.0.2", features = ["net", "os-poll"] }
@@ -76,7 +76,7 @@ libc = { version = "0.2" }
 uds = { git = "https://github.com/rosenpass/uds" }
 
 #Dev dependencies
-serial_test = "3.1.1"
+serial_test = "3.2.0"
 tempfile = "3"
 stacker = "0.1.17"
 libfuzzer-sys = "0.4"
@@ -89,4 +89,4 @@ procspawn = { version = "1.0.1", features = ["test-support"] }
 #Broker dependencies (might need cleanup or changes)
 wireguard-uapi = { version = "3.0.0", features = ["xplatform"] }
 command-fds = "0.2.3"
-rustix = { version = "0.38.39", features = ["net", "fs"] }
+rustix = { version = "0.38.40", features = ["net", "fs"] }

rosenpass/src/api/mio/connection.rs

@@ -88,7 +88,7 @@ impl MioConnection {
         })
     }
 
-    pub fn shoud_close(&self) -> bool {
+    pub fn should_close(&self) -> bool {
         let exhausted = self
             .buffers
             .as_ref()
@@ -262,7 +262,7 @@ pub trait MioConnectionContext {
     }
 
     fn should_close(&self) -> bool {
-        self.mio_connection().shoud_close()
+        self.mio_connection().should_close()
     }
 }
 

rosenpass/src/cli.rs

@@ -43,15 +43,15 @@ pub enum BrokerInterface {
 #[derive(Parser, Debug)]
 #[command(author, version, about, long_about, arg_required_else_help = true)]
 pub struct CliArgs {
-    /// lowest log level to show – log messages at higher levels will be omitted
+    /// Lowest log level to show
     #[arg(long = "log-level", value_name = "LOG_LEVEL", group = "log-level")]
     log_level: Option<log::LevelFilter>,
 
-    /// show verbose log output – sets log level to "debug"
+    /// Show verbose log output – sets log level to "debug"
     #[arg(short, long, group = "log-level")]
     verbose: bool,
 
-    /// show no log output – sets log level to "error"
+    /// Show no log output – sets log level to "error"
     #[arg(short, long, group = "log-level")]
     quiet: bool,
 
@@ -59,22 +59,23 @@ pub struct CliArgs {
     #[cfg(feature = "experiment_api")]
     api: crate::api::cli::ApiCli,
 
-    /// path of the wireguard_psk broker socket to connect to
+    /// Path of the `wireguard_psk` broker socket to connect to
     #[cfg(feature = "experiment_api")]
     #[arg(long, group = "psk-broker-specs")]
     psk_broker_path: Option<PathBuf>,
 
-    /// fd of the wireguard_spk broker socket to connect to
+    /// File descriptor of the `wireguard_psk` broker socket to connect to
     ///
-    /// when this command is called from another process, the other process can open and bind the
+    /// When this command is called from another process, the other process can
-    /// Unix socket for the psk broker connection to use themselves, passing it to this process --
+    /// open and bind the Unix socket for the PSK broker connection to use
-    /// in Rust this can be achieved using the
+    /// themselves, passing it to this process - in Rust this can be achieved
-    /// [command-fds](https://docs.rs/command-fds/latest/command_fds/) crate
+    /// using the [command-fds](https://docs.rs/command-fds/latest/command_fds/)
+    /// crate
     #[cfg(feature = "experiment_api")]
     #[arg(long, group = "psk-broker-specs")]
     psk_broker_fd: Option<i32>,
 
-    /// spawn a psk broker locally using a socket pair
+    /// Spawn a PSK broker locally using a socket pair
     #[cfg(feature = "experiment_api")]
     #[arg(short, long, group = "psk-broker-specs")]
     psk_broker_spawn: bool,
@@ -82,11 +83,16 @@ pub struct CliArgs {
     #[command(subcommand)]
     pub command: Option<CliCommand>,
 
-    /// Generate man page
+    /// Generate man pages for the CLI
+    ///
+    /// This option is used to generate man pages for Rosenpass in the specified
+    /// directory and exit.
     #[clap(long, value_name = "out_dir")]
     pub generate_manpage: Option<PathBuf>,
 
     /// Generate completion file for a shell
+    ///
+    /// This option is used to generate completion files for the specified shell
     #[clap(long, value_name = "shell")]
     pub print_completions: Option<clap_complete::Shell>,
 }
@@ -143,20 +149,20 @@ impl CliArgs {
 /// represents a command specified via CLI
 #[derive(Subcommand, Debug)]
 pub enum CliCommand {
-    /// Start Rosenpass in server mode and carry on with the key exchange
+    /// Start Rosenpass key exchanges based on a configuration file
     ///
-    /// This will parse the configuration file and perform the key exchange
+    /// This will parse the configuration file and perform key exchanges with
-    /// with the specified peers. If a peer's endpoint is specified, this
+    /// the specified peers. If a peer's endpoint is specified, this Rosenpass
-    /// Rosenpass instance will try to initiate a key exchange with the peer,
+    /// instance will try to initiate a key exchange with the peer; otherwise,
-    /// otherwise only initiation attempts from the peer will be responded to.
+    /// only initiation attempts from other peers will be responded to.
     ExchangeConfig { config_file: PathBuf },
 
-    /// Start in daemon mode, performing key exchanges
+    /// Start Rosenpass key exchanges based on command line arguments
     ///
-    /// The configuration is read from the command line. The `peer` token
+    /// The configuration is read from the command line. The `peer` token always
-    /// always separates multiple peers, e. g. if the token `peer` appears
+    /// separates multiple peers, e.g., if the token `peer` appears in the
-    /// in the WIREGUARD_EXTRA_ARGS it is not put into the WireGuard arguments
+    /// WIREGUARD_EXTRA_ARGS, it is not put into the WireGuard arguments but
-    /// but instead a new peer is created.
+    /// instead a new peer is created.
     /* Explanation: `first_arg` and `rest_of_args` are combined into one
      * `Vec<String>`. They are only used to trick clap into displaying some
      * guidance on the CLI usage.
@@ -185,7 +191,10 @@ pub enum CliCommand {
         config_file: Option<PathBuf>,
     },
 
-    /// Generate a demo config file
+    /// Generate a demo config file for Rosenpass
+    ///
+    /// The generated config file will contain a single peer and all common
+    /// options.
     GenConfig {
         config_file: PathBuf,
 
@@ -194,19 +203,19 @@ pub enum CliCommand {
         force: bool,
     },
 
-    /// Generate the keys mentioned in a configFile
+    /// Generate secret & public key for Rosenpass
     ///
-    /// Generates secret- & public-key to their destination. If a config file
+    /// Generates secret & public key to their destination. If a config file is
-    /// is provided then the key file destination is taken from there.
+    /// provided then the key file destination is taken from there, otherwise
-    /// Otherwise the
+    /// the destination is taken from the CLI arguments.
     GenKeys {
         config_file: Option<PathBuf>,
 
-        /// where to write public-key to
+        /// Where to write public key to
         #[clap(short, long)]
         public_key: Option<PathBuf>,
 
-        /// where to write secret-key to
+        /// Where to write secret key to
         #[clap(short, long)]
         secret_key: Option<PathBuf>,
 
@@ -215,21 +224,27 @@ pub enum CliCommand {
         force: bool,
     },
 
-    /// Deprecated - use gen-keys instead
+    /// Validate a configuration file
+    ///
+    /// This command will validate the configuration file and print any errors
+    /// it finds. If the configuration file is valid, it will print a success.
+    /// Defined secret & public keys are checked for existence and validity.
+    Validate { config_files: Vec<PathBuf> },
+
+    /// DEPRECATED - use the gen-keys command instead
     #[allow(rustdoc::broken_intra_doc_links)]
     #[allow(rustdoc::invalid_html_tags)]
+    #[command(hide = true)]
     Keygen {
-        // NOTE yes, the legacy keygen argument initially really accepted "privet-key", not "secret-key"!
+        // NOTE yes, the legacy keygen argument initially really accepted
+        // "private-key", not "secret-key"!
         /// public-key <PATH> private-key <PATH>
         args: Vec<String>,
     },
-
-    /// Validate a configuration
-    Validate { config_files: Vec<PathBuf> },
 }
 
 impl CliArgs {
-    /// runs the command specified via CLI
+    /// Runs the command specified via CLI
     ///
     /// ## TODO
     /// - This method consumes the [`CliCommand`] value. It might be wise to use a reference...

wireguard-broker/Cargo.toml

@@ -28,7 +28,7 @@ derive_builder = { workspace = true }
 postcard = { workspace = true }
 # Problem in CI, unknown reasons: dependency (libc) specified without providing a local path, Git repository, version, or workspace dependency to use
 # Maybe something about the combination of features and optional crates?
-rustix = { version = "0.38.39", optional = true }
+rustix = { version = "0.38.40", optional = true }
 libc = { version = "0.2", optional = true }
 
 # Mio broker client