Enum SshCliError 

#[non_exhaustive]
pub enum SshCliError {
    Io(Error),
    Json(Error),
    TomlDe(Error),
    TomlSer(Error),
    Domain(DomainError),
    SshConnection(String),
    SshAuthentication(String),
    ConnectionFailed(String),
    AuthenticationFailed,
    HostKeyChanged {
        host: String,
        port: u16,
        expected: String,
        obtained: String,
    },
    CommandTooLong {
        max: usize,
        len: usize,
    },
    SudoDisabled,
    SuPasswordMissing,
    ChannelFailed {
        message: String,
        source: Option<ErrorSource>,
    },
    SshTimeout(u64),
    CommandFailed {
        exit_code: i32,
        stderr: String,
    },
    VpsNotFound(String),
    NoActiveVps,
    VpsDuplicate(String),
    FileNotFound(String),
    InvalidArgument(String),
    Tls {
        message: String,
        source: Option<ErrorSource>,
    },
    Crypto {
        op: &'static str,
    },
    Config(String),
    Unavailable {
        service: &'static str,
    },
    Software {
        op: &'static str,
    },
    Timeout(u64),
    XdgDirectory,
    SchemaIncompatible {
        expected: u32,
        found: u32,
    },
    PartialFailure {
        failed: usize,
        total: usize,
        op: &'static str,
    },
    Generic(String),
}

Domain errors produced by ssh-cli operations.

#[non_exhaustive] (G-SEC-11): external crates must use wildcard arms so new variants in minor releases do not break SemVer consumers.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Io(Error)

Underlying I/O error.

Json(Error)

JSON serialization or deserialization error.

TomlDe(Error)

TOML deserialization error.

TomlSer(Error)

TOML serialization error.

Domain(DomainError)

Domain newtype / parse construction failure (G-ERR-02).

SshConnection(String)

SSH connection-layer error.

SshAuthentication(String)

SSH authentication error with detail.

ConnectionFailed(String)

TCP/SSH connection failed before authentication.

AuthenticationFailed

SSH authentication rejected by the server.

HostKeyChanged

Host key diverged from known_hosts (possible MITM).

Fields

host: String

Host name.

port: u16

Port.

expected: String

Expected fingerprint.

obtained: String

Observed fingerprint.

CommandTooLong

Command exceeds max_command_chars.

Fields

max: usize

Configured limit.

len: usize

Command length.

SudoDisabled

Elevation disabled (disable_sudo).

SuPasswordMissing

Missing su password for su-exec.

ChannelFailed

Failed to open or operate an SSH channel (G-ERR-05: optional source chain).

Fields

message: String

Short context (no embedded cause Display).

source: Option<ErrorSource>

Root cause when available.

SshTimeout(u64)

SSH operation timed out.

CommandFailed

Remote command exited non-zero.

Fields

exit_code: i32

Remote process exit code.

stderr: String

Truncated stderr snippet.

VpsNotFound(String)

VPS name not found in the registry.

NoActiveVps

No active VPS (active sibling file missing) — GAP-SSH-EXIT-002.

VpsDuplicate(String)

Duplicate VPS name in the registry.

FileNotFound(String)

Local or remote file not found.

InvalidArgument(String)

Invalid CLI argument.

Tls

TLS layer error (handshake, config, PEM, ACME, mTLS) — G-ERR-04.

Fields

message: String

Short context (no embedded cause Display).

source: Option<ErrorSource>

Root cause when available.

Crypto

Cryptographic / secrets key material failure (no secret bytes in Display).

Fields

op: &'static str

Stable operation id (encrypt, decrypt, keyring_get, …).

Config(String)

Configuration / registry serialization failure (non-TOML crate errors).

Unavailable

A host service the CLI depends on is not answering (exit 69).

G-ERR-R01: Config was the default landing spot for every map_err without an obvious variant, so a locked OS keyring exited 65 — the same code as corrupt TOML — and inherited retryable: false. An agent therefore gave up permanently on the one failure in the list that a plain retry actually fixes.

Fields

service: &'static str

Stable service id (keyring, …).

Software

Internal failure with no user-fixable input (exit 70).

G-ERR-R01: reserved for conditions the caller cannot influence at all, such as a CSPRNG that refuses to produce bytes. Kept apart from Self::Unavailable because waiting and retrying is useless here, while there it is the remedy.

Fields

op: &'static str

Stable operation id (rng, …).

Timeout(u64)

Generic timeout.

XdgDirectory

XDG config directory unavailable.

SchemaIncompatible

Incompatible schema version.

Fields

expected: u32

Expected schema version.

found: u32

Found schema version.

PartialFailure

Multi-host fan-out where some targets failed and others succeeded.

Partial success is the normal outcome of a fan-out, not malformed data. It previously reused Self::Config, which meant an agent could not tell “1 of 10 hosts failed” apart from “the TOML is corrupt” — both exited 65. This variant exits exit_codes::EX_GENERAL and carries the counts so the agent can branch on scale of failure without parsing prose.

Fields

failed: usize

Number of targets that failed.

total: usize

Total number of targets attempted.

op: &'static str

Stable operation id (exec, health-check, scp upload, …).

Generic(String)

Uncategorized error — last resort (prefer typed variants).

Implementations

impl SshCliError

pub fn tls_msg(message: impl AsRef<str>) -> Self

TLS error with message only (no root cause).

Accepts &str / String via AsRef<str> to avoid Into ambiguity with foreign From<&str> impls in the dependency graph.

pub fn tls_src( message: impl AsRef<str>, source: impl Error + Send + Sync + 'static, ) -> Self

TLS error preserving std::error::Error::source (G-ERR-04 / G-ERR-16 DRY).

pub fn channel_msg(message: impl AsRef<str>) -> Self

Channel error with message only.

pub fn channel_src( message: impl AsRef<str>, source: impl Error + Send + Sync + 'static, ) -> Self

Channel error preserving source (G-ERR-05 / G-ERR-16 DRY).

pub fn crypto(op: &'static str) -> Self

Crypto / secrets failure without embedding secret material.

pub fn unavailable(service: &'static str) -> Self

Builds an Self::Unavailable for a host service that is not answering.

pub fn software(op: &'static str) -> Self

Builds a Self::Software for an internal failure with no user-fixable input.

pub fn error_code(&self) -> &'static str

Stable machine-oriented code for JSON envelopes (G-ERR-08).

pub fn exit_code(&self) -> i32

Returns the sysexits.h exit code for this error.

pub fn retry_kind(&self) -> RetryKind

Typed retry kind (no string matching on Display).

pub fn is_retryable(&self) -> bool

Whether an agent may re-invoke the CLI with the same argv after backoff.

pub fn is_permanent(&self) -> bool

Explicit complement of Self::is_retryable.

pub fn classify(&self) -> ErrorClass

High-level class for the JSON envelope error_class field.

pub fn layer(&self) -> ErrorLayer

Stack layer for diagnostics.

pub fn retry_after(&self) -> Option<Duration>

Optional cool-down hint (SSH has no HTTP Retry-After; always None).

pub fn suggestion(&self) -> Option<&'static str>

Short agent-facing suggestion for the JSON envelope.

Trait Implementations

impl Debug for SshCliError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SshCliError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for SshCliError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<DomainError> for SshCliError

fn from(source: DomainError) -> Self

Converts to this type from the input type.

impl From<Error> for SshCliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for SshCliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for SshCliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for SshCliError

fn from(source: Error) -> Self

Converts to this type from the input type.