mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Connection profiles: the named destinations the product talks to.

use clap::{Args, Subcommand};

/// The seven profile lifecycle commands.
#[derive(Debug, Clone, Subcommand)]
pub enum ConnCommand {
    /// Create a named profile.
    Add(AddArgs),
    /// List profiles without revealing any secret.
    List,
    /// Show one profile with its secret redacted.
    Show(NameArgs),
    /// Change a field of an existing profile.
    Edit(EditArgs),
    /// Delete a profile and the secret it holds.
    Remove(NameArgs),
    /// Open, confirm and close the connection.
    Test(TestArgs),
    /// Set which profile applies without an explicit choice.
    Default(NameArgs),
}

/// A command addressing one profile by name.
///
/// The name is optional to the argument layer and required to the command.
/// Publishing the contract must cost nothing, and a caller asking what this
/// command answers should not have to invent a profile first. Absence is
/// refused where the profile is actually touched, and carries a code.
#[derive(Debug, Clone, Args)]
pub struct NameArgs {
    /// Profile name.
    pub name: Option<String>,
}

/// Fields accepted when creating a profile.
///
/// The secret never travels as a flag value, because a flag value is visible
/// in the process list of the whole machine.
// Allowed: a command line offers independent switches, and clap builds
// this record field by field from them. Folding them into a nested
// type would publish a grouping the manual does not have and change
// the path every reader writes, for no gain to the caller.
#[allow(clippy::struct_excessive_bools)]
#[derive(Debug, Clone, Args)]
pub struct AddArgs {
    /// Profile name.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`NameArgs`].
    pub name: Option<String>,

    /// Server host.
    #[arg(long)]
    pub host: Option<String>,

    /// Server port.
    #[arg(long)]
    pub port: Option<u16>,

    /// Local socket path, preferred over the network when present.
    ///
    /// Also spelled `--pipe`, which is the name the manual publishes for the
    /// same thing on the local channel Windows offers. The requirement number
    /// is deliberately not written here: a number in a comment counts as a
    /// citation to the coverage walk, and that requirement is still waiting on
    /// a host this suite does not have. Naming it would discharge it.
    ///
    /// One field carries both spellings, deliberately:
    /// the driver has a single setting for it, documented as "path to unix
    /// socket (or named pipe on Windows)", so two fields would be two names
    /// for one destination and the caller could set one while the work read
    /// the other. That is precisely how `--db` and `--database` came to lose a
    /// parameter in silence, and an alias cannot do it.
    #[arg(long, alias = "pipe")]
    pub socket: Option<std::path::PathBuf>,

    /// User the credential belongs to.
    #[arg(long)]
    pub user: Option<String>,

    /// Read the secret from the standard input.
    #[arg(long)]
    pub password_stdin: bool,

    /// Fix the database, so the profile stops taking a database parameter.
    ///
    /// The database itself is named by the global `--database`, which the
    /// manual publishes for this command. A second local flag for the same
    /// idea used to sit here and it silently won: the global absorbed the
    /// value the caller wrote and the local field it filled was a different
    /// one, so `conn add p --database loja` stored no database at all and
    /// still succeeded.
    ///
    /// Takes an optional value, like the two truth values below it. Creating a
    /// profile has no third state to carry — there is nothing stored yet to
    /// leave alone — so `--pin-database false` and leaving it out mean the same
    /// thing here. It accepts the value anyway, because the alternative was
    /// measured and is worse: on this one command `--require-tls true` was
    /// accepted while `--pin-database true` ended in 2 with `unexpected
    /// argument 'true'`, a message that names the value rather than the flag
    /// and leaves the caller to guess which of three siblings takes one. The
    /// spelling `conn edit` publishes has to work here too, or the caller
    /// learns a form that breaks when they move it one command sideways.
    #[arg(long, value_name = "BOOL", num_args = 0..=1, default_missing_value = "true")]
    pub pin_database: Option<bool>,

    /// Declared authentication method.
    #[arg(long)]
    pub auth: Option<String>,

