shared_framework/controller/

mod.rs

//! HTTP routing and controllers built on Hyper.
//!
//! Key types: [`Router`] dispatches requests, [`RouteController`] groups routes
//! under a base path and version, [`RouteDescription`] declares documentation,
//! validation, and rate-limit metadata, and [`Middleware`] runs before handlers.
//!
//! Request lifecycle: Hyper accepts a connection, the body, query parameters, and
//! headers are attached to a [`CorrelationContext`](CorrelationContext),
//! global middlewares run, the matching route's middlewares run, then the handler
//! receives only the context and returns `Result<ServiceResult<T>, ErrorResult>`.
//!
//! Handlers read input off the context (`ctx.body::<T>()`, `ctx.header()`,
//! `ctx.query_param()`) and return [`ServiceResult`](ServiceResult)
//! or a boxed [`TypedServiceResult`](TypedServiceResult).
//! ```ignore
//! // ctx: CorrelationContext
//! // let dto = ctx.body::<CreateUser>()?;
//! // Ok(ServiceResult::ok("Created", dto))
//! ```

pub mod errors;

use futures::FutureExt;
use std::collections::HashMap;
use std::net::SocketAddr;
use std::sync::{
    Arc, OnceLock,
    atomic::{AtomicBool, AtomicUsize, Ordering},
};

use crate::doc::{DocumentableDTO, DocumentationRegistrant};
use crate::logging::CorrelationContext;
use crate::middleware::rate::{RateLimiter, create_from_env};
use crate::response::{ErrorResult, ResponseType, ServiceResult, TypedServiceResult};
use crate::validation::Validate;
use http::{HeaderMap, Method, Request, Response};
use http_body_util::BodyExt;
use hyper::body::Incoming;
use hyper::server::conn::http1;
use hyper::service::service_fn;
use hyper_util::rt::TokioIo;
use schemars::generate::SchemaSettings;
use serde_json::Value;
use tokio::net::TcpListener;
use tracing::{info, warn};

#[derive(Clone)]
struct Holder {
    path: String,
    limit: u32,
}

/// Documented DTO payload: its JSON Schema, example value, and Rust type name.
/// Used for request bodies and response examples in generated documentation.
#[derive(Clone, Debug)]
pub struct DtoEntity {
    pub(crate) schema: Value,
    pub(crate) example: Value,
    pub(crate) name: &'static str,
}

/// Declared file-upload kind for a multipart file parameter.
/// Determines the example extension list reported in the documentation.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum FileParameterType {
    /// Image files (e.g. `.png, .jpg, .jpeg, .gif, .webp`).
    Image,
    /// Document files (e.g. `.pdf, .doc, .docx, .txt`).
    Document,
    /// Spreadsheet or CSV files (e.g. `.xls, .xlsx, .csv`).
    Spreadsheet,
    /// Video files (e.g. `.mp4, .mov, .avi`).
    Video,
    /// Audio files (e.g. `.mp3, .wav, .aac`).
    Audio,
    /// Archive files (e.g. `.zip, .tar, .gz`).
    Archive,
    /// Any file extension is accepted.
    Any,
}

impl FileParameterType {
    /// Returns the example extension list shown in documentation for this file kind.
    pub fn allowed_extensions_example(&self) -> &'static str {
        match self {
            Self::Image => ".png, .jpg, .jpeg, .gif, .webp",
            Self::Document => ".pdf, .doc, .docx, .txt",
            Self::Spreadsheet => ".xls, .xlsx, .csv",
            Self::Video => ".mp4, .mov, .avi",
            Self::Audio => ".mp3, .wav, .aac",
            Self::Archive => ".zip, .tar, .gz",
            Self::Any => "Any extension",
        }
    }
}

/// File-upload declaration for a multipart route: the part of the name, a description,
/// the accepted file kind, and optional send caps enforced before the handler runs.
#[derive(Clone, Debug)]
pub struct FileParameter {
    /// Multipart part name this declaration applies to.
    pub name: String,
    /// Human-readable description shown in documentation.
    pub description: String,
    /// Accepted file kind, used for the documented extension hint.
    pub file_type: FileParameterType,
    /// Maximum times this part may be sent; enforced as a 400 rejection when exceeded.
    pub count: Option<u32>,
    /// Optional size or count limit recorded for documentation.
    pub limit: Option<u32>,
}

/// Declarative metadata for one route: documentation, validation, and policy.
/// A description is registered for docs generation, declares the expected request
/// body (required when `has_body` is set on mount), response examples, params,
/// file parts, rate limit, and auth notes. Build with the `new` constructor and
/// the `group` / `with_body` / `response` / `header` / `query_param` builders.
#[derive(Debug, Clone)]
pub struct RouteDescription {
    /// Documentation group this route belongs to; also seeds the default tag.
    pub group: String,
    /// Route name; kept in sync with `summary` by [`RouteDescription::name`].
    pub name: String,
    /// Long-form description shown in documentation.
    pub description: String,
    /// Declared request-body DTO schema and example, if the route takes a body.
    pub request_body: Option<DtoEntity>,
    /// Response examples keyed by HTTP status code.
    pub response_examples: HashMap<u16, DtoEntity>,
    /// Documented request headers as name-to-description pairs.
    pub headers: HashMap<String, String>,
    /// Documented path parameters as name-to-description pairs.
    pub path_parameters: HashMap<String, String>,
    /// Default values for documented path parameters.
    pub path_parameter_defaults: HashMap<String, String>,
    /// Documented query parameters as name-to-description pairs.
    pub query_parameters: HashMap<String, String>,
    /// Default values for documented query parameters.
    pub query_parameter_defaults: HashMap<String, String>,
    /// Declared multipart file parameters keyed by part name.
    pub file_parameters: HashMap<String, FileParameter>,
    /// Per-route request cap; `None` means no route-level limit is installed.
    pub rate_limit: Option<u32>,
    /// Whether callers must authenticate; enforced by middleware, not by this struct.
    pub authentication_required: bool,
    /// Optional note explaining the authentication requirement.
    pub authentication_comment: Option<String>,
    /// Short summary shown in documentation; defaults to the name.
    pub summary: String,
    /// Documentation tags used for grouping; defaults to the group name.
    pub tags: Vec<String>,
    /// Marks the route as deprecated in documentation.
    pub is_deprecated: bool,
}

