footing 0.6.3

Feature-gated foundations for Rust backend services
Documentation
//! HTTP policy and foundation construction errors.

use std::fmt;

use thiserror::Error;

use crate::{
    http::{EndpointMethod, IdempotencyRequestPolicy},
    result::{ClassifyError, ErrorKind},
};

#[derive(Error)]
#[non_exhaustive]
/// Errors that can occur while handling HTTP layer.
pub enum HttpMiddlewareError {
    #[error("rate limiting is enabled but no rate-limit store was provided")]
    /// The enabled rate-limit policy has no runtime store.
    MissingRateLimitStore,
    #[error("idempotency is enabled but no idempotency store was provided")]
    /// The enabled idempotency policy has no runtime store.
    MissingIdempotencyStore,
    #[error("identity-based rate limiting requires an HTTP authentication hook")]
    /// Principal- or tenant-based policies have no ordered authentication integration.
    MissingAuthenticationHook,
    #[error(
        "endpoint contract {method} {path} rate-limit policy differs: expected enabled={expected_enabled}, actual enabled={actual_enabled}"
    )]
    /// A registered route's rate-limit enablement differs from its contract.
    EndpointContractRateLimitMismatch {
        /// The endpoint method.
        method: EndpointMethod,
        /// The endpoint route path.
        path: String,
        /// Whether the endpoint contract declares rate limiting.
        expected_enabled: bool,
        /// Whether the stack actually applies rate limiting.
        actual_enabled: bool,
    },
    #[error(
        "endpoint contract {method} {path} idempotency policy differs: expected {expected:?}, actual {actual:?}"
    )]
    /// A registered route's idempotency policy differs from its contract.
    EndpointContractIdempotencyMismatch {
        /// The endpoint method.
        method: EndpointMethod,
        /// The endpoint route path.
        path: String,
        /// The declared endpoint behavior.
        expected: IdempotencyRequestPolicy,
        /// The effective Foundation request policy.
        actual: IdempotencyRequestPolicy,
    },
    #[error("endpoint contract {method} {path} requires ordered authentication")]
    /// An identity-aware route has no authentication hook before Foundation policies.
    EndpointContractAuthenticationRequired {
        /// The endpoint method.
        method: EndpointMethod,
        /// The endpoint route path.
        path: String,
    },
    #[error("endpoint contract {method} {path} requires authorization before idempotency replay")]
    /// A replayable route with identity-category or permission requirements has no authorization hook.
    EndpointContractAuthorizationRequired {
        /// The endpoint method.
        method: EndpointMethod,
        /// The endpoint route path.
        path: String,
    },
    #[error("public endpoint contract {method} {path} cannot use identity-based rate limiting")]
    /// A public route cannot supply a verified principal or tenant bucket key.
    PublicEndpointIdentityRateLimit {
        /// The endpoint method.
        method: EndpointMethod,
        /// The endpoint route path.
        path: String,
    },
    #[error("invalid HTTP header name in {field}")]
    /// The header name is invalid.
    InvalidHeaderName {
        /// The configuration field name.
        field: &'static str,
        #[source]
        /// The source value.
        source: axum::http::header::InvalidHeaderName,
    },
    #[error("invalid rate limit key source in {field}")]
    /// The rate limit key source is invalid.
    InvalidRateLimitKeySource {
        #[doc = "The configuration field name."]
        field: &'static str,
    },
    #[error("request body limit must be greater than zero")]
    /// The request body limit is invalid.
    InvalidRequestBodyLimit,
    #[error(
        "HTTP route matcher must be an absolute ASCII path without whitespace, controls, query, fragment or backslash"
    )]
    /// The route matcher is invalid.
    InvalidRouteMatcher,
}

impl fmt::Debug for HttpMiddlewareError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("HttpMiddlewareError")
            .field("code", &self.error_code())
            .finish_non_exhaustive()
    }
}

impl ClassifyError for HttpMiddlewareError {
    fn error_kind(&self) -> ErrorKind {
        ErrorKind::Validation
    }

    fn error_code(&self) -> crate::result::ErrorCode {
        crate::result::ErrorCode::internal(match self {
            Self::MissingRateLimitStore => "http_rate_limit_store_required",
            Self::MissingIdempotencyStore => "http_idempotency_store_required",
            Self::MissingAuthenticationHook => "http_authentication_hook_required",
            Self::EndpointContractRateLimitMismatch { .. } => {
                "http_endpoint_contract_rate_limit_mismatch"
            }
            Self::EndpointContractIdempotencyMismatch { .. } => {
                "http_endpoint_contract_idempotency_mismatch"
            }
            Self::EndpointContractAuthenticationRequired { .. } => {
                "http_endpoint_contract_authentication_required"
            }
            Self::EndpointContractAuthorizationRequired { .. } => {
                "http_endpoint_contract_authorization_required"
            }
            Self::PublicEndpointIdentityRateLimit { .. } => {
                "http_public_endpoint_identity_rate_limit"
            }
            Self::InvalidHeaderName { .. } => "http_invalid_header_name",
            Self::InvalidRateLimitKeySource { .. } => "http_invalid_rate_limit_key_source",
            Self::InvalidRequestBodyLimit => "http_invalid_request_body_limit",
            Self::InvalidRouteMatcher => "http_invalid_route_matcher",
        })
    }
}