puressh 0.2.4

//! OpenSSH-compatible `ssh_config` / `sshd_config` parser.
//!
//! `puressh::config` parses the two configuration files OpenSSH ships
//! (`ssh_config(5)` and `sshd_config(5)`). The grammar is shared, so this
//! crate exposes a single low-level tokenizer ([`ParsedLine`],
//! [`tokenize_file_with_includes`]) and two semantic layers on top — [`SshClientConfig`] for the client side, and
//! [`SshServerConfig`] for the daemon side. Both round-trip through
//! [`str::parse`]-like entry points and return a typed [`ConfigError`] on
//! bad input.
//!
//! The module is `alloc`-only — it parses `&str`. Reading the file off disk
//! and choosing the search path is up to the caller (the bin/common helpers
//! do this for `~/.ssh/config` and `/etc/ssh/ssh_config`).
//!
//! ## Example
//!
//! ```
//! use puressh::config::SshClientConfig;
//!
//! let src = "\
//! Host gw
//!   HostName 198.51.100.7
//!   User admin
//!   Port 2222
//! ";
//! let cfg = SshClientConfig::parse(src).unwrap();
//! let eff = cfg.lookup("gw");
//! assert_eq!(eff.host_name.as_deref(), Some("198.51.100.7"));
//! assert_eq!(eff.port, Some(2222));
//! assert_eq!(eff.user.as_deref(), Some("admin"));
//! ```

#![cfg(feature = "alloc")]

use alloc::string::String;

pub(crate) mod algos;
pub mod client;
pub(crate) mod glob;
pub(crate) mod host_port;
#[cfg(feature = "std")]
pub(crate) mod include;
pub(crate) mod match_block;
pub(crate) mod parser;
pub mod server;

pub use algos::{
    AlgoCategory, default_list as default_algorithms, known_names as supported_algorithms,
};
pub use client::{
    AddressFamily, CanonicalizeHostname, ClientOptions, ControlMaster, ControlPersist,
    DynamicForwardSpec, ForwardEndpoint, ForwardSpec, GatewayPorts, IdentityAgent, KnockSetting,
    LocalForwardSpec, ObscureKeystrokeTiming, RemoteForwardSpec, RequestTty, SessionType,
    SshClientConfig, StrictMode, parse_escape_char, parse_forward,
};
pub use glob::{HostPattern, host_matches};
pub use host_port::{parse_host_port, parse_host_port_pattern};
#[cfg(feature = "std")]
pub use include::{glob_paths, tokenize_file_with_includes};
pub use match_block::{
    AddressKind, AddressPattern, ExecPolicy, MatchCondition, MatchContext, address_matches,
};
pub use parser::{ParsedLine, tokenize};
pub use server::{
    Compression, HostPort, PerSourcePenalties, PermitRootLogin, RekeyLimit, ServerMatchBlock,
    ServerOptions, SshServerConfig, TcpForwarding,
};
// `AddressFamily` and `GatewayPorts` already exist as client-config types in
// this module's namespace; the server variants live behind `config::server::`
// to avoid the name clash. Re-export the server ones under disambiguated names
// for callers that want them at the top level.
pub use server::{AddressFamily as ServerAddressFamily, GatewayPorts as ServerGatewayPorts};

/// Errors produced while parsing or evaluating an SSH config file.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum ConfigError {
    /// Lexical/structural failure (unterminated quote, bad block header, …).
    Syntax {
        /// 1-based source line number.
        line: usize,
        /// Human-readable description.
        msg: String,
    },
    /// Keyword present in the file but not recognised by this parser.
    UnknownKeyword {
        /// 1-based source line number.
        line: usize,
        /// The offending keyword (lowercased).
        keyword: String,
    },
    /// Value for a recognised keyword failed to parse (bad integer, bad
    /// enum, bad forward-spec, …).
    BadValue {
        /// 1-based source line number.
        line: usize,
        /// The keyword whose value was malformed.
        keyword: String,
        /// Human-readable description of what went wrong.
        msg: String,
    },
    /// Construct understood by OpenSSH but not yet implemented here (e.g.
    /// `Match` blocks in `sshd_config`).
    Unsupported {
        /// 1-based source line number.
        line: usize,
        /// Human-readable description of the unsupported construct.
        msg: String,
    },
    /// An error in a file brought in by `Include`.
    InFile {
        /// The included file's path.
        file: String,
        /// The error, with its line number in that file.
        error: alloc::boxed::Box<ConfigError>,
    },
}

impl ConfigError {
    /// `error`, located in the included `file` (no-op for `None`).
    pub(crate) fn in_file(self, file: Option<&str>) -> Self {
        match file {
            Some(f) if !matches!(self, ConfigError::InFile { .. }) => ConfigError::InFile {
                file: f.into(),
                error: alloc::boxed::Box::new(self),
            },
            _ => self,
        }
    }

    fn write_located(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            ConfigError::Syntax { line, msg } => write!(f, "line {line}: syntax: {msg}"),
            ConfigError::UnknownKeyword { line, keyword } => {
                write!(f, "line {line}: unknown keyword: {keyword}")
            }
            ConfigError::BadValue { line, keyword, msg } => {
                write!(f, "line {line}: bad value for {keyword}: {msg}")
            }
            ConfigError::Unsupported { line, msg } => {
                write!(f, "line {line}: unsupported: {msg}")
            }
            ConfigError::InFile { file, error } => {
                write!(f, "{file} ")?;
                error.write_located(f)
            }
        }
    }
}

impl core::fmt::Display for ConfigError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.write_str("config: ")?;
        self.write_located(f)
    }
}

#[cfg(feature = "std")]
impl std::error::Error for ConfigError {}