impl RouteDescription {
    /// Creates a description with the given summary; group and tags default to `"Default"`.
    pub fn new(summary: impl Into<String>) -> Self {
        let s = summary.into();
        Self {
            group: "Default".to_string(),
            name: s.clone(),
            description: String::new(),
            request_body: None,
            response_examples: Default::default(),
            headers: Default::default(),
            path_parameters: Default::default(),
            path_parameter_defaults: Default::default(),
            query_parameters: Default::default(),
            query_parameter_defaults: Default::default(),
            file_parameters: Default::default(),
            rate_limit: None,
            authentication_required: false,
            authentication_comment: None,
            summary: s.clone(),
            tags: vec!["Default".to_string()],
            is_deprecated: false,
        }
    }
    /// Sets the documentation group and resets the tag list to that group.
    pub fn group(mut self, group: impl Into<String>) -> Self {
        let g = group.into();
        self.group = g.clone();
        self.tags = vec![g];
        self
    }
    /// Sets the route name and copies it into the summary.
    pub fn name(mut self, name: impl Into<String>) -> Self {
        let n = name.into();
        self.name = n.clone();
        self.summary = n;
        self
    }
    /// Sets the long-form description shown in documentation.
    pub fn description(mut self, desc: impl Into<String>) -> Self {
        self.description = desc.into();
        self
    }
    /// Sets the per-route request cap enforced by the router's rate-limit middleware.
    pub fn with_rate_limit(mut self, limit: u32) -> Self {
        self.rate_limit = Some(limit);
        self
    }
    /// Sets the per-route request cap (alias for [`RouteDescription::with_rate_limit`]).
    pub fn rate_limit(mut self, limit: u32) -> Self {
        self.rate_limit = Some(limit);
        self
    }
    /// Declares the request-body DTO type `T`: records its JSON Schema and example.
    /// Required when the route is mounted with `has_body`; `T` must also be validatable.
    pub fn with_body<T>(mut self) -> Self
    where
        T: DocumentableDTO + Validate,
    {
        let settings = SchemaSettings::openapi3();
        let generator = settings.into_generator();
        let schema = generator.into_root_schema_for::<T>();
        let example = T::make_example();
        self.request_body = Some(DtoEntity {
            schema: schema.to_value(),
            example: example.unwrap(),
            name: std::any::type_name::<T>(),
        });
        self
    }
    /// Records whether callers must authenticate (informational; enforced by middleware).
    pub fn authentication(mut self, required: bool) -> Self {
        self.authentication_required = required;
        self
    }

    /// Records a response example for `code` using DTO type `T`'s schema and example.
    pub fn response<T>(mut self, code: u16) -> Self
    where
        T: DocumentableDTO,
    {
        let settings = SchemaSettings::openapi3();
        let generator = settings.into_generator();
        let schema = generator.into_root_schema_for::<T>();
        let example = T::make_example();
        let response = DtoEntity {
            schema: schema.to_value(),
            example: example.unwrap(),
            name: std::any::type_name::<T>(),
        };
        self.response_examples.insert(code, response);
        self
    }
    /// Records whether callers must authenticate (alias for [`RouteDescription::authentication`]).
    pub fn authentication_required(mut self, required: bool) -> Self {
        self.authentication_required = required;
        self
    }
    /// Attaches an explanatory note about the authentication requirement.
    pub fn authentication_comment(mut self, comment: impl Into<String>) -> Self {
        self.authentication_comment = Some(comment.into());
        self
    }
    /// Documents one expected request header as a name-to-description entry.
    pub fn header(mut self, k: impl Into<String>, v: impl Into<String>) -> Self {
        self.headers.insert(k.into(), v.into());
        self
    }
    /// Documents one path parameter as a name-to-description entry.
    pub fn path_param(mut self, k: impl Into<String>, v: impl Into<String>) -> Self {
        self.path_parameters.insert(k.into(), v.into());
        self
    }
    /// Documents one path parameter together with its default value.
    pub fn path_param_with_default(
        mut self,
        k: impl Into<String>,
        v: impl Into<String>,
        default: impl Into<String>,
    ) -> Self {
        let k = k.into();
        self.path_parameters.insert(k.clone(), v.into());
        self.path_parameter_defaults.insert(k, default.into());
        self
    }
    /// Documents one query parameter as a name-to-description entry.
    pub fn query_param(mut self, k: impl Into<String>, v: impl Into<String>) -> Self {
        self.query_parameters.insert(k.into(), v.into());
        self
    }
    /// Documents one query parameter together with its default value.
    pub fn query_param_with_default(
        mut self,
        k: impl Into<String>,
        v: impl Into<String>,
        default: impl Into<String>,
    ) -> Self {
        let k = k.into();
        self.query_parameters.insert(k.clone(), v.into());
        self.query_parameter_defaults.insert(k, default.into());
        self
    }
    /// Declares an accepted multipart file part without total send caps.
    pub fn file_param(
        mut self,
        name: impl Into<String>,
        description: impl Into<String>,
        file_type: FileParameterType,
    ) -> Self {
        let name = name.into();
        self.file_parameters.insert(
            name.clone(),
            FileParameter {
                name,
                description: description.into(),
                file_type,
                count: None,
                limit: None,
            },
        );
        self
    }
    /// Declares an accepted multipart file part with sending limits.
    /// Panics if `limit` or `count` is zero; a `count` overrun rejects the request with a 400.
    pub fn file_param_with_limit(
        mut self,
        name: impl Into<String>,
        description: impl Into<String>,
        file_type: FileParameterType,
        limit: u32,
        count: u32,
    ) -> Self {
        let name = name.into();
        assert!(limit >= 1, "File parameter limit must be greater than 0");
        assert!(count >= 1, "File parameter count must be greater than 0");
        self.file_parameters.insert(
            name.clone(),
            FileParameter {
                name,
                description: description.into(),
                file_type,
                count: Some(count),
                limit: Some(limit),
            },
        );
        self
    }
    /// Marks the route as deprecated (`true`) or not (`false`) in documentation.
    pub fn deprecated(mut self, deprecated: bool) -> Self {
        self.is_deprecated = deprecated;
        self
    }
    /// Adds a documentation tag unless it is already present.
    pub fn tag(mut self, tag: impl Into<String>) -> Self {
        let t = tag.into();
        if !self.tags.contains(&t) {
            self.tags.push(t);
        }
        self
    }
    /// Returns the per-route limit when set, otherwise the given global limit.
    pub fn effective_rate_limit(&self, global: Option<u32>) -> Option<u32> {
        self.rate_limit.or(global)
    }
}

impl Default for RouteDescription {
    fn default() -> Self {
        Self::new("No description")
    }
}

// ── Global state ───────────────────────────────────────────────────────────

static TOTAL_COUNT: AtomicUsize = AtomicUsize::new(0);
static LIMITER: OnceLock<Arc<dyn RateLimiter>> = OnceLock::new();
static MOUNTED_HANDLERS: AtomicBool = AtomicBool::new(false);

// ── Middleware / Handler types ───────────────────────────────────────────────
/// Pre-handler hook: inspects or mutates the context and headers, returning `Ok(())`
/// to continue or `Err(ErrorResult)` to short-circuit with an error response.
pub type Middleware = Arc<
    dyn for<'a> Fn(
            &'a mut CorrelationContext,
        ) -> futures::future::BoxFuture<'a, Result<(), ErrorResult>>
        + Send
        + Sync,
>;

/// Low-level route handler used by the dispatcher: receives the prepared context
/// plus raw headers, method, path, and body bytes, and returns a complete HTTP response.
pub type BoxHandler = Arc<
    dyn Fn(
            CorrelationContext,
            HeaderMap,
            Method,
            String,
            Vec<u8>,
        ) -> futures::future::BoxFuture<'static, Response<String>>
        + Send
        + Sync,
