arcature 2026.2.1

//! Typed engine errors for the high-level [`Application`] lifecycle.
//!
//! Arcature owns the framework failure domain (engine spec §52): configuration,
//! subsystem startup, listener bind, route/proxy setup, background-task
//! failure, and graceful shutdown. Source errors are preserved (not collapsed
//! to `String`), and secret-bearing values are never exposed through
//! [`Display`] or [`Debug`].
//!
//! This PR (facade foundation) introduces the error *type* and the listener /
//! serve variants. Subsystem startup/shutdown variants are added with the
//! runtime-lifecycle PR.

use std::fmt;

/// A failure in the Arcature application engine.
#[derive(Debug)]
pub enum EngineError {
    /// Binding the HTTP listener failed. Wraps the underlying I/O error and
    /// records the bind address for diagnostics (the address is not a secret).
    BindListener {
        /// The address that failed to bind.
        address: String,
        /// The underlying I/O error, preserved for diagnostics.
        source: std::io::Error,
    },
    /// Serving the application failed after the listener was bound.
    Serve {
        /// The underlying I/O error, preserved for diagnostics.
        source: std::io::Error,
    },
    /// The configured HTTP port was invalid (out of range, non-numeric).
    InvalidPort(String),
    /// A subsystem failed to start during engine startup. The variant
    /// records which subsystem failed and preserves the typed source error
    /// (never collapsed to `String` — AGENTS.md §18).
    Startup {
        /// Which subsystem failed (for diagnostics; never a secret).
        subsystem: &'static str,
        /// A short, safe description of the failure stage (e.g. "connect",
        /// "migrate"). Never a secret.
        stage: &'static str,
        /// The typed source error, redacted in `Display` (secrets never leak).
        source: StartupError,
    },
    /// A running subsystem failed during or after shutdown. Preserved as a
    /// typed error so the operator sees which subsystem failed to drain.
    Shutdown {
        /// Which subsystem failed.
        subsystem: &'static str,
        /// The typed source error.
        source: ShutdownError,
    },
}

/// A typed subsystem startup failure. Each variant wraps a specific upstream
/// error; the `Display` impl redacts any connection-string/credential content
/// (AGENTS.md §18: typed errors; secrets never leak through `Display`).
#[derive(Debug)]
pub enum StartupError {
    #[cfg(feature = "db")]
    Db(arcature_db::DbConnectError),
    #[cfg(feature = "cache")]
    Cache(arcature_cache::CacheConnectError),
    #[cfg(feature = "storage")]
    Storage(arcature_storage::StorageConnectError),
    #[cfg(feature = "mail")]
    Mail(arcature_mail::MailConfigError),
    #[cfg(feature = "jobs")]
    JobsMigrate(arcature_jobs::MigrateError),
}

/// A typed subsystem shutdown failure.
#[derive(Debug)]
pub enum ShutdownError {
    #[cfg(feature = "jobs")]
    Worker(arcature_jobs::WorkerError),
    #[cfg(feature = "mail")]
    Mail(String),
}

impl EngineError {
    /// The address variant of a bind failure, if this is a bind-listener error.
    #[must_use]
    pub fn bind_address(&self) -> Option<&str> {
        match self {
            Self::BindListener { address, .. } => Some(address),
            _ => None,
        }
    }
}

impl fmt::Display for EngineError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::BindListener { address, source } => {
                write!(f, "failed to bind HTTP listener on {address}: {source}")
            }
            Self::Serve { source } => write!(f, "HTTP server error: {source}"),
            Self::InvalidPort(value) => write!(f, "invalid HTTP port: {value:?}"),
            Self::Startup {
                subsystem,
                stage,
                source,
            } => {
                write!(
                    f,
                    "subsystem {subsystem} failed to start ({stage}): {source}"
                )
            }
            Self::Shutdown { subsystem, source } => {
                write!(f, "subsystem {subsystem} failed during shutdown: {source}")
            }
        }
    }
}

impl std::error::Error for EngineError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::BindListener { source, .. } | Self::Serve { source } => Some(source),
            Self::Startup { source, .. } => Some(source),
            Self::Shutdown { source, .. } => Some(source),
            Self::InvalidPort(_) => None,
        }
    }
}

impl fmt::Display for StartupError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            #[cfg(feature = "db")]
            Self::Db(e) => write!(f, "database connect: {e}"),
            #[cfg(feature = "cache")]
            Self::Cache(e) => write!(f, "cache connect: {e}"),
            #[cfg(feature = "storage")]
            Self::Storage(e) => write!(f, "storage connect: {e}"),
            #[cfg(feature = "mail")]
            Self::Mail(e) => write!(f, "mailer config: {e}"),
            #[cfg(feature = "jobs")]
            Self::JobsMigrate(e) => write!(f, "jobs migrate: {e}"),
            // Unreachable when no lifecycle features are enabled (the enum has
            // zero variants in that cfg; the wildcard is needed only to satisfy
            // exhaustiveness when at least one feature is on but a new variant
            // is added without a match arm).
            #[allow(unreachable_patterns)]
            _ => write!(f, "unknown startup error"),
        }
    }
}

impl std::error::Error for StartupError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            #[cfg(feature = "db")]
            Self::Db(e) => Some(e),
            #[cfg(feature = "cache")]
            Self::Cache(e) => Some(e),
            #[cfg(feature = "storage")]
            Self::Storage(e) => Some(e),
            #[cfg(feature = "mail")]
            Self::Mail(e) => Some(e),
            #[cfg(feature = "jobs")]
            Self::JobsMigrate(e) => Some(e),
            #[allow(unreachable_patterns)]
            _ => None,
        }
    }
}

impl fmt::Display for ShutdownError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            #[cfg(feature = "jobs")]
            Self::Worker(e) => write!(f, "worker: {e}"),
            #[cfg(feature = "mail")]
            Self::Mail(msg) => write!(f, "mailer shutdown: {msg}"),
            #[allow(unreachable_patterns)]
            _ => write!(f, "unknown shutdown error"),
        }
    }
}

impl std::error::Error for ShutdownError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            #[cfg(feature = "jobs")]
            Self::Worker(e) => Some(e),
            #[cfg(feature = "mail")]
            Self::Mail(_) => None,
            #[allow(unreachable_patterns)]
            _ => None,
        }
    }
}

/// The canonical `Result` alias for the Arcature engine (engine spec §52).
pub type Result<T> = std::result::Result<T, EngineError>;