    /// Client certificate presented to the server.
    #[arg(long)]
    pub client_cert: Option<std::path::PathBuf>,

    /// Key matching the client certificate.
    #[arg(long)]
    pub client_key: Option<std::path::PathBuf>,

    /// Authority used to verify the server certificate.
    #[arg(long)]
    pub ca: Option<std::path::PathBuf>,

    /// Refuse to open unless the channel is encrypted.
    ///
    /// Three states, because two cannot carry the answer. Written bare it
    /// demands encryption, written `--require-tls false` it states this
    /// destination does not, and left out it says nothing and lets the stored
    /// `conn.require_tls` decide. A bare truth value here would make the stored
    /// key unbeatable, which is the precedence the product publishes inverted.
    #[arg(long, value_name = "BOOL", num_args = 0..=1, default_missing_value = "true")]
    pub require_tls: Option<bool>,

    /// Session adjustments applied when opening.
    #[arg(long, value_name = "SETTING")]
    pub session_setup: Vec<String>,

    /// Refuse any change through this profile.
    ///
    /// Takes an optional value for the reason given on `--pin-database` above:
    /// creating a profile has no third state, but the spelling has to match the
    /// one `conn edit` publishes.
    #[arg(long, value_name = "BOOL", num_args = 0..=1, default_missing_value = "true")]
    pub read_only_profile: Option<bool>,

    /// Confirm the connection right away.
    #[arg(long)]
    pub check: bool,
}

/// Fields accepted when editing a profile.
#[derive(Debug, Clone, Args)]
pub struct EditArgs {
    /// Profile name.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`NameArgs`].
    pub name: Option<String>,

    /// The fields this edit may change.
    #[command(flatten)]
    pub fields: EditableFields,
}