>;

// ── RouteEntry / Router ──────────────────────────────────────────────────────
pub(crate) struct RouteEntry {
    method: Method,
    path: String,
    handler: BoxHandler,
    middlewares: Vec<Middleware>,
}

#[derive(Default)]
struct TrieNode {
    static_children: HashMap<String, TrieNode>,
    param_child: Option<(String, Box<TrieNode>)>, // (param name, subtree)
    wildcard_routes: HashMap<Method, RouteEntry>, // method -> route, for a "/*" mounted here
    exact_routes: HashMap<Method, RouteEntry>,    // method -> route, for a path ending here
}

/// Hyper-backed route registry: stores routes with per-route middlewares,
/// runs global middlewares for every request, and dispatches by method and path.
/// A trailing `/*` on a route path acts as a prefix wildcard when matching.
pub struct Router {
    root: TrieNode,
    global_middlewares: Vec<Middleware>,

    /// Reserved test-execution hook for documentation-driven test clients.
    /// When installed and the request carries the test-client header, this handler
    /// runs instead of the matched route.
    test_client_handler: Option<BoxHandler>,
}

impl Router {
    /// Creates an empty router with no routes and no global middlewares.
    pub fn new() -> Self {
        Self {
            root: TrieNode::default(),
            global_middlewares: Vec::new(),
            test_client_handler: None,
        }
    }

    /// Registers a route in the trie, indexed by its path segments and method.
    ///
    /// The path is split on `/` (leading/trailing slashes and empty segments from
    /// repeated `/` are ignored). Each segment is classified as one of:
    ///
    /// - **Static** (`users`, `settings`) — matched literally.
    /// - **Param** (`:id`, `:slug`) — matches any single non-empty segment; the
    ///   name keys the captured value after the colon.
    /// - **Wildcard** (`*`) — must be the final segment; matches the remainder of
    ///   the path, including zero remaining segments.
    ///
    /// Method keys routes at the node where their path terminates, so
    /// registering the same path with different methods (e.g. `GET /users/:id`
    /// and `POST /users/:id`) is expected and does not conflict.
    ///
    /// # Precedence
    ///
    /// Insertion order does not affect resolution order. At lookup time, static
    /// segments are always preferred over a param segment at the same position,
    /// which is preferred over a wildcard — this is enforced by the trie
    /// structure itself, not by the order routes are inserted here.
    ///
    /// # Panics
    ///
    /// In debug builds, panics if a param segment is inserted at a trie position
    /// that already holds a param child with a *different* name (e.g., inserting
    /// both `/users/:id` and `/users/:userId`). This check is compiled out in
    /// release builds — conflicting names will silently take the first
    /// registered name instead.
    ///
    /// # Examples
    ///
    /// ```
    /// use http::Method;
    /// router.insert(crate::shared_framework::controller::RouteEntry { method: Method::GET, path: "/users/:id".into(), .. });
    /// router.insert(crate::shared_framework::controller::RouteEntry { method: Method::GET, path: "/users/active".into(), .. });
    /// router.insert(crate::shared_framework::controller::RouteEntry { method: Method::GET, path: "/admin/*".into(), .. });
    /// ```
    pub(crate) fn insert(&mut self, route: RouteEntry) {
        let segments: Vec<String> = route
            .path
            .trim_matches('/')
            .split('/')
            .filter(|s| !s.is_empty())
            .map(String::from)
            .collect();
        Self::insert_at(&mut self.root, &segments, route);
    }

    fn insert_at(node: &mut TrieNode, segments: &[String], route: RouteEntry) {
        match segments.split_first() {
            None => {
                node.exact_routes.insert(route.method.clone(), route);
            }
            Some((seg, _rest)) if seg == "*" => {
                node.wildcard_routes.insert(route.method.clone(), route);
            }
            Some((seg, rest)) if seg.starts_with(':') => {
                let name = seg[1..].to_string();
                let (existing_name, child) = node
                    .param_child
                    .get_or_insert_with(|| (name.clone(), Box::new(TrieNode::default())));
                debug_assert_eq!(
                    existing_name, &name,
                    "conflicting param names at same position: {existing_name} vs {name}"
                );
                Self::insert_at(child, rest, route);
            }
            Some((seg, rest)) => {
                let child = node.static_children.entry(seg.clone()).or_default();
                Self::insert_at(child, rest, route);
            }
        }
    }

    /// Resolves an incoming request to a registered route, extracting any path
    /// parameters along the way.
    ///
    /// The path is normalized (see [`normalize_path`]) and split into segments
    /// before matching. Matching descends the trie one segment at a time,
    /// preferring branches in this order at each level:
    ///
    /// 1. **Static** children — exact segment match.
    /// 2. **Param** child — matches any segment, capturing its value.
    /// 3. **Wildcard** — matches all remaining segments (including none).
    ///
    /// If a static branch matches part of the path but fails to produce a full
    /// match further down, resolution backtracks and retries via the param
    /// branch at that level before falling back to the wildcard. This ensures a
    /// route like `/users/:id/settings` is still reachable even when a sibling
    /// static route `/users/active` exists but doesn't match past the first
    /// segment.
    ///
    /// The method is checked only at the point a path fully matches (an exact
    /// route or a wildcard boundary) — a path that matches some route's shape
    /// but not under the requested method resolves to `None`, indistinguishable
    /// from no matching path at all.
    ///
    /// # Returns
    ///
    /// `Some((route, params))` on a match, where `params` maps each `:name`
    /// segment in the matched route's path to the corresponding literal value
    /// from the request path. Returns `None` if no route matches the given
    /// method and path.
    ///
    /// # Examples
    ///
    /// ```
    /// let (route, params) = router.resolve("GET", "/users/42").unwrap();
    /// assert_eq!(params["id"], "42");
    /// ```
    ///
    /// # Warnings
    /// - Path segments are not percent-decoded; encoded characters (e.g. `%20`)
    ///   are returned as-is in extracted params.
    /// - Does not distinguish a path that exists under a different method from a
    ///   path that doesn't exist at all — both return `None`.
    pub(crate) fn resolve(
        &self,
        method: &Method,
        path: &str,
    ) -> Option<(&RouteEntry, HashMap<String, String>)> {
        let normal_path = normalize_path(path);
        let segments: Vec<&str> = normal_path
            .trim_matches('/')
            .split('/')
            .filter(|s| !s.is_empty())
            .collect();

        let mut params = Vec::new();
        let route = Self::find(&self.root, &segments, method, &mut params)?;
        Some((route, params.into_iter().collect()))
    }

    /// Installs the reserved test-client interceptor used for documentation-driven test runs.
    pub fn set_test_client_handler(&mut self, handler: BoxHandler) {
        self.test_client_handler = Some(handler);
    }

