capy-core 0.10.0

Typed configuration, application context, and errors for the Capy web framework.
Documentation
use crate::{AppError, ValidationErrors};
use axum::http::StatusCode;

/// An intentional, public application policy rejection. Only these statuses may
/// be exposed by listeners. Codes and messages must be static, safe application
/// text, never dependency errors, credentials or account-existence diagnostics.
#[derive(Clone, Debug, thiserror::Error)]
#[non_exhaustive]
pub enum EventRejection {
    /// Policy forbids the operation (403).
    #[error("{message}")]
    Forbidden {
        /// Stable application-owned machine code.
        code: &'static str,
        /// Safe public explanation.
        message: &'static str,
    },
    /// Application state conflicts with the operation (409).
    #[error("{message}")]
    Conflict {
        /// Stable application-owned machine code.
        code: &'static str,
        /// Safe public explanation.
        message: &'static str,
    },
    /// Application validation failed (422). Field messages are explicitly public.
    #[error("Validation failed")]
    Validation {
        /// Stable application-owned machine code.
        code: &'static str,
        /// Safe field messages; do not reflect secrets or internal error strings.
        errors: ValidationErrors,
    },
    /// The application has temporarily closed this operation (503).
    #[error("{message}")]
    Unavailable {
        /// Stable application-owned machine code.
        code: &'static str,
        /// Safe public explanation.
        message: &'static str,
    },
}
impl EventRejection {
    /// Stable application code included in the JSON error envelope.
    pub fn code(&self) -> &'static str {
        match self {
            Self::Forbidden { code, .. }
            | Self::Conflict { code, .. }
            | Self::Validation { code, .. }
            | Self::Unavailable { code, .. } => code,
        }
    }
    /// Intentional HTTP response status.
    pub fn status(&self) -> StatusCode {
        match self {
            Self::Forbidden { .. } => StatusCode::FORBIDDEN,
            Self::Conflict { .. } => StatusCode::CONFLICT,
            Self::Validation { .. } => StatusCode::UNPROCESSABLE_ENTITY,
            Self::Unavailable { .. } => StatusCode::SERVICE_UNAVAILABLE,
        }
    }
}

/// Listener outcome. Only `Reject` exposes application-authored public text.
/// `?` on database/anyhow/unexpected application errors takes the private failure
/// path. A nested operation's already-typed `AppError::Rejected` remains a rejection.
#[derive(Debug, thiserror::Error)]
pub enum EventError {
    /// Expected application policy rejection; the entire transition must roll back.
    #[error("Application rejected lifecycle operation")]
    Reject(#[from] EventRejection),
    /// Unexpected failure; never expose its message as an application rejection.
    #[error("Lifecycle listener failed")]
    Failure(#[source] AppError),
}
impl From<AppError> for EventError {
    fn from(error: AppError) -> Self {
        match error {
            AppError::Rejected(problem) => Self::Reject(problem),
            error => Self::Failure(error),
        }
    }
}
impl From<sea_orm::DbErr> for EventError {
    fn from(error: sea_orm::DbErr) -> Self {
        Self::Failure(error.into())
    }
}
impl From<anyhow::Error> for EventError {
    fn from(error: anyhow::Error) -> Self {
        Self::Failure(error.into())
    }
}
/// Result returned by a transactional lifecycle listener.
pub type EventResult = std::result::Result<(), EventError>;