/// Every field an edit may change.
#[derive(Debug, Clone, Args)]
pub struct EditableFields {
    /// Server host.
    #[arg(long)]
    pub host: Option<String>,
    /// Server port.
    #[arg(long)]
    pub port: Option<u16>,
    /// Local socket path, also spelled `--pipe` for the reason given on
    /// [`AddArgs`].
    #[arg(long, alias = "pipe")]
    pub socket: Option<std::path::PathBuf>,
    /// User the credential belongs to.
    #[arg(long)]
    pub user: Option<String>,
    /// Read a new secret from the standard input.
    #[arg(long)]
    pub password_stdin: bool,
    /// Fix the database, so the profile stops taking a database parameter.
    ///
    /// Three states rather than two, which every truth value an edit may write
    /// carries here: written bare it fixes the database, written
    /// `--pin-database false` it releases it, and left out it changes nothing.
    /// Two states would make an edit that names one field reset the other, so
    /// "not mentioned" has to be a value the field can hold.
    ///
    /// # A stated departure
    ///
    /// The project's own guidance on this argument library says never to take a
    /// truth value as `Option<bool>` and to use `bool`. Every truth value in
    /// this struct departs from it, deliberately, and the reason is the sentence
    /// above: that guidance is written for a flag that answers "was this
    /// asked for", where two states are all there is to say. These answer a
    /// different question — "should this field change, and to what" — and it
    /// has three answers. Collapsing it would not simplify the type, it would
    /// silently delete stored policy on every edit that did not restate it.
    ///
    /// The same guidance offers a way to get three states without this type: a
    /// pair of plain `bool` flags, `--pin-database` and `--no-pin-database`,
    /// each overriding the other, where writing neither is the third state.
    /// That works, and it is declined on size rather than on correctness. The
    /// three editable truth values here would become six flags, in a product
    /// whose FR-053 publishes its own surface for an agent to read and whose
    /// whole argument is that a smaller answer is a better one. Doubling the
    /// surface to avoid one wrapper is the trade in the wrong direction.
    ///
    /// The count said six and twelve until an audit counted them: three, not
    /// six. The argument survived being wrong by a factor of two, because
    /// doubling is doubling at any size — but the number is what carries it, and
    /// this is the second time in one sitting that a sentence in this repository
    /// stopped matching the thing beside it while still reading as true. The
    /// first was `tests/support/delegated.rs`, whose own correction notes that
    /// its count is spelled out because it was wrong once. A number in prose is
    /// a claim, and nothing here checks it.
    ///
    /// Recorded here rather than left to be re-derived, because a departure
    /// nobody wrote down reads as an oversight by whoever finds it next — and
    /// an alternative discarded without a line reads as one never considered.
    ///
    /// The prose above is written for whoever maintains this, and `long_help`
    /// keeps it out of the terminal. Without that, clap serves the whole doc
    /// comment as the help of this flag, so a caller asking what a flag does was
    /// handed an audit note naming a test file and a requirement number.
    #[arg(
        long,
        value_name = "BOOL",
        num_args = 0..=1,
        default_missing_value = "true",
        long_help = "Fix this profile to one database.\n\n\
            Three states rather than two: written bare it fixes the database, \
            written `--pin-database false` it releases it, and left out it \
            changes nothing. Two states would make an edit that names one field \
            reset the other, so a field left unmentioned has to be a value it \
            can hold."
    )]
    pub pin_database: Option<bool>,
    /// Refuse any change through this profile.
    ///
    /// Carries the same three states as `--pin-database` above, and for the
    /// same reason. It did not, and the gap was not visible from here: the
    /// field beside it announced that "every editable field here" had three
    /// states while this one had two, so a reader checking the sentence rather
    /// than the attribute found the promise and stopped. FR-087 then published
    /// `conn edit producao --read-only-profile` as its example and that form
    /// ended in 2, because the value was required.
    ///
    /// Kept out of the terminal by `long_help`, for the reason stated on
    /// `--pin-database` above.
    #[arg(
        long,
        value_name = "BOOL",
        num_args = 0..=1,
        default_missing_value = "true",
        long_help = "Refuse any change through this profile.\n\n\
            Three states, like `--pin-database`: written bare it refuses every \
            change, written `--read-only-profile false` it allows them again, \
            and left out it changes nothing."
    )]
    pub read_only_profile: Option<bool>,

    /// Declared authentication method.
    #[arg(long)]
    pub auth: Option<String>,

    /// Client certificate presented to the server.
    ///
    /// Editable for the reason the whole group below is: a destination that
    /// only admits an identified caller is exactly the destination whose
    /// identity expires, and an identity that can be written once but never
    /// replaced obliges the caller to delete the profile and build it again.
    /// That trades a rotation for the secret the profile holds, which the
    /// caller may no longer have.
    #[arg(long)]
    pub client_cert: Option<std::path::PathBuf>,

    /// Key matching the client certificate.
    #[arg(long)]
    pub client_key: Option<std::path::PathBuf>,

    /// Authority used to verify the server certificate.
    #[arg(long)]
    pub ca: Option<std::path::PathBuf>,

    /// Whether this destination demands an encrypted channel.
    ///
    /// Three states, matching the field it writes and `--pin-database` beside
    /// it: written bare it demands encryption, written `--require-tls false` it
    /// says this destination does not, and left out it changes nothing and
    /// leaves whatever the profile already said.
    #[arg(long, value_name = "BOOL", num_args = 0..=1, default_missing_value = "true")]
    pub require_tls: Option<bool>,

    /// Session adjustments applied when opening.
    ///
    /// A list cannot borrow the three-state shape of the values above, because
    /// "not mentioned" and "mentioned as nothing" are the same empty list. So
    /// the empty text is spelled out and means the empty list: `--session-setup
    /// ''` clears the adjustments, any other use replaces them, and leaving the
    /// flag out keeps them. Without that spelling the adjustments would be the
    /// one stored field an edit could add to and never take away.
    #[arg(long, value_name = "SETTING")]
    pub session_setup: Vec<String>,
}

/// Options of the connectivity check.
#[derive(Debug, Clone, Args)]
pub struct TestArgs {
    /// Profile to test; defaults to the global choice.
    pub name: Option<String>,
}