    fn ensure_global_middleware(&mut self) {
        if MOUNTED_HANDLERS
            .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
            .is_ok()
        {
            self.global_middlewares.push(Arc::new(|ctx| {
                async move {
                    if ctx.request_id().is_empty() {
                        let rid = hex::encode(rand::random::<[u8; 8]>());
                        ctx.set_request_id(&rid);
                    }
                    Ok(())
                }
                .boxed()
            }));
            self.global_middlewares.push(Arc::new(|ctx| {
                async move {
                    let headers = ctx.headers();
                    if let Some(v) = headers
                        .get("x-correlation-id")
                        .and_then(|h| h.to_str().ok())
                    {
                        if !v.is_empty() {
                            ctx.set_correlation_id(v);
                        }
                    }
                    if let Some(v) = headers
                        .get("x-correlation-flow")
                        .and_then(|h| h.to_str().ok())
                    {
                        if let Ok(flow) = v.parse::<crate::logging::CorrelationFlow>() {
                            ctx.set_flow(flow);
                        }
                    }
                    Ok(())
                }
                .boxed()
            }));
        }
    }

    /// Registers a typed handler at `base_path` + version + `path` for `method`.
    ///
    /// Type parameter `T` is the `ServiceResult` payload; `F`/`Fut` describes the
    /// `Fn(CorrelationContext)` async handler returning `Result<ServiceResult<T>, ErrorResult>`.
    /// The handler receives only the context: body, headers, and query parameters are
    /// attached at dispatch, so use `ctx.body::<T>()`, `ctx.header()`, or `ctx.query_param()`.
    /// Registers the description for documentation, installs per-route rate-limit
    /// middleware when `description.rate_limit` is set, and enforces declared file-part
    /// `count` caps before the handler runs.
    ///
    /// Panics if `has_body` is set without a declared request body or file parameter.
    /// ```ignore
    /// router.mount("/users", 1, "/:id", false, Method::GET, desc, handler, vec![]);
    /// ```
    pub fn mount<T, F, Fut>(
        &mut self,
        base_path: &str,
        version: u32,
        path: &str,
        has_body: bool,
        method: Method,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        self.ensure_global_middleware();
        let full_path = calculate_full_path(base_path, version, path);
        let meta_path = Holder {
            path: full_path.to_string(),
            limit: description.rate_limit.unwrap_or(0),
        };

        if let Ok(mut reg) = DocumentationRegistrant::global().write() {
            reg.register_route(
                &full_path,
                method.as_str(),
                "Controller",
                description.clone(),
            );
        }

        if has_body {
            let expected = description.request_body.clone();
            // File-only routes satisfy the body contract through file_parameters.
            if expected.is_none() && description.file_parameters.is_empty() {
                panic!(
                    "Request body class must be specified in the route description for {}",
                    full_path
                );
            }
        }

        let mut all_middlewares = Vec::new();
        if let Some(limit) = description.rate_limit {
            if limit > 0 {
                let path_clone = meta_path.clone();

                let m: Middleware = Arc::new(move |ctx: &mut CorrelationContext| {
                    let headers = ctx.headers();
                    let path_inner = path_clone.clone();
                    let fut = async move {
                        let limiter = LIMITER.get_or_init(|| create_from_env()).clone();
                        let key = ctx.user_id().unwrap_or_else(|| {
                            headers
                                .get("x-forwarded-for")
                                .and_then(|v| v.to_str().ok())
                                .unwrap_or("anonymous")
                                .to_string()
                        }) + ":"
                            + &path_inner.path;
                        if limiter.is_allowed(&key, path_inner.limit).await {
                            return Ok(());
                        }
                        Err(ErrorResult::from_error(
                            "Too many requests. Please try again later.",
                            429,
                        ))
                    };

                    // Explicitly force the BoxFuture type to drop any inferred lifetime relationships
                    // linked to the arguments ctx or headers
                    FutureExt::boxed(fut)
                });
                all_middlewares.push(m);
            }
        }
        all_middlewares.extend(middlewares);

        // Declared per-parameter send caps (`FileParameter.count`), enforced in
        // place before the handler runs just like body validation.
        let file_counts: Vec<(String, u32)> = description
            .file_parameters
            .iter()
            .filter_map(|(name, p)| p.count.map(|c| (name.clone(), c)))
            .collect();
        let handler = Arc::new(handler);

        let boxed: BoxHandler = Arc::new(move |ctx, _headers, _method, _path, _body| {
            let file_counts = file_counts.clone();
            let handler = handler.clone();
            Box::pin(async move {
                let ctx = Arc::new(ctx);
                if let Some(err) = file_count_violation(ctx.clone(), &file_counts) {
                    return crate::response::error_response(&err, ctx.clone());
                }
                match handler((*ctx).clone()).await {
                    Ok(typed) => {
                        let body = match typed.serialize() {
                            Ok(b) => b,
                            Err(e) => {
                                let err =
                                    ErrorResult::from_error(&anyhow::anyhow!(e.to_string()), 500);
                                return crate::response::error_response(&err, ctx.clone());
                            }
                        };
                        if body.is_empty() {
                            let err = ErrorResult::new("Response body is null", None, 503);
                            return crate::response::error_response(&err, ctx.clone());
                        }
                        let mut builder = Response::builder()
                            .status(typed.code())
                            .header("X-Request-ID", ctx.request_id())
                            .header("X-Correlation-ID", ctx.correlation_id())
                            .header("X-Correlation-Flow", ctx.flow().to_string());
                        let ct = match typed.response_type() {
                            ResponseType::Json => "application/json",
                            ResponseType::File => {
                                let filename = body.rsplit('/').next().unwrap_or("file");
                                builder = builder.header(
                                    "Content-Disposition",
                                    format!("attachment; filename=\"{}\"", filename),
                                );
                                "application/octet-stream"
                            }
                            ResponseType::Xml => "application/xml",
                            ResponseType::Javascript => "application/javascript",
                            ResponseType::Html => "text/html",
                            ResponseType::Text => "text/plain",
                        };
                        builder = builder.header("Content-Type", ct);
                        builder.body(body).unwrap()
                    }
                    Err(e) => crate::response::error_response(&e, ctx.clone()),
                }
            })
        });

        self.insert(RouteEntry {
            method: method.clone(),
            path: full_path.clone(),
            handler: boxed,
            middlewares: all_middlewares,
        });
        info!(
            target: "routing",
            handler = "Controller",
            method = method.as_str(),
            path = %full_path,
            "Mounted a '{}' handler which listens on  '{}'",
            method.as_str(),
            full_path
        );
        TOTAL_COUNT.fetch_add(1, Ordering::SeqCst);
    }

