footing 0.6.6

Feature-gated foundations for Rust backend services
Documentation
//! Explicit API routing errors with request correlation.
//!
//! Install [`route_not_found`] with [`axum::Router::fallback`] and
//! [`method_not_allowed`] with [`axum::Router::method_not_allowed_fallback`].
//! Both return RFC 9457 problems with fixed messages and the current
//! [`RequestContext`]; request paths, query strings and method tokens are not
//! reflected. Axum supplies the route's `Allow` header for 405 responses and
//! removes the response body for HEAD requests.
//!
//! Register the method fallback **after all API routes**, because Axum applies
//! it only to routes registered so far. Install middleware after both fallbacks
//! so it also handles routing errors. `route_layer` only covers matched routes;
//! use `layer` when routing errors need the same request context and response
//! headers as successful requests.
//!
//! ```
//! use axum::{Router, middleware::from_fn, routing::{any, get}};
//! use footing::http::{
//!     method_not_allowed, request_context_middleware, route_not_found,
//! };
//!
//! let api = Router::new()
//!     .route("/health", get(|| async { "ok" }))
//!     .fallback(route_not_found)
//!     .method_not_allowed_fallback(method_not_allowed);
//! let app: Router = Router::new()
//!     .nest("/api", api)
//!     // Axum treats /api and /api/ as distinct mount paths.
//!     .route("/api/", any(route_not_found))
//!     .layer(from_fn(request_context_middleware));
//! ```
//!
//! For a frontend with SPA fallback, keep its file service on the outer
//! router's `fallback_service`, before installing the outer middleware. The
//! nested API fallback handles `/api` and unknown paths below `/api/`, but
//! Axum's nesting at `/api` does **not** match the trailing-slash path `/api/`.
//! The explicit route above reserves that path, preventing it from falling
//! through to frontend HTML. The frontend should also reserve API prefixes in
//! its routing configuration. Choose these mount paths explicitly; the handlers
//! do not normalize paths or install routes themselves.
//!
//! These handlers do not inspect or rewrite responses returned by matched
//! business handlers. Application-specific route and method fallbacks remain
//! explicit choices; installing these handlers is never automatic.

use super::{ApiProblem, ProblemCode, RequestContext};

/// Returns a `404 Not Found` problem for an unmatched API route.
///
/// Pass this handler to [`axum::Router::fallback`]. Its stable problem code is
/// `route_not_found`; its detail does not include the requested URI.
///
/// Existing request context is reused. When absent, the [`RequestContext`]
/// extractor creates one from validated request headers. Install
/// [`super::request_context_middleware`] after the fallback to also emit the
/// request ID in response headers.
pub async fn route_not_found(context: RequestContext) -> ApiProblem {
    const CODE: ProblemCode = ProblemCode::from_static("route_not_found");
    ApiProblem::not_found(CODE, "route not found").with_request_context(&context)
}

/// Returns a `405 Method Not Allowed` problem for a matched API route.
///
/// Pass this handler to [`axum::Router::method_not_allowed_fallback`] after
/// registering routes, or to an individual [`axum::routing::MethodRouter::fallback`].
/// Axum supplies the `Allow` header from the route's registered methods; this
/// handler does not guess or overwrite it. Its stable problem code is
/// `method_not_allowed`, with no request method or URI in its detail.
///
/// Request context follows the same behavior as [`route_not_found`].
pub async fn method_not_allowed(context: RequestContext) -> ApiProblem {
    const CODE: ProblemCode = ProblemCode::from_static("method_not_allowed");
    ApiProblem::method_not_allowed(CODE, "method not allowed").with_request_context(&context)
}