    /// Registers a handler returning heterogeneous payloads as `Box<dyn TypedServiceResult>`.
    /// Use this when one handler returns different `ServiceResult<T>` shapes; prefer
    /// [`Router::mount`] when the result type is statically known.
    /// Like [`Router::mount`], the handler takes only the [`CorrelationContext`].
    pub fn mount_typed<F, Fut>(
        &mut self,
        base_path: &str,
        version: u32,
        path: &str,
        method: Method,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<Box<dyn TypedServiceResult>, ErrorResult>> + Send + 'static,
    {
        self.ensure_global_middleware();
        let full_path = calculate_full_path(base_path, version, path);
        let meta_path = Holder {
            path: full_path.to_string(),
            limit: description.rate_limit.unwrap_or(0),
        };

        if let Ok(mut reg) = DocumentationRegistrant::global().write() {
            reg.register_route(
                &full_path,
                method.as_str(),
                "Controller",
                description.clone(),
            );
        }

        let mut all_middlewares = Vec::new();
        if let Some(limit) = description.rate_limit {
            if limit > 0 {
                let path_clone = meta_path.clone();
                let m: Middleware = Arc::new(move |ctx: &mut CorrelationContext| {
                    let headers = ctx.headers();
                    let path_inner = path_clone.clone();
                    let fut = async move {
                        let limiter = LIMITER.get_or_init(|| create_from_env()).clone();
                        let key = ctx.user_id().unwrap_or_else(|| {
                            headers
                                .get("x-forwarded-for")
                                .and_then(|v| v.to_str().ok())
                                .unwrap_or("anonymous")
                                .to_string()
                        }) + ":"
                            + &path_inner.path;
                        if limiter.is_allowed(&key, path_inner.limit).await {
                            return Ok(());
                        }
                        Err(ErrorResult::from_error(
                            "Too many requests. Please try again later.",
                            429,
                        ))
                    };
                    FutureExt::boxed(fut)
                });
                all_middlewares.push(m);
            }
        }
        all_middlewares.extend(middlewares);

        // Declared per-parameter send caps (`FileParameter.count`), enforced in
        // place before the handler runs just like body validation.
        let file_counts: Vec<(String, u32)> = description
            .file_parameters
            .iter()
            .filter_map(|(name, p)| p.count.map(|c| (name.clone(), c)))
            .collect();
        let handler = Arc::new(handler);

        let boxed: BoxHandler = Arc::new(move |ctx, _headers, _method, _path, _body| {
            let file_counts = file_counts.clone();
            let handler = handler.clone();
            Box::pin(async move {
                let ctx = Arc::new(ctx);
                if let Some(err) = file_count_violation(ctx.clone(), &file_counts) {
                    return crate::response::error_response(&err, ctx.clone());
                }
                match handler((*ctx).clone()).await {
                    Ok(typed) => crate::response::build_response(typed.as_ref(), ctx.clone()),
                    Err(e) => crate::response::error_response(&e, ctx.clone()),
                }
            })
        });

        self.insert(RouteEntry {
            method: method.clone(),
            path: full_path.clone(),
            handler: boxed,
            middlewares: all_middlewares,
        });
        info!(
            handler = "Controller",
            method = method.as_str(),
            path = %full_path,
            "Mounted a '{}' handler which listens on  '{}'",
            method.as_str(),
            full_path
        );
        TOTAL_COUNT.fetch_add(1, Ordering::SeqCst);
    }

    /// Registers a pre-built [`BoxHandler`] at the resolved path with the given middlewares.
    /// A trailing `/*` on the resolved path acts as a prefix wildcard when matching.
    /// Unlike [`Router::mount`], this performs no docs registration and imposes no
    /// body contract, making it suitable for static-asset serving and custom handlers.
    pub fn mount_raw(
        &mut self,
        base_path: &str,
        version: u32,
        path: &str,
        method: Method,
        handler: BoxHandler,
        middlewares: Vec<Middleware>,
    ) {
        self.ensure_global_middleware();
        let full_path = calculate_full_path(base_path, version, path);
        self.insert(RouteEntry {
            method: method.clone(),
            path: full_path.clone(),
            handler,
            middlewares,
        });
        info!(
            handler = "raw",
            method = method.as_str(),
            path = %full_path,
            "Mounted a '{}' handler which listens on  '{}'",
            method.as_str(),
            full_path
        );
        TOTAL_COUNT.fetch_add(1, Ordering::SeqCst);
    }

    /// Serves files under `fs_path` at `base_path` + version + `path` with a `/*` wildcard.
    /// Requests for `/` resolve to `index.html` when present; missing files fall back
    /// to a plain-text placeholder response instead of a 404.
    pub fn mount_static(
        &mut self,
        base_path: &str,
        version: u32,
        path: &str,
        fs_path: String,
        middlewares: Vec<Middleware>,
    ) {
        let full_path = if version == 0 {
            no_trailing_slash(&format!(
                "/{}/{}/*",
                base_path.trim_matches('/'),
                path.trim_matches('/')
            ))
        } else {
            no_trailing_slash(&format!(
                "/v{}/{}/{}/*",
                version,
                base_path.trim_matches('/'),
                path.trim_matches('/')
            ))
        };
        let fs_path_clone = fs_path.clone();
        let full_path_no_wildcard = full_path.trim_end_matches("/*").to_string();
        let handler: BoxHandler = Arc::new(move |ctx, _headers, _method, req_path, _body| {
            let fs_path = fs_path_clone.clone();
            let req_path = req_path.clone();
            let ctx = ctx.clone();
            let prefix = full_path_no_wildcard.clone();
            Box::pin(async move {
                let rel = req_path.trim_start_matches(&prefix).trim_start_matches('/');
                // Resolve to a real file under fs_path when present (Swagger UI `doc/` dir).
                let candidates = if rel.is_empty() {
                    vec![
                        format!("{}/index.html", fs_path.trim_end_matches('/')),
                        fs_path.clone(),
                    ]
                } else {
                    vec![format!("{}/{}", fs_path.trim_end_matches('/'), rel)]
                };
                for candidate in &candidates {
                    if let Ok(bytes) = std::fs::read(candidate) {
                        let ct = guess_content_type(candidate);
                        let body = String::from_utf8_lossy(&bytes).into_owned();
                        return Response::builder()
                            .status(200)
                            .header("X-Request-ID", ctx.request_id())
                            .header("Content-Type", ct)
                            .body(body)
                            .unwrap();
                    }
                }
                // Fallback placeholder (keeps offline/dev behavior useful)
                let file_path = if rel.is_empty() {
                    fs_path.clone()
                } else {
                    format!("{}/{}", fs_path.trim_end_matches('/'), rel)
                };
                let typed = ServiceResult::new(
                    "success",
                    "OK",
                    Some(format!("Serving static file: {}", file_path)),
                    200,
                )
                .with_response_type(ResponseType::Text);
                let body = TypedServiceResult::serialize(&typed).unwrap();
                Response::builder()
                    .status(TypedServiceResult::code(&typed))
                    .header("X-Request-ID", ctx.request_id())
                    .header("Content-Type", "text/plain")
                    .body(body)
                    .unwrap()
            })
        });
        self.insert(RouteEntry {
            method: Method::GET,
            path: full_path.clone(),
            handler,
            middlewares,
        });
        info!(
            handler = "static",
            path = %full_path,
            "Mounted a '{}' handler which listens on  '{}'",
            "static file",
            full_path
        );
        TOTAL_COUNT.fetch_add(1, Ordering::SeqCst);
    }

    fn find<'a>(
        node: &'a TrieNode,
        segments: &[&str],
        method: &Method,
        params: &mut Vec<(String, String)>,
    ) -> Option<&'a RouteEntry> {
        match segments.split_first() {
            None => node
                .exact_routes
                .get(method)
                .or_else(|| node.wildcard_routes.get(method)),
            Some((seg, rest)) => {
                // static beats param beats wildcard, tried in that order with backtracking
                if let Some(child) = node.static_children.get(*seg) {
                    if let Some(r) = Self::find(child, rest, method, params) {
                        return Some(r);
                    }
                }

                if let Some((name, child)) = &node.param_child {
                    params.push((name.clone(), (*seg).to_string()));
                    if let Some(r) = Self::find(child, rest, method, params) {
                        return Some(r);
                    }
                    params.pop();
                }

                node.wildcard_routes.get(method)
            }
        }
    }
}

impl Default for Router {
    fn default() -> Self {
        Self::new()
    }
}

fn guess_content_type(path: &str) -> &'static str {
    let lower = path.to_ascii_lowercase();
    if lower.ends_with(".html") || lower.ends_with(".htm") {
        "text/html"
    } else if lower.ends_with(".js") {
        "application/javascript"
    } else if lower.ends_with(".css") {
        "text/css"
    } else if lower.ends_with(".json") {
        "application/json"
    } else if lower.ends_with(".png") {
        "image/png"
    } else if lower.ends_with(".jpg") || lower.ends_with(".jpeg") {
        "image/jpeg"
    } else if lower.ends_with(".svg") {
        "image/svg+xml"
    } else if lower.ends_with(".yaml") || lower.ends_with(".yml") {
        "application/yaml"
    } else {
        "text/plain"
    }
}
fn normalize_path(p: &str) -> String {
    let p = p.trim().replace("//", "/");
    if p.ends_with('/') && p.len() > 1 {
        p[..p.len() - 1].to_string()
    } else if p.is_empty() {
        "/".to_string()
    } else {
        p
    }
}
fn no_trailing_slash(path: &str) -> String {
    let p = path.trim().replace("//", "/");
    if p.is_empty() || p == "/" {
        return "/".to_string();
    }
    if p.ends_with('/') {
        p[..p.rfind('/').unwrap()].to_string()
    } else {
        p
    }
}
/// Enforce declared `FileParameter.count` caps against a dispatched context.
/// Counts every part bearing the parameter name (files plus text fields) —
/// `count` is the maximum number of times the parameter may be sent.
/// Non-multipart requests and undeclared parameters are never rejected.
fn file_count_violation(
    ctx: Arc<CorrelationContext>,
    counts: &[(String, u32)],
) -> Option<ErrorResult> {
    if counts.is_empty() {
        return None;
    }
    let mp = ctx.multipart()?;
    for (name, max) in counts {
        let occurrences = mp.files.iter().filter(|f| &f.field_name == name).count()
            + mp.fields.get(name).map_or(0, |v| v.len());
        if occurrences as u32 > *max {
            return Some(ErrorResult::bad_request(format!(
                "Too many '{}' parts: got {}, maximum is {}",
                name, occurrences, max
            )));
        }
    }
    None
}

fn calculate_full_path(base_path: &str, version: u32, path: &str) -> String {
    let decoded = if version == 0 {
        let dddd = no_trailing_slash(&format!(
            "/{}/{}",
            base_path.trim_matches('/'),
            path.trim_start_matches('/')
        ));
        urlencoding::decode(dddd.leak())
    } else {
        let dddd = no_trailing_slash(&format!(
            "/v{}/{}/{}",
            version,
            base_path.trim_matches('/'),
            path.trim_start_matches('/')
        ));
        urlencoding::decode(dddd.leak())
    };

    if decoded.is_err() {
        return base_path.to_string();
    }

    decoded.unwrap().to_string()
}

// ── RouteController trait ──────────────────────────────────────────────────

#[async_trait::async_trait]
/// Groups related routes under a shared base path and version.
/// Implement [`RouteController::base_path`] and [`RouteController::register_routes`];
/// override [`RouteController::version`] to prefix paths with `/v{version}`.
pub trait RouteController: Send + Sync {
    /// Base path prefix for every route registered by this controller.
    fn base_path(&self) -> &str;
    /// API version prefix; `0` means no `/v{version}` segment is added.
    fn version(&self) -> u32 {
        0
    }
    /// Resolves a relative `path` to its full mounted path including base path and version.
    fn full_path(&self, path: &str) -> String {
        calculate_full_path(self.base_path(), self.version(), path)
    }
    /// Registers this controller's routes on `router`, typically via [`RouteControllerExt`].
    async fn register_routes(&self, router: &mut Router);
    /// Default registration entry point; delegates to [`RouteController::register_routes`].
    async fn register(&self, router: &mut Router) {
        self.register_routes(router).await;
    }

    ///
    fn type_name(&self) -> &'static str {
        std::any::type_name::<Self>()
    }
}

/// Convenience mounts that fill in this controller's base path and version.
/// Each `mount_*` takes an `Fn(CorrelationContext)` handler returning
/// `Result<ServiceResult<T>, ErrorResult>`; the `*_typed` variants instead return
/// `Result<Box<dyn TypedServiceResult>, ErrorResult>` for heterogeneous payloads.
/// ```ignore
/// self.mount_get(&mut router, "/list", desc, handler, vec![]);
/// ```
pub trait RouteControllerExt: RouteController {
    /// Mounts a GET handler with no required body at `path`.
    fn mount_get<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::GET,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a POST handler; requires a declared request body or file parameter.
    fn mount_post<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            true,
            Method::POST,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a PUT handler; requires a declared request body or file parameter.
    fn mount_put<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            true,
            Method::PUT,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a PATCH handler; `has_body` selects whether a request body is required.
    fn mount_patch<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        has_body: bool,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            has_body,
            Method::PATCH,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a PATCH handler that requires a request body.
    fn mount_patch_with_body<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        self.mount_patch(router, path, true, description, handler, middlewares);
    }
    /// Mounts a PATCH handler that requires no request body.
    fn mount_patch_without_body<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        self.mount_patch(router, path, false, description, handler, middlewares);
    }
    /// Mounts a DELETE handler with no required body at `path`.
    fn mount_delete<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::DELETE,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts an OPTIONS handler with no required body at `path`.
    fn mount_options<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::OPTIONS,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a HEAD handler with no required body at `path`.
    fn mount_head<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::HEAD,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a TRACE handler with no required body at `path`.
    fn mount_trace<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::TRACE,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a CONNECT handler with no required body at `path`.
    fn mount_connect<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::CONNECT,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV COPY handler with no required body at `path`.
    fn mount_copy<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::from_bytes(b"COPY").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV MOVE handler with no required body at `path`.
    fn mount_move<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::from_bytes(b"MOVE").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV LOCK handler; requires a declared request body or file parameter.
    fn mount_lock<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            true,
            Method::from_bytes(b"LOCK").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV UNLOCK handler with no required body at `path`.
    fn mount_unlock<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::from_bytes(b"UNLOCK").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV PROPFIND handler; requires a declared request body or file parameter.
    fn mount_propfind<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            true,
            Method::from_bytes(b"PROPFIND").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV MKCOL handler with no required body at `path`.
    fn mount_mkcol<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::from_bytes(b"MKCOL").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV SEARCH handler; requires a declared request body or file parameter.
    fn mount_search<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            true,
            Method::from_bytes(b"SEARCH").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV REPORT handler; requires a declared request body or file parameter.
    fn mount_report<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            true,
            Method::from_bytes(b"REPORT").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a versioning CHECKIN handler with no required body at `path`.
    fn mount_checkin<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::from_bytes(b"CHECKIN").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a versioning CHECKOUT handler with no required body at `path`.
    fn mount_checkout<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::from_bytes(b"CHECKOUT").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a versioning UNCHECKOUT handler with no required body at `path`.
    fn mount_uncheckout<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            Method::from_bytes(b"UNCHECKOUT").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV MERGE handler; requires a declared request body or file parameter.
    fn mount_merge<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            true,
            Method::from_bytes(b"MERGE").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a WebDAV ACL handler; requires a declared request body or file parameter.
    fn mount_acl<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            true,
            Method::from_bytes(b"ACL").unwrap(),
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a handler for an arbitrary `method` with no required body at `path`.
    fn mount_custom<T, F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        method: Method,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        T: serde::Serialize + Send + Sync + 'static,
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<ServiceResult<T>, ErrorResult>> + Send + 'static,
    {
        router.mount(
            self.base_path(),
            self.version(),
            path,
            false,
            method,
            description,
            handler,
            middlewares,
        );
    }
    /// Serves files under `fs_path` at this controller's base path plus `path`.
    fn mount_static(
        &self,
        router: &mut Router,
        path: &str,
        fs_path: String,
        middlewares: Vec<Middleware>,
    ) {
        router.mount_static(self.base_path(), self.version(), path, fs_path, middlewares);
    }
    /// Mounts a handler returning `Box<dyn TypedServiceResult>` for heterogeneous payloads.
    fn mount_typed<F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        method: Method,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<Box<dyn TypedServiceResult>, ErrorResult>> + Send + 'static,
    {
        router.mount_typed(
            self.base_path(),
            self.version(),
            path,
            method,
            description,
            handler,
            middlewares,
        );
    }
    /// Mounts a boxed-result GET handler returning heterogeneous payloads.
    fn mount_get_typed<F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<Box<dyn TypedServiceResult>, ErrorResult>> + Send + 'static,
    {
        self.mount_typed(router, path, Method::GET, description, handler, middlewares);
    }
    /// Mounts a boxed-result POST handler returning heterogeneous payloads.
    fn mount_post_typed<F, Fut>(
        &self,
        router: &mut Router,
        path: &str,
        description: RouteDescription,
        handler: F,
        middlewares: Vec<Middleware>,
    ) where
        F: Fn(CorrelationContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<Box<dyn TypedServiceResult>, ErrorResult>> + Send + 'static,
    {
        self.mount_typed(
            router,
            path,
            Method::POST,
            description,
            handler,
            middlewares,
        );
    }
}
impl<T: RouteController> RouteControllerExt for T {}

// ── ConfigurationRegistrant — Hyper server bootstrap ───────────────────────

/// Hyper server bootstrap: owns the shared [`Router`] and the bind address.
/// Mount controllers and global middlewares, then call [`ConfigurationRegistrant::serve`].
/// ```ignore
/// let server = std::sync::Arc::new(ConfigurationRegistrant::new(addr));
/// server.mount_controller(MyController).await;
/// let bound = server.serve().await?;
/// ```
pub struct ConfigurationRegistrant {
    router: Arc<tokio::sync::RwLock<Router>>,
    addr: SocketAddr,
}

impl ConfigurationRegistrant {
    /// Creates a bootstrap with a fresh router bound to `addr` on [`ConfigurationRegistrant::serve`].
    pub fn new(addr: SocketAddr) -> Self {
        Self {
            router: Arc::new(tokio::sync::RwLock::new(Router::new())),
            addr,
        }
    }

    /// Registers every route of `controller` on the shared router.
    pub async fn mount_controller<C: RouteController + 'static>(&self, controller: C) {
        let mut r = self.router.write().await;
        info!(
            target: "routing",
            handler = std::any::type_name::<C>(),
            path = %controller.base_path(),
            "Mounted controller '{}' at '{}'",
            std::any::type_name::<C>(),
            controller.base_path()
        );
        controller.register_routes(&mut r).await;
    }

    /// Pushes a middleware that runs for every request before route matching.
    pub async fn mount_middleware(&self, _mw: Middleware) {
        let mut r = self.router.write().await;
        r.global_middlewares.push(_mw);
    }

    /// Binds the socket, spawns the Hyper accept loop in the background, and returns the bound address.
    /// Returns an error if the socket cannot be bound.
    pub async fn serve(self: Arc<Self>) -> anyhow::Result<SocketAddr> {
        let listener = TcpListener::bind(self.addr).await?;
        let addr = listener.local_addr()?;
        info!(address = %addr, "HTTP server listening");
        let router = self.router.clone();
        tokio::spawn(async move {
            loop {
                let (stream, remote) = match listener.accept().await {
                    Ok(v) => v,
                    Err(e) => {
                        warn!(error = %e, "Failed to accept HTTP connection");
                        continue;
                    }
                };
                let io = TokioIo::new(stream);
                let router = router.clone();
                tokio::spawn(async move {
                    let svc = service_fn(move |req: Request<Incoming>| {
                        let router = router.clone();
                        let remote = remote;
                        async move { handle_request(router, req, remote).await }
                    });
                    if let Err(e) = http1::Builder::new().serve_connection(io, svc).await {
                        tracing::debug!(remote_addr = %remote, error = %e, "HTTP connection ended with an error");
                    }
                });
            }
        });
        Ok(addr)
    }

    /// Returns a clone of the shared router handle for direct route registration.
    pub fn router_handle(&self) -> Arc<tokio::sync::RwLock<Router>> {
        self.router.clone()
    }
}

async fn handle_request(
    router: Arc<tokio::sync::RwLock<Router>>,
    req: Request<Incoming>,
    remote_addr: SocketAddr,
) -> Result<Response<String>, ErrorResult> {
    let request_started = std::time::Instant::now();
    let method = req.method().clone();
    let path = req.uri().path();
    let old_path = path;
    let path = urlencoding::decode(path);
    if path.is_err() {
        tracing::error!(
            "This should not be possible. Encountered an error while processing the URL {}",
            old_path
        );
        return Err(ErrorResult::bad_request("Invalid path parameter"));
    }
    let path = path.ok().unwrap().to_string();
    let query = req.uri().query().unwrap_or("").to_string();
    let headers = req.headers().clone();
    let (_parts, body) = req.into_parts();
    let body_bytes = match body.collect().await {
        Ok(collected) => collected.to_bytes().to_vec(),
        Err(e) => {
            warn!(remote_addr = %remote_addr, error = %e, "Failed to read request body");
            vec![]
        }
    };

    let params: HashMap<String, String> = serde_urlencoded::from_str(&query).unwrap_or_default();
    let mut ctx = build_correlation_context(&headers, &params, &body_bytes);

    // Decode multipart eagerly so handlers and middlewares read fields/files
    // off the context via `form_field`/`files` and `ctx.body::<T>()`
    // instead of parsing raw bytes themselves.
    if let Some(ct) = headers
        .get(http::header::CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
    {
        if ct.to_lowercase().starts_with("multipart/form-data") {
            if let Some(boundary) =
                crate::utils::request_parser::RequestParser::multipart_boundary(ct)
            {
                let mp = crate::utils::request_parser::RequestParser::parse_multipart(
                    &body_bytes,
                    &boundary,
                );
                ctx.set_multipart(mp);
            }
        }
    }
    {
        let guard = router.read().await;
        for mw in &guard.global_middlewares {
            if let Err(e) = mw(&mut ctx).await {
                let resp = crate::response::error_response(&e, Arc::new(ctx.clone()));
                return Ok(finish_request(
                    &method,
                    &path,
                    request_started,
                    adapt_response(resp),
                ));
            }
        }
    }

    let limit = ctx
        .query_param("limit")
        .and_then(|v| v.parse().ok())
        .unwrap_or(15usize);
    let cursor = ctx.query_param("cursor");
    ctx.set_pagination(cursor, limit);

    // Reserved test-client interception — catch-all guard on
    // `X-Moovable-Test-Client`. Only intercepts when the header is present and
    // DocumentationController installed the hook.
    let test_hook = {
        let guard = router.read().await;
        let has_header = headers.contains_key("x-moovable-test-client")
            || headers.contains_key("x-tm30-test-client");
        if has_header {
            guard.test_client_handler.clone()
        } else {
            None
        }
    };
    if let Some(hook) = test_hook {
        let resp = hook(
            ctx.clone(),
            headers.clone(),
            method.clone(),
            path.clone(),
            body_bytes,
        )
        .await;
        return Ok(finish_request(
            &method,
            &path,
            request_started,
            adapt_string_response(resp, Arc::new(ctx.clone())),
        ));
    }

    let guard = router.read().await;
    if let Some((entry, params)) = guard.resolve(&method, &path) {
        for mw in &entry.middlewares {
            if let Err(e) = mw(&mut ctx).await {
                let resp = crate::response::error_response(&e, Arc::new(ctx.clone()));
                return Ok(finish_request(
                    &method,
                    &path,
                    request_started,
                    adapt_response(resp),
                ));
            }
        }
        ctx.set_params(params);
        let handler = entry.handler.clone();
        let path_clone = path.clone();
        let headers_clone = headers.clone();
        let method_clone = method.clone();
        drop(guard);
        let resp = handler(
            ctx.clone(),
            headers_clone,
            method_clone,
            path_clone,
            body_bytes,
        )
        .await;
        Ok(finish_request(
            &method,
            &path,
            request_started,
            adapt_string_response(resp, Arc::new(ctx.clone())),
        ))
    } else {
        drop(guard);
        let err = ErrorResult::not_found(format!("The requested resource was not found: {path}"));
        let resp = crate::response::error_response(&err, Arc::new(ctx.clone()));
        Ok(finish_request(
            &method,
            &path,
            request_started,
            adapt_response(resp),
        ))
    }
}

fn finish_request(
    method: &Method,
    path: &str,
    started: std::time::Instant,
    response: Response<String>,
) -> Response<String> {
    crate::middleware::monitoring::RequestLogger::log(
        path,
        method.as_str(),
        response.status().as_u16(),
        started.elapsed(),
    );
    response
}

fn build_correlation_context(
    headers: &HeaderMap,
    query: &HashMap<String, String>,
    body: &[u8],
) -> CorrelationContext {
    let corr_id = headers
        .get("x-correlation-id")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");
    let flow_str = headers
        .get("x-correlation-flow")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("ONCE");
    let flow = flow_str
        .parse()
        .unwrap_or(crate::logging::CorrelationFlow::Once);
    let ctx = if corr_id.is_empty() {
        CorrelationContext::new()
    } else {
        CorrelationContext::with_ids(corr_id, &hex::encode(rand::random::<[u8; 8]>()))
    };
    ctx.set_flow(flow);
    // Attach request-scoped data in place — handlers read body, headers, and
    // query parameters off the context, so handler signatures stay context-only.
    ctx.set_headers(headers.clone());
    ctx.set_query_params(query.clone());
    ctx.set_body(body.to_vec());
    let req_id = headers.get("x-request-id").and_then(|v| v.to_str().ok());
    if let Some(rid) = req_id {
        ctx.set_request_id(rid);
    } else {
        let rid = hex::encode(rand::random::<[u8; 8]>());
        ctx.set_request_id(&rid);
    }
    ctx
}

fn adapt_response(r: Response<String>) -> Response<String> {
    r
}
fn adapt_string_response(
    mut r: Response<String>,
    ctx: Arc<CorrelationContext>,
) -> Response<String> {
    let headers = r.headers_mut();
    headers
        .entry("x-request-id")
        .or_insert(ctx.request_id().parse().unwrap());
    headers
        .entry("x-correlation-id")
        .or_insert(ctx.correlation_id().parse().unwrap());
    headers
        .entry("x-correlation-flow")
        .or_insert(ctx.flow().to_string().parse().unwrap());
    r
}

/// Builds a complete HTTP response from a `ServiceResult<T>`, setting correlation
/// headers and the content type from the result's response type.
pub fn json_response<T: serde::Serialize + Send + Sync>(
    result: ServiceResult<T>,
    ctx: Arc<CorrelationContext>,
) -> Response<String> {
    crate::response::build_response(&result, ctx)
}

/// Builds a complete HTTP response from any `TypedServiceResult`, setting correlation
/// headers and the content type. Serialization failures fall back to a 500 error message body.
pub fn typed_response(
    result: &dyn TypedServiceResult,
    ctx: Arc<CorrelationContext>,
) -> Response<String> {
    let body = result.serialize().unwrap_or_else(|e| {
        ErrorResult::from_error(&anyhow::anyhow!(e.to_string()), 500)
            .message
            .clone()
    });
    let mut builder = Response::builder()
        .status(result.code())
        .header("X-Request-ID", ctx.request_id())
        .header("X-Correlation-ID", ctx.correlation_id())
        .header("X-Correlation-Flow", ctx.flow().to_string());
    let ct = match result.response_type() {
        ResponseType::Json => "application/json",
        ResponseType::File => {
            let filename = body.rsplit('/').next().unwrap_or("file");
            builder = builder.header(
                "Content-Disposition",
                format!("attachment; filename=\"{}\"", filename),
            );
            "application/octet-stream"
        }
        ResponseType::Xml => "application/xml",
        ResponseType::Javascript => "application/javascript",
        ResponseType::Html => "text/html",
        ResponseType::Text => "text/plain",
    };
    builder = builder.header("Content-Type", ct);
    builder.body(body).unwrap()
}