asupersync 0.4.10

//! Request extractors.
//!
//! Extractors pull typed data from incoming HTTP requests. Each extractor
//! implements [`FromRequest`] or [`FromRequestParts`] and can be used as a
//! handler parameter.
//!
//! # Built-in Extractors
//!
//! - [`Path<T>`]: URL path parameters
//! - [`Query<T>`]: Query string parameters
//! - [`Json<T>`]: JSON request body
//! - [`Form<T>`]: URL-encoded form body
//! - [`Header<T>`] / [`TypedHeader<T>`]: Typed request headers
//! - [`Cookie`]: Raw `Cookie` request header
//! - [`CookieJar`]: Parsed request cookies
//! - [`State<T>`]: Shared application state
//! - [`RawBody`]: Raw request body bytes

use std::any::{Any, TypeId};
use std::collections::HashMap;
use std::fmt;
#[cfg(not(target_arch = "wasm32"))]
use std::pin::Pin;
use std::sync::Arc;
#[cfg(not(target_arch = "wasm32"))]
use std::task::{Context, Poll};

use crate::Cx;
use crate::bytes::Bytes;
#[cfg(not(target_arch = "wasm32"))]
use crate::bytes::{Buf, BytesCursor};
#[cfg(not(target_arch = "wasm32"))]
use crate::http::body::{Body, Frame, HeaderMap, Limited, LimitedError, SizeHint};
#[cfg(not(target_arch = "wasm32"))]
use crate::http::h1::stream::{BodyKind, IncomingBodyError, IncomingRequestBody};
#[cfg(not(target_arch = "wasm32"))]
use crate::types::CancelKind;
#[cfg(not(target_arch = "wasm32"))]
use parking_lot::Mutex;
use serde::de::{
    self, DeserializeOwned, DeserializeSeed, IntoDeserializer, SeqAccess, Unexpected, Visitor,
};
use serde::forward_to_deserialize_any;

const MALFORMED_HEADER_CODE: &str = "[ASUP-E503]";

// ─── Request Type ────────────────────────────────────────────────────────────

/// An incoming HTTP request.
#[derive(Debug, Clone)]
pub struct Request {
    /// HTTP method (GET, POST, etc.).
    pub method: String,
    /// Request path (e.g., "/users/42").
    pub path: String,
    /// Query string (everything after '?'), if present.
    pub query: Option<String>,
    /// Request headers.
    pub headers: HashMap<String, String>,
    /// Request body bytes.
    pub body: Bytes,
    /// Path parameters extracted by the router (e.g., `{ "id": "42" }`).
    pub path_params: HashMap<String, String>,
    /// Extensions for middleware-injected state.
    pub extensions: Extensions,
}

impl Request {
    /// Create a new request (primarily for testing).
    #[must_use]
    pub fn new(method: impl Into<String>, path: impl Into<String>) -> Self {
        Self {
            method: method.into(),
            path: path.into(),
            query: None,
            headers: HashMap::with_capacity(8),
            body: Bytes::new(),
            path_params: HashMap::with_capacity(2),
            extensions: Extensions::new(),
        }
    }

    /// Set the query string.
    #[must_use]
    pub fn with_query(mut self, query: impl Into<String>) -> Self {
        self.query = Some(query.into());
        self
    }

    /// Set the request body.
    #[must_use]
    pub fn with_body(mut self, body: impl Into<Bytes>) -> Self {
        self.body = body.into();
        self
    }

    /// Set a header.
    ///
    /// Header names are normalized to lowercase so the lightweight web stack
    /// can treat them case-insensitively.
    #[must_use]
    pub fn with_header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.headers
            .insert(name.into().to_ascii_lowercase(), value.into());
        self
    }

    /// Returns a header value using HTTP's case-insensitive matching rules.
    #[must_use]
    pub fn header(&self, name: &str) -> Option<&str> {
        if let Some(value) = self.headers.get(name) {
            return Some(value.as_str());
        }

        self.headers
            .iter()
            .find(|(key, _)| key.eq_ignore_ascii_case(name))
            .map(|(_, value)| value.as_str())
    }

    /// Return the effective request-body policy currently enforced by the
    /// router and body extractors.
    ///
    /// This meets backwards-compatible public projection updates with the
    /// router's protected snapshot, so replacing a typed `RequestBodyPolicy`
    /// extension cannot report a value looser than the enforced policy.
    /// Middleware that replaces the entire public [`Self::extensions`] map
    /// also discards the router snapshot and is outside this guarantee.
    #[must_use]
    pub fn body_policy(&self) -> Option<super::RequestBodyPolicy> {
        effective_request_body_policy(self)
    }

    /// Set path parameters (used internally by the router).
    #[must_use]
    pub fn with_path_params(mut self, params: HashMap<String, String>) -> Self {
        self.path_params = params;
        self
    }
}

// ─── Extensions ──────────────────────────────────────────────────────────────

/// Type-erased extension map for middleware-injected data.
///
/// Allows middleware to inject arbitrary typed state into requests.
#[derive(Clone, Default)]
pub struct Extensions {
    string_data: HashMap<String, String>,
    typed_data: HashMap<TypeId, Arc<dyn Any + Send + Sync>>,
}

impl fmt::Debug for Extensions {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Extensions")
            .field("string_keys", &self.string_data.keys().collect::<Vec<_>>())
            .field("typed_count", &self.typed_data.len())
            .finish()
    }
}

impl Extensions {
    /// Create an empty extensions map.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Insert a value by key.
    pub fn insert(&mut self, key: impl Into<String>, value: impl Into<String>) {
        self.string_data.insert(key.into(), value.into());
    }

    /// Get a value by key.
    #[must_use]
    pub fn get(&self, key: &str) -> Option<&str> {
        self.string_data.get(key).map(String::as_str)
    }

    /// Insert a typed value.
    pub fn insert_typed<T>(&mut self, value: T)
    where
        T: Send + Sync + 'static,
    {
        self.typed_data.insert(TypeId::of::<T>(), Arc::new(value));
    }

    /// Get a typed value.
    #[must_use]
    pub fn get_typed<T>(&self) -> Option<&T>
    where
        T: Send + Sync + 'static,
    {
        self.typed_data
            .get(&TypeId::of::<T>())
            .and_then(|value| value.as_ref().downcast_ref::<T>())
    }

    /// Get a cloned typed value.
    #[must_use]
    pub fn get_typed_cloned<T>(&self) -> Option<T>
    where
        T: Clone + Send + Sync + 'static,
    {
        self.get_typed::<T>().cloned()
    }

    /// Merge data from another extension map.
    pub(crate) fn extend_from(&mut self, other: &Self) {
        self.string_data.extend(other.string_data.clone());
        self.typed_data.extend(
            other
                .typed_data
                .iter()
                .map(|(type_id, value)| (*type_id, Arc::clone(value))),
        );
    }
}

// ─── Extraction Error ────────────────────────────────────────────────────────

/// Error returned when extraction fails.
#[derive(Debug, Clone)]
pub struct ExtractionError {
    /// Human-readable description.
    pub message: String,
    /// Suggested HTTP status code for the error response.
    pub status: super::response::StatusCode,
}

impl ExtractionError {
    /// Create a new extraction error.
    #[must_use]
    pub fn new(status: super::response::StatusCode, message: impl Into<String>) -> Self {
        Self {
            message: message.into(),
            status,
        }
    }

    /// Create a 400 Bad Request extraction error.
    #[must_use]
    pub fn bad_request(message: impl Into<String>) -> Self {
        Self::new(super::response::StatusCode::BAD_REQUEST, message)
    }

    /// Create a 422 Unprocessable Entity extraction error.
    #[must_use]
    pub fn unprocessable(message: impl Into<String>) -> Self {
        Self::new(super::response::StatusCode::UNPROCESSABLE_ENTITY, message)
    }
}

impl fmt::Display for ExtractionError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{} {}", self.status, self.message)
    }
}

impl std::error::Error for ExtractionError {}

impl super::response::IntoResponse for ExtractionError {
    fn into_response(self) -> super::response::Response {
        super::response::Response::new(self.status, Bytes::copy_from_slice(self.message.as_bytes()))
            .header("content-type", "text/plain; charset=utf-8")
    }
}

// ─── FromRequest / FromRequestParts ──────────────────────────────────────────

/// Extract a value from request parts (headers, path, query).
///
/// Extractors implementing this trait can be used without consuming the body.
pub trait FromRequestParts: Sized {
    /// Attempt to extract from request parts.
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError>;
}

/// Extract a value from the full request (may consume the body).
///
/// Only one body-consuming extractor can be used per handler.
pub trait FromRequest: Sized {
    /// Attempt to extract from the request.
    fn from_request(req: Request) -> Result<Self, ExtractionError>;

    /// Extract from the request while borrowing its structured-concurrency
    /// context.
    ///
    /// The default preserves the synchronous [`Self::from_request`] contract
    /// exactly. Body extractors that must wait for streamed ingress may
    /// override this hook without breaking existing implementations.
    fn from_request_with_cx<'a>(
        _cx: &'a Cx,
        req: Request,
    ) -> impl std::future::Future<Output = Result<Self, ExtractionError>> + Send + 'a
    where
        Self: Send + 'a,
    {
        std::future::ready(Self::from_request(req))
    }
}

// Blanket: anything that implements FromRequestParts also implements FromRequest.
impl<T: FromRequestParts> FromRequest for T {
    fn from_request(req: Request) -> Result<Self, ExtractionError> {
        Self::from_request_parts(&req)
    }
}

// ─── Path<T> ─────────────────────────────────────────────────────────────────

/// Extract path parameters.
///
/// For a single parameter, primitive/owned types can be extracted directly
/// (for example `Path<u64>` or `Path<String>`). For named parameters, extract
/// into a `Deserialize` type (for example a struct or `HashMap<String, String>`).
///
/// ```ignore
/// async fn get_user(Path(id): Path<String>) -> String {
///     format!("User {id}")
/// }
/// ```
#[derive(Debug, Clone)]
pub struct Path<T>(pub T);

impl<T> FromRequestParts for Path<T>
where
    T: DeserializeOwned,
{
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        if req.path_params.is_empty() {
            return Err(ExtractionError::bad_request("no path parameters found"));
        }

        if req.path_params.len() == 1
            && let Some(first) = req.path_params.values().next()
            && let Some(value) = deserialize_single_value::<T>(first)
        {
            return Ok(Self(value));
        }

        deserialize_from_string_map(&req.path_params, "path parameters").map(Self)
    }
}

// ─── Query<T> ────────────────────────────────────────────────────────────────

/// Extract query string parameters.
///
/// Deserializes query pairs into typed values.
///
/// ```ignore
/// #[derive(Deserialize)]
/// struct Pagination { page: u32, per_page: u32 }
///
/// async fn list(Query(p): Query<Pagination>) -> String {
///     format!("Page {} ({} per page)", p.page, p.per_page)
/// }
/// ```
#[derive(Debug, Clone)]
pub struct Query<T>(pub T);

impl<T> FromRequestParts for Query<T>
where
    T: DeserializeOwned,
{
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        let qs = req.query.as_deref().unwrap_or("");
        let parsed = parse_urlencoded(qs, "query parameter")?;

        if parsed.len() == 1
            && let Some(first) = parsed.values().next()
            && let Some(value) = deserialize_single_value::<T>(first)
        {
            return Ok(Self(value));
        }

        deserialize_from_string_map(&parsed, "query parameters").map(Self)
    }
}

fn deserialize_single_value<T>(raw: &str) -> Option<T>
where
    T: DeserializeOwned,
{
    if let Ok(parsed) = serde_json::from_value::<T>(serde_json::Value::String(raw.to_string())) {
        return Some(parsed);
    }

    serde_json::from_value::<T>(coerce_json_scalar(raw)).ok()
}

#[allow(clippy::implicit_hasher)]
fn deserialize_from_string_map<T>(
    values: &HashMap<String, String>,
    context: &str,
) -> Result<T, ExtractionError>
where
    T: DeserializeOwned,
{
    // Use the same type-directed deserializer as `Form`: it coerces each value
    // based on the *target field's* requested type (string fields stay strings
    // via `deserialize_str`/`deserialize_any`; numeric/bool fields parse),
    // rather than the previous per-value guessing. The old two-pass approach
    // (all-strings, then coerce-every-value-to-its-looks-like type) broke any
    // struct mixing a `String` field with a numeric field: a string field
    // holding a numeric-looking value (an all-digit username, a numeric id or
    // ZIP passed as text, "true"/"false" strings) was coerced to a JSON
    // number/bool in the fallback pass and then failed to deserialize into
    // `String`, returning a confusing 400 to legitimate clients.
    //
    // Query and Path are always single-valued here (duplicate query keys are
    // rejected upstream in `parse_urlencoded`, and path params are a
    // single-value map), so each value becomes a one-element slice.
    let multi: HashMap<String, Vec<String>> = values
        .iter()
        .map(|(key, value)| (key.clone(), vec![value.clone()]))
        .collect();
    deserialize_from_multi_value_map(&multi, context)
}

fn coerce_json_scalar(raw: &str) -> serde_json::Value {
    if let Ok(boolean) = raw.parse::<bool>() {
        return serde_json::Value::Bool(boolean);
    }
    if let Ok(integer) = raw.parse::<i64>() {
        return serde_json::Value::Number(integer.into());
    }
    if let Ok(unsigned) = raw.parse::<u64>() {
        return serde_json::Value::Number(unsigned.into());
    }
    if let Ok(float) = raw.parse::<f64>()
        && let Some(number) = serde_json::Number::from_f64(float)
    {
        return serde_json::Value::Number(number);
    }
    serde_json::Value::String(raw.to_string())
}

/// Deserialize from multi-value map (for forms with duplicate keys).
///
/// Handles both single values and Vec<String> according to target type.
/// For single-value fields, uses the first value. For Vec fields, preserves all values.
fn deserialize_from_multi_value_map<T>(
    parsed: &HashMap<String, Vec<String>>,
    context: &str,
) -> Result<T, ExtractionError>
where
    T: DeserializeOwned,
{
    let fields = parsed
        .iter()
        .map(|(key, values)| (key.as_str(), FormValueDeserializer { values }));
    let deserializer = de::value::MapDeserializer::new(fields);
    T::deserialize(deserializer)
        .map_err(|e| ExtractionError::bad_request(format!("invalid {context}: {e}")))
}

#[derive(Clone, Copy)]
struct FormValueDeserializer<'a> {
    values: &'a [String],
}

impl<'a> FormValueDeserializer<'a> {
    fn first<E>(self) -> Result<&'a str, E>
    where
        E: de::Error,
    {
        self.values
            .first()
            .map(String::as_str)
            .ok_or_else(|| E::invalid_value(Unexpected::Seq, &"at least one form value"))
    }

    fn parse<T, E>(self, expected: &'static str) -> Result<T, E>
    where
        T: std::str::FromStr,
        E: de::Error,
    {
        let raw = self.first::<E>()?;
        raw.parse::<T>()
            .map_err(|_| E::invalid_value(Unexpected::Str(raw), &expected))
    }
}

impl<'de> IntoDeserializer<'de, de::value::Error> for FormValueDeserializer<'de> {
    type Deserializer = Self;

    fn into_deserializer(self) -> Self::Deserializer {
        self
    }
}

impl<'de> de::Deserializer<'de> for FormValueDeserializer<'de> {
    type Error = de::value::Error;

    fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_str(self.first::<Self::Error>()?)
    }

    fn deserialize_bool<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_bool(self.parse("a boolean")?)
    }

    fn deserialize_i8<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_i8(self.parse("an i8")?)
    }

    fn deserialize_i16<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_i16(self.parse("an i16")?)
    }

    fn deserialize_i32<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_i32(self.parse("an i32")?)
    }

    fn deserialize_i64<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_i64(self.parse("an i64")?)
    }

    fn deserialize_u8<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_u8(self.parse("a u8")?)
    }

    fn deserialize_u16<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_u16(self.parse("a u16")?)
    }

    fn deserialize_u32<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_u32(self.parse("a u32")?)
    }

    fn deserialize_u64<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_u64(self.parse("a u64")?)
    }

    fn deserialize_f32<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_f32(self.parse("an f32")?)
    }

    fn deserialize_f64<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_f64(self.parse("an f64")?)
    }

    fn deserialize_char<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        let raw = self.first::<Self::Error>()?;
        let mut chars = raw.chars();
        match (chars.next(), chars.next()) {
            (Some(c), None) => visitor.visit_char(c),
            _ => Err(de::Error::invalid_value(Unexpected::Str(raw), &"a char")),
        }
    }

    fn deserialize_str<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_str(self.first::<Self::Error>()?)
    }

    fn deserialize_string<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_string(self.first::<Self::Error>()?.to_string())
    }

    fn deserialize_bytes<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_bytes(self.first::<Self::Error>()?.as_bytes())
    }

    fn deserialize_byte_buf<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_byte_buf(self.first::<Self::Error>()?.as_bytes().to_vec())
    }

    fn deserialize_option<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        if self.values.is_empty() {
            visitor.visit_none()
        } else {
            visitor.visit_some(self)
        }
    }

    fn deserialize_unit<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        if self.first::<Self::Error>()?.is_empty() {
            visitor.visit_unit()
        } else {
            Err(de::Error::invalid_value(
                Unexpected::Str(self.first::<Self::Error>()?),
                &"an empty form value",
            ))
        }
    }

    fn deserialize_newtype_struct<V>(
        self,
        _name: &'static str,
        visitor: V,
    ) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_newtype_struct(self)
    }

    fn deserialize_seq<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_seq(FormSeqDeserializer {
            values: self.values.iter(),
        })
    }

    fn deserialize_tuple<V>(self, _len: usize, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        self.deserialize_seq(visitor)
    }

    fn deserialize_tuple_struct<V>(
        self,
        _name: &'static str,
        _len: usize,
        visitor: V,
    ) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        self.deserialize_seq(visitor)
    }

    fn deserialize_enum<V>(
        self,
        _name: &'static str,
        _variants: &'static [&'static str],
        visitor: V,
    ) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        visitor.visit_enum(self.first::<Self::Error>()?.into_deserializer())
    }

    forward_to_deserialize_any! {
        unit_struct map struct identifier ignored_any
    }
}

struct FormSeqDeserializer<'a> {
    values: std::slice::Iter<'a, String>,
}

impl<'de> SeqAccess<'de> for FormSeqDeserializer<'de> {
    type Error = de::value::Error;

    fn next_element_seed<T>(&mut self, seed: T) -> Result<Option<T::Value>, Self::Error>
    where
        T: DeserializeSeed<'de>,
    {
        self.values
            .next()
            .map(|value| {
                seed.deserialize(FormValueDeserializer {
                    values: std::slice::from_ref(value),
                })
            })
            .transpose()
    }
}

/// Parse a URL-encoded string into key-value pairs.
///
/// Per HTML form specification, duplicate keys should preserve all values
/// as Vec<String> rather than rejecting or overwriting. This correctly
/// handles forms like `a=1&a=2` -> `{"a": ["1", "2"]}`.
fn parse_urlencoded_multi(
    input: &str,
    _field_kind: &str,
) -> Result<HashMap<String, Vec<String>>, ExtractionError> {
    let mut parsed: HashMap<String, Vec<String>> = HashMap::new();
    for pair in input.split('&').filter(|s| !s.is_empty()) {
        let mut parts = pair.splitn(2, '=');
        let Some(key) = parts.next() else {
            continue;
        };
        let key = percent_decode(key);
        let value = percent_decode(parts.next().unwrap_or(""));
        parsed.entry(key).or_default().push(value);
    }
    Ok(parsed)
}

/// Legacy parse function for backward compatibility with single values.
/// Used by Query extractor which may want different duplicate key behavior.
fn parse_urlencoded(
    input: &str,
    field_kind: &str,
) -> Result<HashMap<String, String>, ExtractionError> {
    let multi_values = parse_urlencoded_multi(input, field_kind)?;
    let mut single_values = HashMap::new();

    for (key, values) in multi_values {
        if values.len() == 1 {
            // Safe: length check ensures exactly one element exists
            if let Some(value) = values.into_iter().next() {
                single_values.insert(key, value);
            } else {
                // Should never happen given length check, but handle gracefully
                return Err(ExtractionError::bad_request(format!(
                    "internal error: expected value for {field_kind} `{key}`"
                )));
            }
        } else {
            return Err(ExtractionError::bad_request(format!(
                "duplicate {field_kind} `{key}` (use multi-value extractor for forms)"
            )));
        }
    }
    Ok(single_values)
}

/// Simple percent-decoding (handles %XX and + as space).
fn percent_decode(input: &str) -> String {
    let input = input.as_bytes();
    let mut output = Vec::with_capacity(input.len());
    let mut i = 0;
    while i < input.len() {
        match input[i] {
            b'+' => {
                output.push(b' ');
                i += 1;
            }
            b'%' => {
                if i.saturating_add(2) < input.len() {
                    let hi = hex_val(input[i.saturating_add(1)]);
                    let lo = hex_val(input[i.saturating_add(2)]);
                    if let (Some(h), Some(l)) = (hi, lo) {
                        output.push(h << 4 | l);
                        i += 3;
                    } else {
                        output.push(b'%');
                        i += 1;
                    }
                } else {
                    output.push(b'%');
                    i += 1;
                }
            }
            b => {
                output.push(b);
                i += 1;
            }
        }
    }
    String::from_utf8(output).unwrap_or_else(|e| String::from_utf8_lossy(e.as_bytes()).into_owned())
}

fn hex_val(b: u8) -> Option<u8> {
    match b {
        b'0'..=b'9' => Some(b - b'0'),
        b'a'..=b'f' => Some(b - b'a' + 10),
        b'A'..=b'F' => Some(b - b'A' + 10),
        _ => None,
    }
}

// ─── Header<T> / TypedHeader<T> ─────────────────────────────────────────────

/// Error returned by a typed header parser.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HeaderParseError {
    message: String,
}

impl HeaderParseError {
    /// Create a typed header parse error.
    #[must_use]
    pub fn new(message: impl Into<String>) -> Self {
        Self {
            message: message.into(),
        }
    }

    /// Human-readable parse failure.
    #[must_use]
    pub fn message(&self) -> &str {
        &self.message
    }
}

impl fmt::Display for HeaderParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.message)
    }
}

impl std::error::Error for HeaderParseError {}

/// Convert one request header value into a typed extractor value.
pub trait FromHeaderValue: Sized {
    /// Canonical header name used by the extractor.
    const NAME: &'static str;

    /// Parse a header value.
    fn from_header_value(value: &str) -> Result<Self, HeaderParseError>;
}

/// Extract a typed request header.
///
/// ```
/// use asupersync::web::extract::{
///     ContentType, FromRequestParts, Header, Request,
/// };
///
/// let req = Request::new("POST", "/items")
///     .with_header("Content-Type", "application/json; charset=utf-8");
///
/// let Header(content_type) =
///     Header::<ContentType>::from_request_parts(&req).expect("content type");
/// assert_eq!(content_type.media_type(), "application/json");
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Header<T>(pub T);

impl<T> FromRequestParts for Header<T>
where
    T: FromHeaderValue,
{
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        extract_typed_header::<T>(req).map(Self)
    }
}

/// Extract a typed request header.
///
/// This is a naming alias in behavior, not a global header map. It extracts
/// exactly one typed header through [`FromHeaderValue`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TypedHeader<T>(pub T);

impl<T> FromRequestParts for TypedHeader<T>
where
    T: FromHeaderValue,
{
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        extract_typed_header::<T>(req).map(Self)
    }
}

/// `Content-Type` request header.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ContentType(pub String);

impl ContentType {
    /// Full header value.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Media type without parameters.
    #[must_use]
    pub fn media_type(&self) -> &str {
        self.0.split(';').next().unwrap_or("").trim()
    }
}

impl FromHeaderValue for ContentType {
    const NAME: &'static str = "content-type";

    fn from_header_value(value: &str) -> Result<Self, HeaderParseError> {
        let trimmed = checked_header_value(Self::NAME, value)?;
        let media_type = trimmed.split(';').next().unwrap_or("").trim();
        validate_media_range(media_type, false)?;
        Ok(Self(trimmed.to_string()))
    }
}

/// `Authorization` request header.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Authorization {
    /// Authorization scheme, e.g. `Bearer`.
    pub scheme: String,
    /// Scheme credentials.
    pub credentials: String,
}

impl Authorization {
    /// Reconstruct the header value.
    #[must_use]
    pub fn as_str(&self) -> String {
        format!("{} {}", self.scheme, self.credentials)
    }
}

impl FromHeaderValue for Authorization {
    const NAME: &'static str = "authorization";

    fn from_header_value(value: &str) -> Result<Self, HeaderParseError> {
        let trimmed = checked_header_value(Self::NAME, value)?;
        let mut parts = trimmed.splitn(2, char::is_whitespace);
        let scheme = parts.next().unwrap_or("");
        let credentials = parts.next().unwrap_or("").trim();

        if scheme.is_empty() || !scheme.bytes().all(is_http_token_char) {
            return Err(HeaderParseError::new(
                "Authorization scheme must be a non-empty HTTP token",
            ));
        }
        if credentials.is_empty() {
            return Err(HeaderParseError::new(
                "Authorization credentials must be present",
            ));
        }

        Ok(Self {
            scheme: scheme.to_string(),
            credentials: credentials.to_string(),
        })
    }
}

/// `User-Agent` request header.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UserAgent(pub String);

impl UserAgent {
    /// Full header value.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl FromHeaderValue for UserAgent {
    const NAME: &'static str = "user-agent";

    fn from_header_value(value: &str) -> Result<Self, HeaderParseError> {
        Ok(Self(checked_header_value(Self::NAME, value)?.to_string()))
    }
}

/// `Accept` request header.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Accept(pub String);

impl Accept {
    /// Full header value.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl FromHeaderValue for Accept {
    const NAME: &'static str = "accept";

    fn from_header_value(value: &str) -> Result<Self, HeaderParseError> {
        let trimmed = checked_header_value(Self::NAME, value)?;
        for raw_range in trimmed.split(',') {
            let media_range = raw_range.split(';').next().unwrap_or("").trim();
            validate_media_range(media_range, true)?;
        }
        Ok(Self(trimmed.to_string()))
    }
}

fn extract_typed_header<T>(req: &Request) -> Result<T, ExtractionError>
where
    T: FromHeaderValue,
{
    let value = header_value_ci(req, T::NAME)
        .ok_or_else(|| malformed_header_rejection(T::NAME, "missing header"))?;
    T::from_header_value(value).map_err(|err| malformed_header_rejection(T::NAME, err.message()))
}

fn malformed_header_rejection(header_name: &str, reason: impl fmt::Display) -> ExtractionError {
    ExtractionError::new(
        super::response::StatusCode::BAD_REQUEST,
        format!("{MALFORMED_HEADER_CODE} malformed request header `{header_name}`: {reason}"),
    )
}

fn checked_header_value<'a>(
    header_name: &str,
    value: &'a str,
) -> Result<&'a str, HeaderParseError> {
    if value
        .as_bytes()
        .iter()
        .any(|byte| matches!(*byte, b'\r' | b'\n' | 0))
    {
        return Err(HeaderParseError::new(format!(
            "{header_name} contains a forbidden control character"
        )));
    }

    let trimmed = value.trim();
    if trimmed.is_empty() {
        return Err(HeaderParseError::new(format!(
            "{header_name} must not be empty"
        )));
    }
    Ok(trimmed)
}

fn validate_media_range(media_range: &str, allow_wildcards: bool) -> Result<(), HeaderParseError> {
    let Some((ty, subtype)) = media_range.split_once('/') else {
        return Err(HeaderParseError::new(
            "media range must contain type and subtype",
        ));
    };
    let ty = ty.trim();
    let subtype = subtype.trim();

    let type_ok =
        (ty == "*" && allow_wildcards) || (!ty.is_empty() && ty.bytes().all(is_http_token_char));
    let subtype_ok = subtype == "*" && allow_wildcards
        || !subtype.is_empty() && subtype.bytes().all(is_http_token_char);
    if !type_ok || !subtype_ok {
        return Err(HeaderParseError::new(
            "media range type and subtype must be HTTP tokens",
        ));
    }
    Ok(())
}

fn is_http_token_char(byte: u8) -> bool {
    matches!(
        byte,
        b'0'..=b'9'
            | b'a'..=b'z'
            | b'A'..=b'Z'
            | b'!'
            | b'#'
            | b'$'
            | b'%'
            | b'&'
            | b'\''
            | b'*'
            | b'+'
            | b'-'
            | b'.'
            | b'^'
            | b'_'
            | b'`'
            | b'|'
            | b'~'
    )
}

// ─── Cookie / CookieJar ─────────────────────────────────────────────────────

/// Extract the raw `Cookie` request header.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Cookie(pub String);

impl FromRequestParts for Cookie {
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        header_value_ci(req, "cookie")
            .map(|value| Self(value.to_string()))
            .ok_or_else(|| ExtractionError::bad_request("missing Cookie header"))
    }
}

/// Parsed request cookies.
///
/// `CookieJar` is extracted from the `Cookie` header and provides convenient
/// accessors for cookie lookup.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct CookieJar {
    cookies: HashMap<String, String>,
}

impl CookieJar {
    /// Returns the cookie value for `name`, if present.
    #[must_use]
    pub fn get(&self, name: &str) -> Option<&str> {
        self.cookies.get(name).map(String::as_str)
    }

    /// Returns true when a cookie with `name` exists.
    #[must_use]
    pub fn contains(&self, name: &str) -> bool {
        self.cookies.contains_key(name)
    }

    /// Returns the number of cookies in the jar.
    #[must_use]
    pub fn len(&self) -> usize {
        self.cookies.len()
    }

    /// Returns true when no cookies are present.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.cookies.is_empty()
    }

    /// Iterates over cookie key/value pairs.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> + '_ {
        self.cookies
            .iter()
            .map(|(name, value)| (name.as_str(), value.as_str()))
    }
}

impl FromRequestParts for CookieJar {
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        let cookies = header_value_ci(req, "cookie")
            .map(parse_cookie_header)
            .unwrap_or_default();
        Ok(Self { cookies })
    }
}

pub(super) fn header_value_ci<'a>(req: &'a Request, header_name: &str) -> Option<&'a str> {
    req.headers
        .iter()
        .find(|(name, _)| name.eq_ignore_ascii_case(header_name))
        .map(|(_, value)| value.as_str())
}

fn matches_content_type_media_type(content_type: &str, expected: &str) -> bool {
    content_type
        .split(';')
        .next()
        .is_some_and(|media_type| media_type.trim().eq_ignore_ascii_case(expected))
}

fn matches_json_content_type(content_type: &str) -> bool {
    let Some(media_type) = content_type.split(';').next() else {
        return false;
    };
    let Some((ty, subtype)) = media_type.trim().split_once('/') else {
        return false;
    };
    if !ty.trim().eq_ignore_ascii_case("application") {
        return false;
    }

    let subtype = subtype.trim();
    subtype.eq_ignore_ascii_case("json")
        || subtype.rsplit_once('+').is_some_and(|(prefix, suffix)| {
            !prefix.trim().is_empty() && suffix.eq_ignore_ascii_case("json")
        })
}

#[allow(clippy::implicit_hasher)]
fn parse_cookie_header(raw: &str) -> HashMap<String, String> {
    let mut parsed = HashMap::new();
    for segment in raw.split(';') {
        let trimmed = segment.trim();
        if trimmed.is_empty() {
            continue;
        }
        let Some((name, value)) = trimmed.split_once('=') else {
            continue;
        };
        let name = name.trim();
        if name.is_empty() {
            continue;
        }
        let value = value.trim().trim_matches('"').to_string();
        parsed.insert(name.to_string(), value);
    }
    parsed
}

fn invalid_content_length() -> ExtractionError {
    ExtractionError::new(
        super::response::StatusCode::BAD_REQUEST,
        "invalid Content-Length header",
    )
}

pub(super) fn parse_content_length(value: &str) -> Result<usize, ExtractionError> {
    let mut parsed = None;

    for raw_part in value.split(',') {
        let part = raw_part.trim();
        if part.is_empty() {
            return Err(invalid_content_length());
        }

        // RFC 9110 §8.6: Content-Length = 1*DIGIT. Rust's `usize` parser also
        // accepts a leading '+' (e.g. "+5" -> 5); reject any non-digit byte so
        // a fronting proxy cannot frame such a value differently than we do
        // (the classic request-smuggling / framing-desync precondition).
        if !part.bytes().all(|b| b.is_ascii_digit()) {
            return Err(invalid_content_length());
        }
        let declared = part
            .parse::<usize>()
            .map_err(|_| invalid_content_length())?;
        if let Some(previous) = parsed {
            if previous != declared {
                return Err(ExtractionError::new(
                    super::response::StatusCode::BAD_REQUEST,
                    "conflicting Content-Length header values",
                ));
            }
        } else {
            parsed = Some(declared);
        }
    }

    parsed.ok_or_else(invalid_content_length)
}

/// Validates that request body length matches Content-Length, when present.
fn validate_content_length(req: &Request) -> Result<(), ExtractionError> {
    if let Some(cl_value) = header_value_ci(req, "content-length") {
        let declared_length = parse_content_length(cl_value)?;
        let actual_length = req.body.len();
        if actual_length != declared_length {
            return Err(ExtractionError::new(
                super::response::StatusCode::BAD_REQUEST,
                format!(
                    "Content-Length mismatch: declared {} bytes, received {} bytes",
                    declared_length, actual_length
                ),
            ));
        }
    }
    Ok(())
}

/// Check Content-Length header against size limit before reading body.
///
/// This prevents DoS attacks where large bodies are fully buffered into memory
/// before size checking occurs. Per RFC 9110, we should return 413 Payload Too Large
/// based on Content-Length header before body processing.
fn check_content_length_limit(req: &Request, limit: usize) -> Result<(), ExtractionError> {
    if let Some(cl_value) = header_value_ci(req, "content-length") {
        let declared_length = parse_content_length(cl_value)?;
        if declared_length > limit {
            return Err(ExtractionError::new(
                super::response::StatusCode::PAYLOAD_TOO_LARGE,
                format!(
                    "Content-Length {} bytes exceeds limit {} bytes",
                    declared_length, limit
                ),
            ));
        }
    }
    Ok(())
}

// ─── BodyLimits ──────────────────────────────────────────────────────────────

/// Default maximum JSON body size (10 MiB).
const DEFAULT_MAX_JSON_BODY_SIZE: usize = 10 * 1024 * 1024;

/// Default maximum form body size (2 MiB).
const DEFAULT_MAX_FORM_BODY_SIZE: usize = 2 * 1024 * 1024;

/// Default maximum raw body size (10 MiB).
const DEFAULT_MAX_RAW_BODY_SIZE: usize = 10 * 1024 * 1024;

/// Configurable body size limits for request extractors.
///
/// Middleware can inject this into request extensions to override the default
/// limits on a per-route or per-server basis. Extractors (`Json`, `Form`,
/// `RawBody`)
/// check for this type in extensions and fall back to defaults if absent.
///
/// # Example
///
/// ```ignore
/// // Server-wide: allow 50 MiB JSON bodies
/// let limits = BodyLimits::new()
///     .max_json_body_size(50 * 1024 * 1024);
/// // Inject via middleware into request.extensions.insert_typed(limits)
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BodyLimits {
    /// Maximum JSON body size in bytes.
    pub max_json_body_size: usize,
    /// Maximum form body size in bytes.
    pub max_form_body_size: usize,
    /// Maximum raw body size in bytes.
    pub max_raw_body_size: usize,
}

impl Default for BodyLimits {
    fn default() -> Self {
        Self {
            max_json_body_size: DEFAULT_MAX_JSON_BODY_SIZE,
            max_form_body_size: DEFAULT_MAX_FORM_BODY_SIZE,
            max_raw_body_size: DEFAULT_MAX_RAW_BODY_SIZE,
        }
    }
}

impl BodyLimits {
    /// Create body limits with defaults (10 MiB JSON, 2 MiB form, 10 MiB raw).
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the maximum JSON body size.
    #[must_use]
    pub fn max_json_body_size(mut self, bytes: usize) -> Self {
        self.max_json_body_size = bytes;
        self
    }

    /// Set the maximum form body size.
    #[must_use]
    pub fn max_form_body_size(mut self, bytes: usize) -> Self {
        self.max_form_body_size = bytes;
        self
    }

    /// Set the maximum raw body size.
    #[must_use]
    pub fn max_raw_body_size(mut self, bytes: usize) -> Self {
        self.max_raw_body_size = bytes;
        self
    }

    /// Meet these limits with another boundary's limits.
    #[must_use]
    pub fn tightened_with(self, other: Self) -> Self {
        Self {
            max_json_body_size: self.max_json_body_size.min(other.max_json_body_size),
            max_form_body_size: self.max_form_body_size.min(other.max_form_body_size),
            max_raw_body_size: self.max_raw_body_size.min(other.max_raw_body_size),
        }
    }

    /// Apply a format-independent total request-body ceiling.
    #[must_use]
    pub fn max_total_body_size(self, bytes: usize) -> Self {
        self.tightened_with(Self {
            max_json_body_size: bytes,
            max_form_body_size: bytes,
            max_raw_body_size: bytes,
        })
    }
}

pub(super) fn effective_request_body_policy(req: &Request) -> Option<super::RequestBodyPolicy> {
    let enforced = req
        .extensions
        .get_typed::<super::EnforcedRequestBodyPolicy>()
        .map(|snapshot| snapshot.policy);
    let projected = req
        .extensions
        .get_typed::<super::RequestBodyPolicy>()
        .copied();
    let mut effective = match (enforced, projected) {
        (Some(enforced), Some(projected)) => Some(enforced.tightened_with(projected)),
        (Some(policy), None) | (None, Some(policy)) => Some(policy.resolved()),
        (None, None) => None,
    }?;

    if let Some(body_limits) = req.extensions.get_typed::<BodyLimits>().copied() {
        effective.body_limits = effective.body_limits.tightened_with(body_limits);
    }
    if let Some(multipart_limits) = req
        .extensions
        .get_typed::<super::multipart::MultipartLimits>()
        .copied()
    {
        effective.multipart_limits = effective.multipart_limits.tightened_with(multipart_limits);
    }

    Some(effective.resolved())
}

fn effective_body_limits(req: &Request) -> BodyLimits {
    let projected = req.extensions.get_typed::<BodyLimits>().copied();
    let enforced = effective_request_body_policy(req).map(|policy| policy.body_limits);
    match (enforced, projected) {
        (Some(enforced), Some(projected)) => enforced.tightened_with(projected),
        (Some(limits), None) | (None, Some(limits)) => limits,
        (None, None) => BodyLimits::default(),
    }
}

// ─── Json<T> ─────────────────────────────────────────────────────────────────

/// Extract JSON request body.
///
/// Deserializes the request body as JSON.
///
/// The body size limit defaults to 10 MiB but can be overridden by injecting
/// [`BodyLimits`] into the request extensions via middleware.
///
/// ```ignore
/// async fn create_user(Json(user): Json<CreateUser>) -> StatusCode {
///     // ...
///     StatusCode::CREATED
/// }
/// ```
#[derive(Debug, Clone)]
pub struct Json<T>(pub T);

fn json_body_limit(req: &Request) -> usize {
    effective_body_limits(req).max_json_body_size
}

fn validate_json_content_type(req: &Request) -> Result<(), ExtractionError> {
    let Some(content_type) = header_value_ci(req, "content-type") else {
        return Err(ExtractionError::new(
            super::response::StatusCode::UNSUPPORTED_MEDIA_TYPE,
            "Json requires Content-Type: application/json",
        ));
    };
    if !matches_json_content_type(content_type) {
        return Err(ExtractionError::new(
            super::response::StatusCode::UNSUPPORTED_MEDIA_TYPE,
            format!("expected application/json, got {content_type}"),
        ));
    }
    Ok(())
}

fn deserialize_json_body<T: serde::de::DeserializeOwned>(
    body: &[u8],
) -> Result<Json<T>, ExtractionError> {
    // br-asupersync-y4mc96: keep serde error in server-side log only;
    // return a generic message to the client so byte offsets, expected
    // type names, and partial-parse context don't reach an attacker.
    // The detailed `e` is recorded via tracing for operator forensics.
    serde_json::from_slice(body).map(Json).map_err(|_err| {
        crate::tracing_compat::warn!(
            error = %_err,
            "web/extract: Json deserialization failed"
        );
        ExtractionError::unprocessable("invalid JSON body")
    })
}

impl<T: serde::de::DeserializeOwned> FromRequest for Json<T> {
    fn from_request(req: Request) -> Result<Self, ExtractionError> {
        #[cfg(not(target_arch = "wasm32"))]
        reject_buffered_extractor_on_streaming_request(&req, "Json")?;

        let limit = json_body_limit(&req);

        // SECURITY: Check Content-Length header BEFORE reading body to prevent DoS
        check_content_length_limit(&req, limit)?;

        if req.body.len() > limit {
            return Err(ExtractionError::new(
                super::response::StatusCode::PAYLOAD_TOO_LARGE,
                format!(
                    "JSON body too large: {} bytes (limit {})",
                    req.body.len(),
                    limit
                ),
            ));
        }

        // Reject invalid or mismatched framing metadata before parsing body bytes.
        validate_content_length(&req)?;

        validate_json_content_type(&req)?;
        deserialize_json_body(req.body.as_ref())
    }

    fn from_request_with_cx<'a>(
        cx: &'a Cx,
        req: Request,
    ) -> impl std::future::Future<Output = Result<Self, ExtractionError>> + Send + 'a
    where
        Self: Send + 'a,
    {
        async move {
            #[cfg(not(target_arch = "wasm32"))]
            if req.extensions.get_typed::<StreamingRawBodySlot>().is_some() {
                let limit = json_body_limit(&req);
                check_content_length_limit(&req, limit)?;
                validate_json_content_type(&req)?;
                let body = StreamingRawBody::take_from_request(&req)?;
                let collected = body
                    .collect_bounded_with_cx(cx, limit)
                    .await
                    .map_err(|error| streaming_extraction_error("JSON", error))?;
                return deserialize_json_body(collected.data().as_ref());
            }

            Self::from_request(req)
        }
    }
}

// ─── Form<T> ─────────────────────────────────────────────────────────────────

/// Extract URL-encoded form data from the request body.
///
/// ```ignore
/// #[derive(Deserialize)]
/// struct Login { username: String, password: String }
///
/// async fn login(Form(data): Form<Login>) -> Redirect {
///     // ...
///     Redirect::to("/dashboard")
/// }
/// ```
#[derive(Debug, Clone)]
pub struct Form<T>(pub T);

fn form_body_limit(req: &Request) -> usize {
    effective_body_limits(req).max_form_body_size
}

fn validate_form_content_type(req: &Request) -> Result<(), ExtractionError> {
    // br-asupersync-mxqraw: Content-Type MUST be present AND must be
    // application/x-www-form-urlencoded. Missing Content-Type remains 415.
    let Some(content_type) = header_value_ci(req, "content-type") else {
        return Err(ExtractionError::new(
            super::response::StatusCode::UNSUPPORTED_MEDIA_TYPE,
            "Form requires Content-Type: application/x-www-form-urlencoded",
        ));
    };
    if !matches_content_type_media_type(content_type, "application/x-www-form-urlencoded") {
        return Err(ExtractionError::new(
            super::response::StatusCode::UNSUPPORTED_MEDIA_TYPE,
            format!("expected application/x-www-form-urlencoded, got {content_type}"),
        ));
    }
    Ok(())
}

#[allow(clippy::implicit_hasher)]
fn deserialize_form_body<T: DeserializeOwned>(body: &[u8]) -> Result<Form<T>, ExtractionError> {
    let body_str = std::str::from_utf8(body)
        .map_err(|error| ExtractionError::bad_request(format!("invalid UTF-8 body: {error}")))?;
    let parsed = parse_urlencoded_multi(body_str, "form field")?;
    deserialize_from_multi_value_map(&parsed, "form data").map(Form)
}

#[allow(clippy::implicit_hasher)]
impl<T: DeserializeOwned> FromRequest for Form<T> {
    fn from_request(req: Request) -> Result<Self, ExtractionError> {
        #[cfg(not(target_arch = "wasm32"))]
        reject_buffered_extractor_on_streaming_request(&req, "Form")?;

        let limit = form_body_limit(&req);

        // SECURITY: Check Content-Length header BEFORE reading body to prevent DoS
        check_content_length_limit(&req, limit)?;

        if req.body.len() > limit {
            return Err(ExtractionError::new(
                super::response::StatusCode::PAYLOAD_TOO_LARGE,
                format!(
                    "form body too large: {} bytes (limit {})",
                    req.body.len(),
                    limit
                ),
            ));
        }

        // Reject invalid or mismatched framing metadata before parsing body bytes.
        validate_content_length(&req)?;

        validate_form_content_type(&req)?;
        deserialize_form_body(req.body.as_ref())
    }

    fn from_request_with_cx<'a>(
        cx: &'a Cx,
        req: Request,
    ) -> impl std::future::Future<Output = Result<Self, ExtractionError>> + Send + 'a
    where
        Self: Send + 'a,
    {
        async move {
            #[cfg(not(target_arch = "wasm32"))]
            if req.extensions.get_typed::<StreamingRawBodySlot>().is_some() {
                let limit = form_body_limit(&req);
                check_content_length_limit(&req, limit)?;
                validate_form_content_type(&req)?;
                let body = StreamingRawBody::take_from_request(&req)?;
                let collected = body
                    .collect_bounded_with_cx(cx, limit)
                    .await
                    .map_err(|error| streaming_extraction_error("form", error))?;
                return deserialize_form_body(collected.data().as_ref());
            }

            Self::from_request(req)
        }
    }
}

// ─── State<T> ────────────────────────────────────────────────────────────────

/// Extract shared application state.
///
/// State must be injected via `Router::with_state()`. The state is stored
/// in the request extensions by the router.
///
/// ```ignore
/// use asupersync::web::{FnHandler1, Router, State, get};
///
/// #[derive(Clone)]
/// struct AppState { db: DbPool }
///
/// fn handler(State(state): State<AppState>) -> String {
///     // use state.db
///     "ok".into()
/// }
///
/// let handler = FnHandler1::<_, State<AppState>>::new(handler);
/// let app = Router::new()
///     .route("/", get(handler))
///     .with_state(AppState { db });
/// ```
#[derive(Debug, Clone)]
pub struct State<T>(pub T);

impl<T> FromRequestParts for State<T>
where
    T: Clone + Send + Sync + 'static,
{
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        req.extensions
            .get_typed_cloned::<T>()
            .map(Self)
            .ok_or_else(|| {
                ExtractionError::new(
                    super::response::StatusCode::INTERNAL_SERVER_ERROR,
                    format!("state not configured for {}", std::any::type_name::<T>()),
                )
            })
    }
}

// ─── Extension<T> ────────────────────────────────────────────────────────────

/// Extract a typed value injected by middleware.
///
/// Middleware inserts values into the request's [`Extensions`] store with
/// [`Extensions::insert_typed`]; handlers extract them with `Extension<T>`.
/// The value lives on the [`Request`] itself, so it is request-scoped: each
/// request carries its own extensions map, with no bleed between requests,
/// and the map is dropped with the request when handling completes (inside
/// the request region when the server dispatches through one).
///
/// Difference from [`State<T>`]: `State` carries application-lifetime shared
/// state injected once via `Router::with_state`; `Extension` carries
/// per-request values injected by middleware (auth principals, request
/// metadata, trace context, ...). Both read the same typed store.
///
/// Missing extensions are a server-side wiring bug, so extraction failure
/// maps to `500 Internal Server Error` (matching [`State<T>`]).
///
/// ```
/// use asupersync::web::extract::{Extension, FromRequestParts, Request};
///
/// #[derive(Clone, Debug, PartialEq)]
/// struct CurrentUser {
///     id: u64,
/// }
///
/// // Middleware inserts:
/// let mut req = Request::new("GET", "/me");
/// req.extensions.insert_typed(CurrentUser { id: 42 });
///
/// // Handler extracts:
/// let Extension(user) =
///     Extension::<CurrentUser>::from_request_parts(&req).expect("extension present");
/// assert_eq!(user, CurrentUser { id: 42 });
/// ```
#[derive(Debug, Clone)]
pub struct Extension<T>(pub T);

impl<T> FromRequestParts for Extension<T>
where
    T: Clone + Send + Sync + 'static,
{
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        req.extensions
            .get_typed_cloned::<T>()
            .map(Self)
            .ok_or_else(|| {
                ExtractionError::new(
                    super::response::StatusCode::INTERNAL_SERVER_ERROR,
                    format!("missing request extension {}", std::any::type_name::<T>()),
                )
            })
    }
}

// ─── RawBody ─────────────────────────────────────────────────────────────────

/// Extract the raw request body as bytes.
#[derive(Debug, Clone)]
pub struct RawBody(pub Bytes);

impl FromRequest for RawBody {
    fn from_request(req: Request) -> Result<Self, ExtractionError> {
        #[cfg(not(target_arch = "wasm32"))]
        reject_buffered_extractor_on_streaming_request(&req, "RawBody")?;

        let limit = effective_body_limits(&req).max_raw_body_size;

        // SECURITY: Check Content-Length header BEFORE reading body to prevent DoS
        check_content_length_limit(&req, limit)?;

        if req.body.len() > limit {
            return Err(ExtractionError::new(
                super::response::StatusCode::PAYLOAD_TOO_LARGE,
                format!(
                    "raw body too large: {} bytes (limit {})",
                    req.body.len(),
                    limit
                ),
            ));
        }

        // Reject invalid or mismatched framing metadata before exposing body bytes.
        validate_content_length(&req)?;

        Ok(Self(req.body))
    }
}

// ─── StreamingRawBody ───────────────────────────────────────────────────────

/// Extract the live HTTP/1 request body without implicitly collecting it.
///
/// This additive extractor is available only on the HTTP/1 streaming Router
/// path. Existing [`RawBody`] handlers retain their buffered byte contract.
/// The body remains single-consumer and cancel-correct: dropping it before EOF
/// tells the protocol driver to apply its bounded drain-or-close policy.
#[cfg(not(target_arch = "wasm32"))]
#[pin_project::pin_project]
#[derive(Debug)]
pub struct StreamingRawBody {
    #[pin]
    inner: IncomingRequestBody,
}

/// Contiguous collection storage whose retained capacity is within the
/// caller's byte budget after each successful append.
///
/// `Vec::extend_from_slice` normally grows geometrically, so checking only the
/// resulting length can retain more allocation than the configured body
/// limit. Reserve each required length exactly, shrink an allocator-granted
/// excess back to the budget, and fail closed before copying if the reported
/// capacity still exceeds it.
#[cfg(not(target_arch = "wasm32"))]
#[derive(Debug)]
struct BoundedCollectionBuffer {
    data: Vec<u8>,
    max_bytes: usize,
}

#[cfg(not(target_arch = "wasm32"))]
impl BoundedCollectionBuffer {
    fn new(max_bytes: usize) -> Self {
        Self {
            data: Vec::new(),
            max_bytes,
        }
    }

    fn extend_from_slice(&mut self, chunk: &[u8]) -> Result<(), StreamingRawBodyCollectError> {
        let Some(next_len) = self.data.len().checked_add(chunk.len()) else {
            return Err(StreamingRawBodyCollectError::LengthLimitExceeded {
                actual: None,
                limit: self.max_bytes,
            });
        };
        if next_len > self.max_bytes {
            return Err(StreamingRawBodyCollectError::LengthLimitExceeded {
                actual: u64::try_from(next_len).ok(),
                limit: self.max_bytes,
            });
        }

        if next_len > self.data.capacity() {
            self.data
                .try_reserve_exact(next_len - self.data.len())
                .map_err(|_| {
                    StreamingRawBodyCollectError::Body(IncomingBodyError::AccountingOverflow)
                })?;
            if self.data.capacity() > self.max_bytes {
                self.data.shrink_to(self.max_bytes);
            }
            if self.data.capacity() > self.max_bytes {
                return Err(StreamingRawBodyCollectError::Body(
                    IncomingBodyError::AccountingOverflow,
                ));
            }
        }

        self.data.extend_from_slice(chunk);
        debug_assert!(self.data.len() <= self.max_bytes);
        debug_assert!(self.data.capacity() <= self.max_bytes);
        Ok(())
    }

    fn into_bytes(self) -> Bytes {
        self.data.into()
    }

    #[cfg(test)]
    fn retained_capacity(&self) -> usize {
        self.data.capacity()
    }
}

#[cfg(not(target_arch = "wasm32"))]
impl StreamingRawBody {
    fn take_from_request(req: &Request) -> Result<Self, ExtractionError> {
        let slot = req
            .extensions
            .get_typed::<StreamingRawBodySlot>()
            .ok_or_else(|| {
                ExtractionError::new(
                    super::response::StatusCode::INTERNAL_SERVER_ERROR,
                    "streaming request body unavailable on this transport",
                )
            })?;
        let max_bytes = effective_request_body_policy(req).map(|policy| policy.max_total_body_size);
        if let Some(max_bytes) = max_bytes {
            check_content_length_limit(req, max_bytes)?;
        }
        slot.take()
            .map(|inner| {
                if let Some(max_bytes) = max_bytes {
                    inner.tighten_max_body_size(u64::try_from(max_bytes).unwrap_or(u64::MAX));
                }
                Self { inner }
            })
            .map_err(|message| {
                ExtractionError::new(super::response::StatusCode::INTERNAL_SERVER_ERROR, message)
            })
    }

    /// Return the framing mode declared by the validated request head.
    #[must_use]
    pub fn kind(&self) -> BodyKind {
        self.inner.kind()
    }

    /// Return bytes currently retained by the bounded incoming-frame queue.
    #[must_use]
    pub fn queued_bytes(&self) -> usize {
        self.inner.queued_bytes()
    }

    /// Consume this wrapper and return the hardened HTTP/1 body.
    #[must_use]
    pub fn into_inner(self) -> IncomingRequestBody {
        self.inner
    }

    /// Explicitly collect the stream under a caller-selected byte limit.
    ///
    /// Data-frame order and the terminal trailer map are preserved. Exceeding
    /// the limit drops the live consumer; the HTTP/1 driver then performs its
    /// existing bounded unread-body drain before considering connection reuse.
    pub async fn collect_bounded(
        self,
        max_bytes: usize,
    ) -> Result<CollectedStreamingRawBody, StreamingRawBodyCollectError> {
        self.collect_bounded_inner(None, max_bytes).await
    }

    /// Collect the stream while also checkpointing an explicit caller context.
    ///
    /// This is the preferred Router-handler form because it observes both the
    /// body driver's request context and the handler's authoritative context.
    pub async fn collect_bounded_with_cx(
        self,
        cx: &Cx,
        max_bytes: usize,
    ) -> Result<CollectedStreamingRawBody, StreamingRawBodyCollectError> {
        self.collect_bounded_inner(Some(cx), max_bytes).await
    }

    async fn collect_bounded_inner(
        self,
        cx: Option<&Cx>,
        max_bytes: usize,
    ) -> Result<CollectedStreamingRawBody, StreamingRawBodyCollectError> {
        let max_bytes_u64 = u64::try_from(max_bytes).unwrap_or(u64::MAX);
        if let Some(upper) = self.size_hint().upper()
            && upper > max_bytes_u64
        {
            return Err(StreamingRawBodyCollectError::LengthLimitExceeded {
                actual: Some(upper),
                limit: max_bytes,
            });
        }

        let mut body = Limited::new(self, max_bytes_u64);
        let mut data = BoundedCollectionBuffer::new(max_bytes);
        let mut trailers = None;
        loop {
            if let Some(cx) = cx
                && cx.checkpoint().is_err()
            {
                let kind = cx
                    .cancel_reason()
                    .map_or(CancelKind::User, |reason| reason.kind());
                return Err(StreamingRawBodyCollectError::Body(
                    IncomingBodyError::Cancelled { kind },
                ));
            }
            let frame =
                match std::future::poll_fn(|poll_cx| Pin::new(&mut body).poll_frame(poll_cx)).await
                {
                    Some(Ok(frame)) => frame,
                    Some(Err(LimitedError::LengthLimit)) => {
                        return Err(StreamingRawBodyCollectError::LengthLimitExceeded {
                            actual: body.length_limit_actual(),
                            limit: max_bytes,
                        });
                    }
                    Some(Err(LimitedError::Inner(error))) => {
                        return Err(StreamingRawBodyCollectError::Body(error));
                    }
                    Some(Err(LimitedError::PolledAfterCompletion)) => {
                        return Err(StreamingRawBodyCollectError::Body(
                            IncomingBodyError::AlreadyTerminal,
                        ));
                    }
                    None => break,
                };
            match frame {
                Frame::Data(chunk) => {
                    data.extend_from_slice(chunk.chunk())?;
                }
                Frame::Trailers(frame_trailers) => trailers = Some(frame_trailers),
            }
        }

        Ok(CollectedStreamingRawBody {
            data: data.into_bytes(),
            trailers,
        })
    }
}

#[cfg(not(target_arch = "wasm32"))]
impl Body for StreamingRawBody {
    type Data = BytesCursor;
    type Error = IncomingBodyError;

    fn poll_frame(
        self: Pin<&mut Self>,
        poll_cx: &mut Context<'_>,
    ) -> Poll<Option<Result<Frame<Self::Data>, Self::Error>>> {
        self.project().inner.poll_frame(poll_cx)
    }

    fn is_end_stream(&self) -> bool {
        self.inner.is_end_stream()
    }

    fn size_hint(&self) -> SizeHint {
        self.inner.size_hint()
    }
}

/// Bytes and trailers returned by [`StreamingRawBody::collect_bounded`].
#[cfg(not(target_arch = "wasm32"))]
#[derive(Debug)]
pub struct CollectedStreamingRawBody {
    data: Bytes,
    trailers: Option<HeaderMap>,
}

#[cfg(not(target_arch = "wasm32"))]
impl CollectedStreamingRawBody {
    /// Return the collected data bytes.
    #[must_use]
    pub fn data(&self) -> &Bytes {
        &self.data
    }

    /// Return the terminal trailer map, when the request carried trailers.
    #[must_use]
    pub fn trailers(&self) -> Option<&HeaderMap> {
        self.trailers.as_ref()
    }

    /// Consume the collection and return its data plus terminal trailers.
    #[must_use]
    pub fn into_parts(self) -> (Bytes, Option<HeaderMap>) {
        (self.data, self.trailers)
    }
}

/// Failure from [`StreamingRawBody::collect_bounded`].
#[cfg(not(target_arch = "wasm32"))]
#[derive(Debug)]
pub enum StreamingRawBodyCollectError {
    /// The declared or observed data length exceeded the caller's limit.
    LengthLimitExceeded {
        /// Declared or observed length, when representable.
        actual: Option<u64>,
        /// Caller-selected maximum number of bytes.
        limit: usize,
    },
    /// The HTTP/1 request-body protocol terminated with an error.
    Body(IncomingBodyError),
}

#[cfg(not(target_arch = "wasm32"))]
pub(super) fn streaming_extraction_error(
    extractor: &str,
    error: StreamingRawBodyCollectError,
) -> ExtractionError {
    use super::response::StatusCode;

    let too_large = |actual: Option<u64>, limit: u64| {
        let message = actual.map_or_else(
            || format!("{extractor} body too large (limit {limit})"),
            |actual| format!("{extractor} body too large: {actual} bytes (limit {limit})"),
        );
        ExtractionError::new(StatusCode::PAYLOAD_TOO_LARGE, message)
    };

    match error {
        StreamingRawBodyCollectError::LengthLimitExceeded { actual, limit } => {
            too_large(actual, u64::try_from(limit).unwrap_or(u64::MAX))
        }
        StreamingRawBodyCollectError::Body(IncomingBodyError::BodyTooLarge { actual, limit }) => {
            too_large(actual, limit)
        }
        StreamingRawBodyCollectError::Body(IncomingBodyError::QueueFrameTooLarge {
            actual,
            limit,
        }) => too_large(
            u64::try_from(actual).ok(),
            u64::try_from(limit).unwrap_or(u64::MAX),
        ),
        StreamingRawBodyCollectError::Body(IncomingBodyError::AccountingOverflow) => {
            ExtractionError::new(
                StatusCode::INTERNAL_SERVER_ERROR,
                format!("failed to account for {extractor} request body"),
            )
        }
        StreamingRawBodyCollectError::Body(IncomingBodyError::Cancelled {
            kind:
                CancelKind::Timeout
                | CancelKind::Deadline
                | CancelKind::PollQuota
                | CancelKind::CostBudget
                | CancelKind::ResourceUnavailable,
        }) => ExtractionError::new(
            StatusCode::SERVICE_UNAVAILABLE,
            format!("{extractor} request body unavailable"),
        ),
        // `ExtractionError` is converted directly into a web `Response`, so it
        // cannot yet carry the protocol-level "record cancellation without a
        // response" disposition. Retain the pre-existing web 499
        // representation for these residual kinds until the Handler boundary
        // can propagate `ServerHopOutcome::Cancelled`.
        StreamingRawBodyCollectError::Body(IncomingBodyError::Cancelled { .. }) => {
            ExtractionError::new(
                StatusCode::CLIENT_CLOSED_REQUEST,
                format!("{extractor} request body cancelled"),
            )
        }
        StreamingRawBodyCollectError::Body(
            IncomingBodyError::BadContentLength
            | IncomingBodyError::BadChunkedEncoding
            | IncomingBodyError::TrailersTooLarge
            | IncomingBodyError::BadHeader
            | IncomingBodyError::InvalidHeaderName
            | IncomingBodyError::InvalidHeaderValue,
        ) => ExtractionError::bad_request(format!("invalid {extractor} request body")),
        StreamingRawBodyCollectError::Body(IncomingBodyError::SourceDisconnected) => {
            ExtractionError::new(
                StatusCode::INTERNAL_SERVER_ERROR,
                format!("failed to read {extractor} request body"),
            )
        }
        StreamingRawBodyCollectError::Body(
            IncomingBodyError::ConsumerDropped
            | IncomingBodyError::DrainLimitExceeded { .. }
            | IncomingBodyError::DrainTimeout
            | IncomingBodyError::AlreadyTerminal,
        ) => ExtractionError::new(
            StatusCode::INTERNAL_SERVER_ERROR,
            format!("failed to read {extractor} request body"),
        ),
    }
}

#[cfg(not(target_arch = "wasm32"))]
impl fmt::Display for StreamingRawBodyCollectError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::LengthLimitExceeded {
                actual: Some(actual),
                limit,
            } => write!(
                f,
                "streaming raw body too large: {actual} bytes (limit {limit})"
            ),
            Self::LengthLimitExceeded {
                actual: None,
                limit,
            } => write!(f, "streaming raw body length overflowed (limit {limit})"),
            Self::Body(error) => write!(f, "streaming raw body failed: {error}"),
        }
    }
}

#[cfg(not(target_arch = "wasm32"))]
impl std::error::Error for StreamingRawBodyCollectError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Body(error) => Some(error),
            Self::LengthLimitExceeded { .. } => None,
        }
    }
}

#[cfg(not(target_arch = "wasm32"))]
#[derive(Clone)]
pub(crate) struct StreamingRawBodySlot {
    state: Arc<Mutex<StreamingRawBodySlotState>>,
}

#[cfg(not(target_arch = "wasm32"))]
enum StreamingRawBodySlotState {
    Available(IncomingRequestBody),
    Taken,
    Closed,
}

#[cfg(not(target_arch = "wasm32"))]
impl StreamingRawBodySlot {
    fn new(body: IncomingRequestBody) -> Self {
        Self {
            state: Arc::new(Mutex::new(StreamingRawBodySlotState::Available(body))),
        }
    }

    fn take(&self) -> Result<IncomingRequestBody, &'static str> {
        let mut state = self.state.lock();
        match std::mem::replace(&mut *state, StreamingRawBodySlotState::Closed) {
            StreamingRawBodySlotState::Available(body) => {
                *state = StreamingRawBodySlotState::Taken;
                Ok(body)
            }
            StreamingRawBodySlotState::Taken => {
                *state = StreamingRawBodySlotState::Taken;
                Err("streaming request body was already extracted")
            }
            StreamingRawBodySlotState::Closed => {
                Err("streaming request body is no longer available")
            }
        }
    }

    fn tighten_max_body_size(&self, bytes: u64) {
        if let StreamingRawBodySlotState::Available(body) = &*self.state.lock() {
            body.tighten_max_body_size(bytes);
        }
    }

    /// Drop an unclaimed body outside the state lock so producer wakeups
    /// cannot re-enter while the one-shot ownership guard is held.
    pub(crate) fn drop_unclaimed(&self) {
        let body = {
            let mut state = self.state.lock();
            match std::mem::replace(&mut *state, StreamingRawBodySlotState::Closed) {
                StreamingRawBodySlotState::Available(body) => Some(body),
                StreamingRawBodySlotState::Taken => {
                    *state = StreamingRawBodySlotState::Taken;
                    None
                }
                StreamingRawBodySlotState::Closed => None,
            }
        };
        drop(body);
    }
}

#[cfg(not(target_arch = "wasm32"))]
pub(crate) fn insert_streaming_raw_body(
    req: &mut Request,
    body: IncomingRequestBody,
) -> Result<StreamingRawBodyControl, IncomingRequestBody> {
    if req.extensions.get_typed::<StreamingRawBodySlot>().is_some() {
        return Err(body);
    }
    let slot = StreamingRawBodySlot::new(body);
    req.extensions.insert_typed(slot.clone());
    Ok(StreamingRawBodyControl(slot))
}

#[cfg(not(target_arch = "wasm32"))]
pub(crate) fn tighten_streaming_raw_body(req: &Request, max_bytes: usize) {
    if let Some(slot) = req.extensions.get_typed::<StreamingRawBodySlot>() {
        slot.tighten_max_body_size(u64::try_from(max_bytes).unwrap_or(u64::MAX));
    }
}

#[cfg(not(target_arch = "wasm32"))]
pub(crate) struct StreamingRawBodyControl(StreamingRawBodySlot);

#[cfg(not(target_arch = "wasm32"))]
impl Drop for StreamingRawBodyControl {
    fn drop(&mut self) {
        self.0.drop_unclaimed();
    }
}

#[cfg(not(target_arch = "wasm32"))]
pub(super) fn reject_buffered_extractor_on_streaming_request(
    req: &Request,
    extractor: &str,
) -> Result<(), ExtractionError> {
    if req.extensions.get_typed::<StreamingRawBodySlot>().is_none() {
        return Ok(());
    }
    Err(ExtractionError::new(
        super::response::StatusCode::INTERNAL_SERVER_ERROR,
        format!("{extractor} cannot consume a streaming request; use StreamingRawBody"),
    ))
}

#[cfg(not(target_arch = "wasm32"))]
impl FromRequest for StreamingRawBody {
    fn from_request(req: Request) -> Result<Self, ExtractionError> {
        Self::take_from_request(&req)
    }
}

// ─── HeaderMap Extractor ─────────────────────────────────────────────────────

#[allow(clippy::implicit_hasher)]
impl FromRequestParts for HashMap<String, String> {
    fn from_request_parts(req: &Request) -> Result<Self, ExtractionError> {
        Ok(req.headers.clone())
    }
}

// ─── Tests ───────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    #![allow(
        clippy::pedantic,
        clippy::nursery,
        clippy::expect_fun_call,
        clippy::map_unwrap_or,
        clippy::cast_possible_wrap,
        clippy::future_not_send
    )]
    use super::*;

    #[cfg(not(target_arch = "wasm32"))]
    fn block_on<F: std::future::Future>(future: F) -> F::Output {
        let waker = std::task::Waker::noop().clone();
        let mut task_cx = Context::from_waker(&waker);
        let mut future = std::pin::pin!(future);
        loop {
            match std::future::Future::poll(future.as_mut(), &mut task_cx) {
                Poll::Ready(output) => return output,
                Poll::Pending => std::thread::yield_now(),
            }
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    fn streaming_extractor_request(
        cx: &Cx,
        kind: BodyKind,
        content_type: &str,
        limit: usize,
    ) -> (
        crate::http::h1::stream::IncomingRequestBodyWriter,
        Request,
        StreamingRawBodyControl,
    ) {
        let (writer, body) = IncomingRequestBody::channel(cx, kind);
        let mut req = Request::new("POST", "/streamed").with_header("content-type", content_type);
        if let BodyKind::ContentLength(length) = kind {
            req = req.with_header("content-length", length.to_string());
        }
        req.extensions.insert_typed(
            BodyLimits::new()
                .max_json_body_size(limit)
                .max_form_body_size(limit),
        );
        let control = insert_streaming_raw_body(&mut req, body).expect("install streaming body");
        (writer, req, control)
    }

    #[test]
    fn path_extraction() {
        let mut params = HashMap::new();
        params.insert("id".to_string(), "42".to_string());
        let req = Request::new("GET", "/users/42").with_path_params(params);

        let Path(id) = Path::<String>::from_request_parts(&req).unwrap();
        assert_eq!(id, "42");
    }

    #[test]
    fn query_extraction() {
        let req = Request::new("GET", "/items").with_query("page=3&sort=name");
        let Query(params) = Query::<HashMap<String, String>>::from_request_parts(&req).unwrap();
        assert_eq!(params.get("page").unwrap(), "3");
        assert_eq!(params.get("sort").unwrap(), "name");
    }

    #[test]
    fn path_typed_numeric_extraction() {
        let mut params = HashMap::new();
        params.insert("id".to_string(), "42".to_string());
        let req = Request::new("GET", "/users/42").with_path_params(params);

        let Path(id) = Path::<u64>::from_request_parts(&req).unwrap();
        assert_eq!(id, 42);
    }

    #[test]
    fn path_typed_struct_extraction() {
        #[derive(Debug, serde::Deserialize, PartialEq, Eq)]
        struct Params {
            user_id: u64,
            post_id: u32,
        }

        let mut params = HashMap::new();
        params.insert("user_id".to_string(), "7".to_string());
        params.insert("post_id".to_string(), "11".to_string());
        let req = Request::new("GET", "/users/7/posts/11").with_path_params(params);

        let Path(extracted) = Path::<Params>::from_request_parts(&req).unwrap();
        assert_eq!(
            extracted,
            Params {
                user_id: 7,
                post_id: 11
            }
        );
    }

    #[test]
    fn path_typed_deserialization_error() {
        let mut params = HashMap::new();
        params.insert("id".to_string(), "not-a-number".to_string());
        let req = Request::new("GET", "/users/not-a-number").with_path_params(params);

        let err = Path::<u64>::from_request_parts(&req).unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
        assert!(err.message.contains("invalid path parameters"));
    }

    #[test]
    fn content_length_parser_accepts_single_and_identical_combined_values() {
        assert_eq!(parse_content_length("42").unwrap(), 42);
        assert_eq!(parse_content_length("42, 42").unwrap(), 42);
        assert_eq!(parse_content_length("0042, 42").unwrap(), 42);
    }

    #[test]
    fn content_length_parser_rejects_invalid_or_conflicting_values() {
        // "+5"/"+42": Rust's usize parser accepts a leading '+', but RFC 9110
        // §8.6 forbids it — a fronting proxy may frame it differently
        // (smuggling/desync), so it must be rejected.
        for value in [
            "",
            "5, ",
            "5, 6",
            "not-a-number",
            "-1",
            "+5",
            "+42",
            "5, +5",
            "0x10",
            "1 2",
        ] {
            let err = parse_content_length(value).unwrap_err();
            assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
        }
    }

    #[test]
    fn json_extraction() {
        #[derive(Debug, serde::Deserialize, PartialEq)]
        struct Input {
            name: String,
        }

        let req = Request::new("POST", "/users")
            .with_header("content-type", "application/json")
            .with_body(Bytes::from_static(b"{\"name\":\"alice\"}"));

        let Json(input) = Json::<Input>::from_request(req).unwrap();
        assert_eq!(input.name, "alice");
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn streaming_json_and_form_buffered_async_hook_parity() {
        let cx = Cx::for_testing();

        let json_req = Request::new("POST", "/json")
            .with_header("content-type", "application/json")
            .with_body(Bytes::from_static(br#"{"name":"alice"}"#));
        let expected_json = Json::<serde_json::Value>::from_request(json_req.clone())
            .expect("buffered JSON")
            .0;
        let actual_json = block_on(Json::<serde_json::Value>::from_request_with_cx(
            &cx, json_req,
        ))
        .expect("async-hook buffered JSON")
        .0;
        assert_eq!(actual_json, expected_json);

        let form_req = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(b"user=alice&role=admin"));
        let expected_form = Form::<HashMap<String, String>>::from_request(form_req.clone())
            .expect("buffered form")
            .0;
        let actual_form = block_on(Form::<HashMap<String, String>>::from_request_with_cx(
            &cx, form_req,
        ))
        .expect("async-hook buffered form")
        .0;
        assert_eq!(actual_form, expected_form);
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn streaming_json_and_form_bounded_collection_caps_fragmented_capacity() {
        let mut zero = BoundedCollectionBuffer::new(0);
        zero.extend_from_slice(b"")
            .expect("empty body fits zero limit");
        assert_eq!(zero.retained_capacity(), 0);
        assert!(matches!(
            zero.extend_from_slice(b"x"),
            Err(StreamingRawBodyCollectError::LengthLimitExceeded {
                actual: Some(1),
                limit: 0,
            })
        ));

        let mut fragmented = BoundedCollectionBuffer::new(10);
        for chunk in [b"a".as_slice(), b"bc", b"def", b"ghij"] {
            fragmented
                .extend_from_slice(chunk)
                .expect("fragment fits collection limit");
            assert!(fragmented.retained_capacity() <= 10);
        }
        assert_eq!(fragmented.data.as_slice(), b"abcdefghij");

        assert!(matches!(
            fragmented.extend_from_slice(b"k"),
            Err(StreamingRawBodyCollectError::LengthLimitExceeded {
                actual: Some(11),
                limit: 10,
            })
        ));
        assert_eq!(fragmented.data.as_slice(), b"abcdefghij");
        assert!(fragmented.retained_capacity() <= 10);
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn body_policy_streaming_raw_body_enforces_actual_chunked_bytes() {
        let cx = Cx::for_testing();
        let (mut writer, incoming) = IncomingRequestBody::channel(&cx, BodyKind::Chunked);
        let mut request = Request::new("POST", "/streamed");
        request
            .extensions
            .insert_typed(super::super::RequestBodyPolicy::new().max_total_body_size(6));
        let control = insert_streaming_raw_body(&mut request, incoming)
            .expect("install policy-limited streaming body");
        block_on(writer.push_bytes(&cx, b"4\r\nABCD\r\n4\r\nEFGH\r\n0\r\n\r\n"))
            .expect("publish chunked body through protocol decoder");

        let body = StreamingRawBody::from_request(request).expect("take streaming body");
        let error = block_on(body.collect_bounded_with_cx(&cx, 32))
            .expect_err("actual bytes above policy total must fail");
        assert!(matches!(
            error,
            StreamingRawBodyCollectError::Body(IncomingBodyError::BodyTooLarge {
                actual: Some(8),
                limit: 6,
            })
        ));
        drop(control);
    }

    #[test]
    fn body_policy_enforced_snapshot_prevents_late_body_limit_loosen() {
        let enforced = super::super::RequestBodyPolicy::new()
            .max_total_body_size(1024)
            .body_limits(BodyLimits::new().max_json_body_size(4))
            .resolved();
        let mut request = Request::new("POST", "/json")
            .with_header("content-type", "application/json")
            .with_body(Bytes::from_static(b"{\"x\":1}"));
        request
            .extensions
            .insert_typed(super::super::EnforcedRequestBodyPolicy { policy: enforced });
        request.extensions.insert_typed(
            super::super::RequestBodyPolicy::new()
                .max_total_body_size(4096)
                .body_limits(BodyLimits::new().max_json_body_size(4096)),
        );
        request
            .extensions
            .insert_typed(BodyLimits::new().max_json_body_size(4096));

        let reported = request
            .body_policy()
            .expect("protected effective policy remains inspectable");
        assert_eq!(reported.body_limits.max_json_body_size, 4);
        assert_eq!(reported.max_total_body_size, 1024);

        let error = Json::<serde_json::Value>::from_request(request)
            .expect_err("late middleware must not loosen locked JSON limit");
        assert_eq!(
            error.status,
            super::super::response::StatusCode::PAYLOAD_TOO_LARGE
        );
    }

    #[test]
    fn body_policy_accessor_includes_tighter_legacy_projections() {
        let enforced = super::super::RequestBodyPolicy::new()
            .max_total_body_size(1024)
            .body_limits(BodyLimits::new().max_json_body_size(10))
            .multipart_limits(
                super::super::multipart::MultipartLimits::new().max_part_body_size(12),
            )
            .resolved();
        let mut request = Request::new("POST", "/upload");
        request
            .extensions
            .insert_typed(super::super::EnforcedRequestBodyPolicy { policy: enforced });
        request
            .extensions
            .insert_typed(BodyLimits::new().max_json_body_size(4));
        request
            .extensions
            .insert_typed(super::super::multipart::MultipartLimits::new().max_part_body_size(3));

        let reported = request
            .body_policy()
            .expect("protected effective policy remains inspectable");
        assert_eq!(reported.max_total_body_size, 1024);
        assert_eq!(reported.body_limits.max_json_body_size, 4);
        assert_eq!(reported.multipart_limits.max_part_body_size, 3);
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn body_policy_unconfigured_chunked_body_preserves_unknown_upper_hint() {
        let cx = Cx::for_testing();
        let (mut writer, incoming) = IncomingRequestBody::channel(&cx, BodyKind::Chunked);
        let mut request = Request::new("POST", "/streamed");
        let control = insert_streaming_raw_body(&mut request, incoming)
            .expect("install unconfigured streaming body");
        let body = StreamingRawBody::from_request(request).expect("take streaming body");
        assert_eq!(body.size_hint().upper(), None);

        block_on(writer.push_bytes(&cx, b"4\r\nbody\r\n0\r\n\r\n"))
            .expect("publish bounded chunked body");
        let collected = block_on(body.collect_bounded_with_cx(&cx, 4))
            .expect("unconfigured chunked body remains collectable");
        assert_eq!(collected.data().as_ref(), b"body");
        drop(control);
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn body_policy_streaming_raw_body_rejects_declared_length_before_take() {
        let cx = Cx::for_testing();
        let (writer, incoming) = IncomingRequestBody::channel(&cx, BodyKind::ContentLength(8));
        let mut request = Request::new("POST", "/streamed").with_header("content-length", "8");
        request
            .extensions
            .insert_typed(super::super::RequestBodyPolicy::new().max_total_body_size(6));
        let control = insert_streaming_raw_body(&mut request, incoming)
            .expect("install policy-limited streaming body");

        let error = StreamingRawBody::from_request(request)
            .expect_err("declared length above policy must fail before take");
        assert_eq!(
            error.status,
            super::super::response::StatusCode::PAYLOAD_TOO_LARGE
        );
        assert!(!writer.consumer_dropped());
        drop(control);
        assert!(writer.consumer_dropped());
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn body_policy_streaming_raw_body_into_inner_retains_limit_and_size_hint() {
        let cx = Cx::for_testing();
        let (mut writer, incoming) = IncomingRequestBody::channel(&cx, BodyKind::Chunked);
        let mut request = Request::new("POST", "/streamed");
        request
            .extensions
            .insert_typed(super::super::RequestBodyPolicy::new().max_total_body_size(6));
        let control = insert_streaming_raw_body(&mut request, incoming)
            .expect("install policy-limited streaming body");
        let body = StreamingRawBody::from_request(request).expect("take streaming body");
        let mut body = body.into_inner();
        assert_eq!(body.size_hint().upper(), Some(6));

        block_on(writer.push_bytes(&cx, b"4\r\nABCD\r\n"))
            .expect("first chunk stays inside policy");
        let frame = block_on(std::future::poll_fn(|poll_cx| {
            Pin::new(&mut body).poll_frame(poll_cx)
        }))
        .expect("first frame")
        .expect("first frame succeeds");
        assert_eq!(frame.data_ref().expect("DATA frame").remaining(), 4);
        assert_eq!(body.size_hint().upper(), Some(2));

        let writer_error = block_on(writer.push_bytes(&cx, b"3\r\nEFG\r\n0\r\n\r\n"))
            .expect_err("inner body must retain the route policy");
        assert!(matches!(
            writer_error,
            IncomingBodyError::BodyTooLarge {
                actual: Some(7),
                limit: 6,
            }
        ));
        let body_error = block_on(std::future::poll_fn(|poll_cx| {
            Pin::new(&mut body).poll_frame(poll_cx)
        }))
        .expect("terminal policy error")
        .expect_err("body observes policy error");
        assert!(matches!(
            body_error,
            IncomingBodyError::BodyTooLarge {
                actual: Some(7),
                limit: 6,
            }
        ));
        assert_eq!(body.size_hint().exact(), Some(0));
        drop(control);
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn streaming_json_and_form_enforce_declared_and_actual_limits() {
        let cx = Cx::for_testing();

        let (json_writer, json_req, json_control) =
            streaming_extractor_request(&cx, BodyKind::ContentLength(8), "application/json", 7);
        let error = block_on(Json::<serde_json::Value>::from_request_with_cx(
            &cx, json_req,
        ))
        .expect_err("declared JSON length must fail before body polling");
        assert_eq!(
            error.status,
            super::super::response::StatusCode::PAYLOAD_TOO_LARGE
        );
        assert!(!json_writer.consumer_dropped());
        drop(json_control);
        assert!(json_writer.consumer_dropped());

        let (form_writer, form_req, form_control) = streaming_extractor_request(
            &cx,
            BodyKind::ContentLength(8),
            "application/x-www-form-urlencoded",
            7,
        );
        let error = block_on(Form::<HashMap<String, String>>::from_request_with_cx(
            &cx, form_req,
        ))
        .expect_err("declared form length must fail before body polling");
        assert_eq!(
            error.status,
            super::super::response::StatusCode::PAYLOAD_TOO_LARGE
        );
        assert!(!form_writer.consumer_dropped());
        drop(form_control);
        assert!(form_writer.consumer_dropped());

        let (mut empty_form_writer, empty_form_req, empty_form_control) =
            streaming_extractor_request(
                &cx,
                BodyKind::Chunked,
                "application/x-www-form-urlencoded",
                0,
            );
        block_on(empty_form_writer.push_bytes(&cx, b"0\r\n\r\n"))
            .expect("publish zero-length chunked form");
        let Form(values) = block_on(Form::<HashMap<String, String>>::from_request_with_cx(
            &cx,
            empty_form_req,
        ))
        .expect("zero-length form without content-length");
        assert!(values.is_empty());
        drop(empty_form_control);

        let (mut json_writer, json_req, json_control) =
            streaming_extractor_request(&cx, BodyKind::Chunked, "application/json", 7);
        block_on(json_writer.push_bytes(&cx, b"7\r\n{\"x\":1}\r\n0\r\n\r\n"))
            .expect("publish exact-limit chunked JSON");
        let Json(value) = block_on(Json::<serde_json::Value>::from_request_with_cx(
            &cx, json_req,
        ))
        .expect("exact-limit chunked JSON");
        assert_eq!(value["x"], 1);
        drop(json_control);

        let (mut form_writer, form_req, form_control) = streaming_extractor_request(
            &cx,
            BodyKind::Chunked,
            "application/x-www-form-urlencoded",
            7,
        );
        block_on(form_writer.push_bytes(&cx, b"7\r\na=12345\r\n0\r\n\r\n"))
            .expect("publish exact-limit chunked form");
        let Form(values) = block_on(Form::<HashMap<String, String>>::from_request_with_cx(
            &cx, form_req,
        ))
        .expect("exact-limit chunked form");
        assert_eq!(values.get("a").map(String::as_str), Some("12345"));
        drop(form_control);

        let (mut json_writer, json_req, json_control) =
            streaming_extractor_request(&cx, BodyKind::Chunked, "application/json", 7);
        block_on(json_writer.push_bytes(&cx, b"8\r\n{\"x\":12}\r\n0\r\n\r\n"))
            .expect("publish over-limit chunked JSON");
        let error = block_on(Json::<serde_json::Value>::from_request_with_cx(
            &cx, json_req,
        ))
        .expect_err("actual streamed JSON length must be capped");
        assert_eq!(
            error.status,
            super::super::response::StatusCode::PAYLOAD_TOO_LARGE
        );
        assert!(error.message.contains("8 bytes (limit 7)"));
        drop(json_control);

        let (mut form_writer, form_req, form_control) = streaming_extractor_request(
            &cx,
            BodyKind::Chunked,
            "application/x-www-form-urlencoded",
            7,
        );
        block_on(form_writer.push_bytes(&cx, b"8\r\na=123456\r\n0\r\n\r\n"))
            .expect("publish over-limit chunked form");
        let error = block_on(Form::<HashMap<String, String>>::from_request_with_cx(
            &cx, form_req,
        ))
        .expect_err("actual streamed form length must be capped");
        assert_eq!(
            error.status,
            super::super::response::StatusCode::PAYLOAD_TOO_LARGE
        );
        assert!(error.message.contains("8 bytes (limit 7)"));
        drop(form_control);
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn streaming_json_and_form_fail_closed_on_transport_errors_and_cancellation() {
        let cx = Cx::for_testing();

        let (mut json_writer, json_req, json_control) =
            streaming_extractor_request(&cx, BodyKind::ContentLength(7), "application/json", 7);
        block_on(json_writer.push_bytes(&cx, b"{}")).expect("publish truncated fixed JSON prefix");
        assert_eq!(
            json_writer.finish(&cx),
            Err(IncomingBodyError::BadContentLength)
        );
        let error = block_on(Json::<serde_json::Value>::from_request_with_cx(
            &cx, json_req,
        ))
        .expect_err("truncated fixed JSON must fail");
        assert_eq!(
            error.status,
            super::super::response::StatusCode::BAD_REQUEST
        );
        assert_eq!(error.message, "invalid JSON request body");
        drop(json_control);

        let (mut form_writer, form_req, form_control) = streaming_extractor_request(
            &cx,
            BodyKind::Chunked,
            "application/x-www-form-urlencoded",
            32,
        );
        assert_eq!(
            block_on(form_writer.push_bytes(&cx, b"Z\r\n")),
            Err(IncomingBodyError::BadChunkedEncoding)
        );
        let error = block_on(Form::<HashMap<String, String>>::from_request_with_cx(
            &cx, form_req,
        ))
        .expect_err("malformed chunked form must fail");
        assert_eq!(
            error.status,
            super::super::response::StatusCode::BAD_REQUEST
        );
        assert_eq!(error.message, "invalid form request body");
        drop(form_control);

        let cancelled_cx = Cx::for_testing();
        let (mut json_writer, json_req, json_control) = streaming_extractor_request(
            &cancelled_cx,
            BodyKind::ContentLength(1),
            "application/json",
            1,
        );
        let mut extraction = std::pin::pin!(Json::<serde_json::Value>::from_request_with_cx(
            &cancelled_cx,
            json_req,
        ));
        let waker = std::task::Waker::noop().clone();
        let mut task_cx = Context::from_waker(&waker);
        assert!(matches!(
            std::future::Future::poll(extraction.as_mut(), &mut task_cx),
            Poll::Pending
        ));
        cancelled_cx.cancel_fast(crate::types::CancelKind::Deadline);
        let Poll::Ready(Err(error)) = std::future::Future::poll(extraction.as_mut(), &mut task_cx)
        else {
            panic!("cancelled streaming JSON extraction must terminate");
        };
        assert_eq!(
            error.status,
            super::super::response::StatusCode::SERVICE_UNAVAILABLE
        );
        assert_eq!(error.message, "JSON request body unavailable");
        drop(extraction);
        drop(json_control);
        assert_eq!(
            block_on(json_writer.push_bytes(&cancelled_cx, b"x")),
            Err(IncomingBodyError::Cancelled {
                kind: crate::types::CancelKind::Deadline,
            })
        );
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn streaming_json_and_form_typed_error_mapping_matches_body_contract() {
        use super::super::response::StatusCode;

        for kind in [
            CancelKind::Timeout,
            CancelKind::Deadline,
            CancelKind::PollQuota,
            CancelKind::CostBudget,
            CancelKind::ResourceUnavailable,
        ] {
            let error = streaming_extraction_error(
                "JSON",
                StreamingRawBodyCollectError::Body(IncomingBodyError::Cancelled { kind }),
            );
            assert_eq!(error.status, StatusCode::SERVICE_UNAVAILABLE);
        }

        for kind in [
            CancelKind::User,
            CancelKind::FailFast,
            CancelKind::RaceLost,
            CancelKind::ParentCancelled,
            CancelKind::Shutdown,
            CancelKind::LinkedExit,
        ] {
            let error = streaming_extraction_error(
                "JSON",
                StreamingRawBodyCollectError::Body(IncomingBodyError::Cancelled { kind }),
            );
            assert_eq!(error.status, StatusCode::CLIENT_CLOSED_REQUEST);
        }

        for incoming in [
            IncomingBodyError::AccountingOverflow,
            IncomingBodyError::SourceDisconnected,
        ] {
            let error =
                streaming_extraction_error("form", StreamingRawBodyCollectError::Body(incoming));
            assert_eq!(error.status, StatusCode::INTERNAL_SERVER_ERROR);
        }
    }

    #[test]
    fn json_wrong_content_type() {
        #[derive(Debug, serde::Deserialize)]
        struct Input {
            #[allow(dead_code)]
            name: String,
        }

        let req = Request::new("POST", "/users")
            .with_header("content-type", "text/plain")
            .with_body(Bytes::from_static(b"{\"name\":\"alice\"}"));

        let result = Json::<Input>::from_request(req);
        assert!(result.is_err());
    }

    #[test]
    fn form_extraction() {
        let req = Request::new("POST", "/login")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(b"user=alice&pass=secret"));

        let Form(data) = Form::<HashMap<String, String>>::from_request(req).unwrap();
        assert_eq!(data.get("user").unwrap(), "alice");
        assert_eq!(data.get("pass").unwrap(), "secret");
    }

    #[test]
    fn raw_body_extraction() {
        let req = Request::new("POST", "/upload").with_body(Bytes::from_static(b"raw data"));

        let RawBody(body) = RawBody::from_request(req).unwrap();
        assert_eq!(body.as_ref(), b"raw data");
    }

    #[test]
    fn headers_extraction() {
        let req = Request::new("GET", "/").with_header("x-request-id", "abc123");

        let headers = HashMap::<String, String>::from_request_parts(&req).unwrap();
        assert_eq!(headers.get("x-request-id").unwrap(), "abc123");
    }

    #[test]
    fn request_header_lookup_is_case_insensitive() {
        let mut req = Request::new("GET", "/").with_header("X-Trace-Id", "trace-123");
        req.headers
            .insert("Authorization".to_string(), "Bearer token".to_string());

        assert_eq!(req.header("x-trace-id"), Some("trace-123"));
        assert_eq!(req.header("X-TRACE-ID"), Some("trace-123"));
        assert_eq!(req.header("authorization"), Some("Bearer token"));
        assert_eq!(req.header("AUTHORIZATION"), Some("Bearer token"));
        assert_eq!(req.header("missing"), None);
    }

    #[test]
    fn typed_header_content_type_extracts_case_insensitively() {
        let req = Request::new("POST", "/items")
            .with_header("Content-Type", "application/json; charset=utf-8");

        let Header(content_type) = Header::<ContentType>::from_request_parts(&req).unwrap();
        assert_eq!(content_type.as_str(), "application/json; charset=utf-8");
        assert_eq!(content_type.media_type(), "application/json");
    }

    #[test]
    fn typed_header_alias_extracts_authorization() {
        let req = Request::new("GET", "/admin").with_header("Authorization", "Bearer token-123");

        let TypedHeader(auth) = TypedHeader::<Authorization>::from_request_parts(&req).unwrap();
        assert_eq!(auth.scheme, "Bearer");
        assert_eq!(auth.credentials, "token-123");
        assert_eq!(auth.as_str(), "Bearer token-123");
    }

    #[test]
    fn shipped_typed_headers_cover_user_agent_and_accept() {
        let req = Request::new("GET", "/")
            .with_header("User-Agent", "asupersync-test/1")
            .with_header("Accept", "application/json, text/plain;q=0.8, */*;q=0.1");

        let Header(user_agent) = Header::<UserAgent>::from_request_parts(&req).unwrap();
        let Header(accept) = Header::<Accept>::from_request_parts(&req).unwrap();
        assert_eq!(user_agent.as_str(), "asupersync-test/1");
        assert_eq!(
            accept.as_str(),
            "application/json, text/plain;q=0.8, */*;q=0.1"
        );
    }

    #[test]
    fn missing_typed_header_rejects_with_asup_code() {
        let req = Request::new("GET", "/");

        let err = Header::<ContentType>::from_request_parts(&req).unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
        assert!(err.message.starts_with("[ASUP-E503]"));
        assert!(err.message.contains("content-type"));
        assert!(err.message.contains("missing header"));
    }

    #[test]
    fn malformed_typed_header_rejects_with_asup_code() {
        let bad_content_type =
            Request::new("POST", "/items").with_header("content-type", "application");
        let err = Header::<ContentType>::from_request_parts(&bad_content_type).unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
        assert!(err.message.starts_with("[ASUP-E503]"));
        assert!(err.message.contains("media range"));

        let bad_authorization =
            Request::new("GET", "/admin").with_header("authorization", "Bearer   ");
        let err = TypedHeader::<Authorization>::from_request_parts(&bad_authorization).unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
        assert!(err.message.starts_with("[ASUP-E503]"));
        assert!(err.message.contains("credentials"));
    }

    #[test]
    fn missing_path_params() {
        let req = Request::new("GET", "/");
        let result = Path::<String>::from_request_parts(&req);
        assert!(result.is_err());
    }

    #[test]
    fn percent_decode_preserves_invalid_sequences() {
        assert_eq!(percent_decode("a%2"), "a%2");
        assert_eq!(percent_decode("x%G1"), "x%G1");
        assert_eq!(percent_decode("x%1G"), "x%1G");
        assert_eq!(percent_decode("%"), "%");
        assert_eq!(percent_decode("%A"), "%A");
        assert_eq!(percent_decode("%%41"), "%A"); // first % invalid, then valid %41
    }

    #[test]
    fn request_debug_clone() {
        let r = Request::new("GET", "/api/v1");
        let dbg = format!("{r:?}");
        assert!(dbg.contains("Request"));
        assert!(dbg.contains("GET"));

        let r2 = r;
        assert_eq!(r2.method, "GET");
        assert_eq!(r2.path, "/api/v1");
    }

    #[test]
    fn extensions_debug_clone_default() {
        let e = Extensions::default();
        let dbg = format!("{e:?}");
        assert!(dbg.contains("Extensions"));

        let e2 = e;
        assert!(e2.get("missing").is_none());
    }

    #[test]
    fn extraction_error_debug_clone() {
        let e = ExtractionError::bad_request("missing field");
        let dbg = format!("{e:?}");
        assert!(dbg.contains("ExtractionError"));
        assert!(dbg.contains("missing field"));

        let e2 = e;
        assert_eq!(e2.message, "missing field");
    }

    #[test]
    fn typed_state_extraction() {
        #[derive(Clone, Debug, PartialEq, Eq)]
        struct AppState {
            name: String,
        }

        let mut req = Request::new("GET", "/");
        req.extensions.insert_typed(AppState {
            name: "alpha".to_string(),
        });

        let State(state) = State::<AppState>::from_request_parts(&req).unwrap();
        assert_eq!(
            state,
            AppState {
                name: "alpha".to_string()
            }
        );
    }

    #[test]
    fn typed_state_missing_returns_error() {
        #[derive(Clone, Debug)]
        struct AppState;

        let req = Request::new("GET", "/");
        let err = State::<AppState>::from_request_parts(&req).unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::INTERNAL_SERVER_ERROR
        );
        assert!(err.message.contains("state not configured"));
    }

    #[test]
    fn form_body_too_large() {
        let oversized = vec![b'a'; DEFAULT_MAX_FORM_BODY_SIZE + 1];
        let req = Request::new("POST", "/form").with_body(Bytes::from(oversized));
        let result = Form::<HashMap<String, String>>::from_request(req);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::PAYLOAD_TOO_LARGE
        );
    }

    #[test]
    fn json_body_too_large() {
        let oversized = vec![b'a'; DEFAULT_MAX_JSON_BODY_SIZE + 1];
        let req = Request::new("POST", "/data")
            .with_header("content-type", "application/json")
            .with_body(Bytes::from(oversized));
        let result = Json::<serde_json::Value>::from_request(req);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::PAYLOAD_TOO_LARGE
        );
    }

    #[test]
    fn json_content_type_header_name_case_insensitive() {
        let req = Request::new("POST", "/data")
            .with_header("Content-Type", "application/json")
            .with_body(Bytes::from_static(br#"{"ok":true}"#));
        let Json(value) = Json::<serde_json::Value>::from_request(req).unwrap();
        assert_eq!(value.get("ok"), Some(&serde_json::Value::Bool(true)));
    }

    #[test]
    fn json_content_type_allows_parameters_but_rejects_substring_tricks() {
        let with_charset = Request::new("POST", "/data")
            .with_header("content-type", "application/json; charset=utf-8")
            .with_body(Bytes::from_static(br#"{"ok":true}"#));
        let Json(value) = Json::<serde_json::Value>::from_request(with_charset).unwrap();
        assert_eq!(value.get("ok"), Some(&serde_json::Value::Bool(true)));

        let structured_suffix = Request::new("POST", "/data")
            .with_header("content-type", "application/cloudevents+json")
            .with_body(Bytes::from_static(br#"{"ok":true}"#));
        let Json(value) = Json::<serde_json::Value>::from_request(structured_suffix).unwrap();
        assert_eq!(value.get("ok"), Some(&serde_json::Value::Bool(true)));

        let misleading = Request::new("POST", "/data")
            .with_header("content-type", "text/plain; note=application/json")
            .with_body(Bytes::from_static(br#"{"ok":true}"#));
        let err = Json::<serde_json::Value>::from_request(misleading).unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::UNSUPPORTED_MEDIA_TYPE
        );

        let wrong_top_level = Request::new("POST", "/data")
            .with_header("content-type", "text/cloudevents+json")
            .with_body(Bytes::from_static(br#"{"ok":true}"#));
        let err = Json::<serde_json::Value>::from_request(wrong_top_level).unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::UNSUPPORTED_MEDIA_TYPE
        );

        let empty_structured_prefix = Request::new("POST", "/data")
            .with_header("content-type", "application/+json")
            .with_body(Bytes::from_static(br#"{"ok":true}"#));
        let err = Json::<serde_json::Value>::from_request(empty_structured_prefix).unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::UNSUPPORTED_MEDIA_TYPE
        );
    }

    #[test]
    fn json_missing_content_type_rejects_with_415() {
        let req = Request::new("POST", "/data").with_body(Bytes::from_static(br#"{"ok":true}"#));
        let err = Json::<serde_json::Value>::from_request(req).unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::UNSUPPORTED_MEDIA_TYPE
        );
        assert_eq!(err.message, "Json requires Content-Type: application/json");
    }

    #[test]
    fn json_top_level_scalar_matches_rfc7159() {
        let req = Request::new("POST", "/data")
            .with_header("content-type", "application/json")
            .with_body(Bytes::from_static(b"123"));
        let Json(value) = Json::<serde_json::Value>::from_request(req).unwrap();
        assert_eq!(value, serde_json::Value::Number(123.into()));
    }

    #[test]
    fn json_surrounded_by_rfc8259_whitespace_parses() {
        let req = Request::new("POST", "/data")
            .with_header("content-type", "application/json")
            .with_body(Bytes::from_static(b"\r\n\t {\"ok\":true} \n"));
        let Json(value) = Json::<serde_json::Value>::from_request(req).unwrap();
        assert_eq!(value.get("ok"), Some(&serde_json::Value::Bool(true)));
    }

    #[test]
    fn metamorphic_body_extractors_preserve_body_semantics_and_limits() {
        let json_body = Bytes::from_static(br#"{"user":"alice","admin":true}"#);
        let json_req = Request::new("POST", "/json")
            .with_header("content-type", "application/json")
            .with_body(json_body.clone());
        let RawBody(raw_json) = RawBody::from_request(json_req.clone()).unwrap();
        assert_eq!(raw_json.as_ref(), json_body.as_ref());
        let Json(parsed_json) = Json::<serde_json::Value>::from_request(json_req).unwrap();
        assert_eq!(
            parsed_json,
            serde_json::from_slice::<serde_json::Value>(raw_json.as_ref()).unwrap()
        );

        let form_body = Bytes::from_static(b"user=alice&admin=boss");
        let form_req = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(form_body.clone());
        let RawBody(raw_form) = RawBody::from_request(form_req.clone()).unwrap();
        assert_eq!(raw_form.as_ref(), form_body.as_ref());
        let Form(parsed_form) = Form::<HashMap<String, String>>::from_request(form_req).unwrap();
        assert_eq!(
            parsed_form,
            parse_urlencoded(
                std::str::from_utf8(raw_form.as_ref()).unwrap(),
                "form field"
            )
            .unwrap()
        );

        let limit = 8;
        let limits = BodyLimits::new()
            .max_json_body_size(limit)
            .max_form_body_size(limit)
            .max_raw_body_size(limit);

        let mut oversized_json_req = Request::new("POST", "/json")
            .with_header("content-type", "application/json")
            .with_body(Bytes::from_static(br#"{"k":"123456789"}"#));
        oversized_json_req.extensions.insert_typed(limits);
        let json_err = Json::<serde_json::Value>::from_request(oversized_json_req).unwrap_err();
        assert_eq!(
            json_err.status,
            crate::web::response::StatusCode::PAYLOAD_TOO_LARGE
        );

        let mut oversized_form_req = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(b"k=123456789"));
        oversized_form_req.extensions.insert_typed(limits);
        let form_err =
            Form::<HashMap<String, String>>::from_request(oversized_form_req).unwrap_err();
        assert_eq!(
            form_err.status,
            crate::web::response::StatusCode::PAYLOAD_TOO_LARGE
        );

        let mut oversized_raw_req =
            Request::new("POST", "/raw").with_body(Bytes::from_static(b"123456789"));
        oversized_raw_req.extensions.insert_typed(limits);
        let raw_err = RawBody::from_request(oversized_raw_req).unwrap_err();
        assert_eq!(
            raw_err.status,
            crate::web::response::StatusCode::PAYLOAD_TOO_LARGE
        );
    }

    #[test]
    fn form_wrong_content_type() {
        let req = Request::new("POST", "/form")
            .with_header("content-type", "text/plain")
            .with_body(Bytes::from_static(b"user=alice"));
        let result = Form::<HashMap<String, String>>::from_request(req);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::UNSUPPORTED_MEDIA_TYPE
        );
    }

    #[test]
    fn form_content_type_header_name_case_insensitive() {
        let req = Request::new("POST", "/form")
            .with_header("Content-Type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(b"user=alice&role=admin"));
        let Form(values) = Form::<HashMap<String, String>>::from_request(req).unwrap();
        assert_eq!(values.get("user").map(String::as_str), Some("alice"));
        assert_eq!(values.get("role").map(String::as_str), Some("admin"));
    }

    #[test]
    fn form_content_type_allows_parameters_but_rejects_substring_tricks() {
        let with_charset = Request::new("POST", "/form")
            .with_header(
                "content-type",
                "application/x-www-form-urlencoded; charset=utf-8",
            )
            .with_body(Bytes::from_static(b"user=alice&role=admin"));
        let Form(values) = Form::<HashMap<String, String>>::from_request(with_charset).unwrap();
        assert_eq!(values.get("user").map(String::as_str), Some("alice"));
        assert_eq!(values.get("role").map(String::as_str), Some("admin"));

        let misleading = Request::new("POST", "/form")
            .with_header(
                "content-type",
                "application/x-www-form-urlencoded-bogus; charset=utf-8",
            )
            .with_body(Bytes::from_static(b"user=alice"));
        let err = Form::<HashMap<String, String>>::from_request(misleading).unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::UNSUPPORTED_MEDIA_TYPE
        );
    }

    #[test]
    fn form_missing_content_type_rejects_with_415() {
        // br-asupersync-mxqraw: Form requires Content-Type:
        // application/x-www-form-urlencoded. Missing Content-Type is a
        // 415 — default-deny prevents an attacker from forging Form<T>
        // deserialisation by submitting a foreign-format body (JSON, XML,
        // raw bytes) without declaring its media type.
        let req = Request::new("POST", "/form").with_body(Bytes::from_static(b"user=alice"));
        let err = Form::<HashMap<String, String>>::from_request(req).unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::UNSUPPORTED_MEDIA_TYPE
        );
    }

    #[test]
    fn form_invalid_utf8() {
        let req = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(b"\xff\xfe"));
        let result = Form::<HashMap<String, String>>::from_request(req);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
    }

    #[test]
    fn form_duplicate_keys_preserved_as_vec() {
        use serde::Deserialize;

        #[derive(Deserialize, Debug, PartialEq)]
        struct MultiForm {
            role: Vec<String>,
            name: String,
        }

        let req = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(b"role=user&role=admin&name=alice"));

        let Form(data) = Form::<MultiForm>::from_request(req).unwrap();
        assert_eq!(data.role, vec!["user", "admin"]);
        assert_eq!(data.name, "alice");
    }

    #[test]
    fn form_duplicate_keys_html_spec_compliance_audit() {
        println!("=== FORM DUPLICATE KEYS HTML SPEC COMPLIANCE AUDIT ===");

        use serde::Deserialize;

        // Test Case 1: Multiple values for same key should be preserved as Vec
        #[derive(Deserialize, Debug, PartialEq)]
        struct TestForm {
            tags: Vec<String>,
            category: String,
            flags: Option<Vec<String>>,
        }

        println!("✓ Test Case 1: Multiple values preserved as Vec<String>");

        let req1 = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(
                b"tags=red&tags=blue&tags=green&category=test",
            ));

        let Form(data1) = Form::<TestForm>::from_request(req1).unwrap();
        assert_eq!(data1.tags, vec!["red", "blue", "green"]);
        assert_eq!(data1.category, "test");
        assert_eq!(data1.flags, None);

        println!("  ✅ tags=red&tags=blue&tags=green → Vec![\"red\", \"blue\", \"green\"]");

        // Test Case 2: Single values should work normally
        println!("✓ Test Case 2: Single values work normally");

        let req2 = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(b"tags=solo&category=single"));

        let Form(data2) = Form::<TestForm>::from_request(req2).unwrap();
        assert_eq!(data2.tags, vec!["solo"]);
        assert_eq!(data2.category, "single");

        println!("  ✅ tags=solo → Vec![\"solo\"] (single item as Vec)");

        // Test Case 3: Mixed single and multiple values
        println!("✓ Test Case 3: Mixed single and multiple values");

        let req3 = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(
                b"tags=first&category=mixed&tags=second&flags=a&flags=b",
            ));

        let Form(data3) = Form::<TestForm>::from_request(req3).unwrap();
        assert_eq!(data3.tags, vec!["first", "second"]);
        assert_eq!(data3.category, "mixed");
        assert_eq!(data3.flags, Some(vec!["a".to_string(), "b".to_string()]));

        println!("  ✅ Mixed form: single category + multiple tags + multiple flags");

        // Test Case 4: HTML checkbox scenario (common use case)
        #[derive(Deserialize, Debug)]
        struct CheckboxForm {
            #[serde(default)]
            permissions: Vec<String>,
            username: String,
        }

        println!("✓ Test Case 4: HTML checkbox scenario");

        let req4 = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(
                b"permissions=read&permissions=write&permissions=delete&username=admin",
            ));

        let Form(data4) = Form::<CheckboxForm>::from_request(req4).unwrap();
        assert_eq!(data4.permissions, vec!["read", "write", "delete"]);
        assert_eq!(data4.username, "admin");

        println!("  ✅ Checkbox form: permissions=[read, write, delete]");

        // Test Case 5: Type coercion with duplicates
        #[derive(Deserialize, Debug)]
        struct TypedForm {
            numbers: Vec<i32>,
            enabled: bool,
        }

        println!("✓ Test Case 5: Type coercion with duplicates");

        let req5 = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(
                b"numbers=42&numbers=123&numbers=999&enabled=true",
            ));

        let Form(data5) = Form::<TypedForm>::from_request(req5).unwrap();
        assert_eq!(data5.numbers, vec![42, 123, 999]);
        assert_eq!(data5.enabled, true);

        println!("  ✅ Type coercion: string numbers → Vec<i32>");

        println!("\n📋 HTML FORM SPEC COMPLIANCE VERIFIED:");
        println!("  1. Duplicate keys preserved: ✅ OPTION (a) - Vec<String> (CORRECT)");
        println!("  2. Single values supported: ✅ BACKWARD COMPATIBLE");
        println!("  3. Type coercion works: ✅ STRING → NUMBER/BOOL");
        println!("  4. HTML checkboxes: ✅ MULTIPLE SELECTIONS PRESERVED");
        println!("  5. Mixed forms: ✅ SINGLE + MULTIPLE FIELDS");

        println!("\n✅ STATUS: FORM DUPLICATE KEY HANDLING IS COMPLIANT");
        println!("BEHAVIOR: Option (a) - return Vec<String> for duplicate keys (CORRECT)");
        println!("COMPLIANCE: HTML Form Specification - preserves all submitted values");
        println!("IMPACT: Applications can now handle multi-select forms correctly");
    }

    #[test]
    fn form_scalar_extraction_does_not_ignore_field_names() {
        let req = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_body(Bytes::from_static(b"flag=true"));
        let err = Form::<bool>::from_request(req).unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
        assert!(err.message.contains("invalid form data"));
    }

    #[test]
    fn json_invalid_body() {
        let req = Request::new("POST", "/data")
            .with_header("content-type", "application/json")
            .with_body(Bytes::from_static(b"not json"));
        let result = Json::<serde_json::Value>::from_request(req);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(
            err.status,
            crate::web::response::StatusCode::UNPROCESSABLE_ENTITY
        );
    }

    #[test]
    fn query_empty_string() {
        let req = Request::new("GET", "/items");
        let Query(params) = Query::<HashMap<String, String>>::from_request_parts(&req).unwrap();
        assert!(params.is_empty());
    }

    #[test]
    fn query_percent_encoded_values() {
        let req = Request::new("GET", "/search").with_query("q=hello+world&tag=%23rust");
        let Query(params) = Query::<HashMap<String, String>>::from_request_parts(&req).unwrap();
        assert_eq!(params.get("q").unwrap(), "hello world");
        assert_eq!(params.get("tag").unwrap(), "#rust");
    }

    #[test]
    fn query_typed_struct_extraction() {
        #[derive(Debug, serde::Deserialize, PartialEq, Eq)]
        struct Pagination {
            page: u32,
            per_page: u16,
            active: bool,
        }

        let req = Request::new("GET", "/items").with_query("page=3&per_page=25&active=true");
        let Query(pagination) = Query::<Pagination>::from_request_parts(&req).unwrap();
        assert_eq!(
            pagination,
            Pagination {
                page: 3,
                per_page: 25,
                active: true
            }
        );
    }

    #[test]
    fn query_typed_scalar_extraction() {
        let req = Request::new("GET", "/items").with_query("value=17");
        let Query(value) = Query::<u32>::from_request_parts(&req).unwrap();
        assert_eq!(value, 17);
    }

    #[test]
    fn query_typed_deserialization_error() {
        let req = Request::new("GET", "/items").with_query("page=abc");
        let err = Query::<u32>::from_request_parts(&req).unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
        assert!(err.message.contains("invalid query parameters"));
    }

    #[test]
    fn query_duplicate_keys_reject_instead_of_collapsing_to_scalar() {
        let req = Request::new("GET", "/items").with_query("value=17&value=18");
        let err = Query::<u32>::from_request_parts(&req).unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
        assert_eq!(
            err.message,
            "duplicate query parameter `value` (use multi-value extractor for forms)"
        );
    }

    #[test]
    fn path_multiple_params() {
        let mut params = HashMap::new();
        params.insert("user_id".to_string(), "42".to_string());
        params.insert("post_id".to_string(), "7".to_string());
        let req = Request::new("GET", "/users/42/posts/7").with_path_params(params.clone());

        let Path(extracted) = Path::<HashMap<String, String>>::from_request_parts(&req).unwrap();
        assert_eq!(extracted, params);
    }

    #[test]
    fn query_string_field_accepts_numeric_looking_value() {
        // A `String` field holding a numeric/bool-looking value (all-digit
        // username, numeric id passed as text, "true"/"false" string) must be
        // kept as a string, not coerced to a JSON number/bool and rejected.
        #[derive(Debug, serde::Deserialize, PartialEq, Eq)]
        struct Mixed {
            name: String,
            flag: String,
            age: u32,
        }
        let req = Request::new("GET", "/u").with_query("name=42&flag=true&age=30");
        let Query(m) = Query::<Mixed>::from_request_parts(&req).unwrap();
        assert_eq!(
            m,
            Mixed {
                name: "42".to_string(),
                flag: "true".to_string(),
                age: 30,
            }
        );
    }

    #[test]
    fn path_string_field_accepts_numeric_looking_value() {
        #[derive(Debug, serde::Deserialize, PartialEq, Eq)]
        struct Params {
            token: String,
            id: u64,
        }
        let mut params = HashMap::new();
        params.insert("token".to_string(), "1234".to_string());
        params.insert("id".to_string(), "9".to_string());
        let req = Request::new("GET", "/x").with_path_params(params);
        let Path(p) = Path::<Params>::from_request_parts(&req).unwrap();
        assert_eq!(
            p,
            Params {
                token: "1234".to_string(),
                id: 9,
            }
        );
    }

    #[test]
    fn raw_body_empty() {
        let req = Request::new("POST", "/upload");
        let RawBody(body) = RawBody::from_request(req).unwrap();
        assert!(body.is_empty());
    }

    #[test]
    fn cookie_extraction_raw_header() {
        let req = Request::new("GET", "/").with_header("Cookie", "session=abc; theme=dark");
        let Cookie(raw) = Cookie::from_request_parts(&req).unwrap();
        assert_eq!(raw, "session=abc; theme=dark");
    }

    #[test]
    fn cookie_extraction_missing_header_is_error() {
        let req = Request::new("GET", "/");
        let err = Cookie::from_request_parts(&req).unwrap_err();
        assert_eq!(err.status, crate::web::response::StatusCode::BAD_REQUEST);
    }

    #[test]
    fn cookie_jar_parses_cookie_pairs() {
        let req = Request::new("GET", "/").with_header("cookie", "session=abc; theme=dark; id=42");
        let jar = CookieJar::from_request_parts(&req).unwrap();
        assert_eq!(jar.get("session"), Some("abc"));
        assert_eq!(jar.get("theme"), Some("dark"));
        assert_eq!(jar.get("id"), Some("42"));
        assert_eq!(jar.len(), 3);
    }

    #[test]
    fn cookie_jar_last_duplicate_wins() {
        let req = Request::new("GET", "/").with_header("cookie", "mode=old; mode=new");
        let jar = CookieJar::from_request_parts(&req).unwrap();
        assert_eq!(jar.get("mode"), Some("new"));
    }

    #[test]
    fn cookie_jar_ignores_malformed_segments() {
        let req = Request::new("GET", "/").with_header(
            "cookie",
            "good=1; malformed; =missing_name; spaced = ok ; quoted=\"v\"",
        );
        let jar = CookieJar::from_request_parts(&req).unwrap();
        assert_eq!(jar.get("good"), Some("1"));
        assert_eq!(jar.get("spaced"), Some("ok"));
        assert_eq!(jar.get("quoted"), Some("v"));
        assert!(!jar.contains("malformed"));
    }

    #[test]
    fn cookie_jar_missing_header_is_empty() {
        let req = Request::new("GET", "/");
        let jar = CookieJar::from_request_parts(&req).unwrap();
        assert!(jar.is_empty());
    }

    #[test]
    fn extraction_error_into_response() {
        use crate::web::response::IntoResponse;
        let err = ExtractionError::bad_request("missing field");
        let resp = err.into_response();
        assert_eq!(resp.status, crate::web::response::StatusCode::BAD_REQUEST);
        assert_eq!(
            resp.headers.get("content-type").map(String::as_str),
            Some("text/plain; charset=utf-8")
        );
    }

    #[test]
    fn extensions_extend_preserves_string_and_typed_values() {
        #[derive(Clone, Debug, PartialEq, Eq)]
        struct AppState {
            id: u32,
        }

        let mut base = Extensions::new();
        base.insert("trace_id", "abc");
        base.insert_typed(AppState { id: 7 });

        let mut req_extensions = Extensions::new();
        req_extensions.insert("request_id", "r-1");
        req_extensions.extend_from(&base);

        assert_eq!(req_extensions.get("trace_id"), Some("abc"));
        assert_eq!(req_extensions.get("request_id"), Some("r-1"));
        assert_eq!(
            req_extensions.get_typed_cloned::<AppState>(),
            Some(AppState { id: 7 })
        );
    }

    #[test]
    fn extensions_hold_multiple_typed_values_and_override_same_type() {
        #[derive(Clone, Debug, PartialEq, Eq)]
        struct AppState {
            id: u32,
        }

        #[derive(Clone, Debug, PartialEq, Eq)]
        struct FeatureFlags {
            experimental: bool,
        }

        let mut extensions = Extensions::new();
        extensions.insert_typed(AppState { id: 1 });
        extensions.insert_typed(FeatureFlags { experimental: true });
        // Same TypeId should be replaced by the most recent insert.
        extensions.insert_typed(AppState { id: 2 });

        assert_eq!(
            extensions.get_typed_cloned::<AppState>(),
            Some(AppState { id: 2 })
        );
        assert_eq!(
            extensions.get_typed_cloned::<FeatureFlags>(),
            Some(FeatureFlags { experimental: true })
        );
    }

    // ── Scalar-guard regression tests ────────────────────────────────────

    #[test]
    fn path_scalar_with_multiple_params_falls_through_to_struct() {
        // Before the len()==1 guard, Path<u32> with 2+ params would
        // nondeterministically pick whichever value HashMap yielded first.
        #[derive(Debug, serde::Deserialize, PartialEq)]
        struct PostRef {
            user_id: u32,
            post_id: u32,
        }

        let mut params = HashMap::new();
        params.insert("user_id".to_string(), "42".to_string());
        params.insert("post_id".to_string(), "7".to_string());
        let req = Request::new("GET", "/users/42/posts/7").with_path_params(params);

        // Scalar extraction must NOT succeed — falls through to struct deser.
        assert!(Path::<u32>::from_request_parts(&req).is_err());

        // Struct extraction succeeds deterministically.
        let Path(post_ref) = Path::<PostRef>::from_request_parts(&req).unwrap();
        assert_eq!(
            post_ref,
            PostRef {
                user_id: 42,
                post_id: 7
            }
        );
    }

    #[test]
    fn query_scalar_with_multiple_params_falls_through_to_struct() {
        #[derive(Debug, serde::Deserialize, PartialEq)]
        struct Pagination {
            page: u32,
            per_page: u32,
        }

        let req = Request::new("GET", "/items").with_query("page=3&per_page=25");

        // Scalar extraction must NOT succeed with 2 query params.
        assert!(Query::<u32>::from_request_parts(&req).is_err());

        // Struct extraction works correctly.
        let Query(pg) = Query::<Pagination>::from_request_parts(&req).unwrap();
        assert_eq!(
            pg,
            Pagination {
                page: 3,
                per_page: 25
            }
        );
    }

    #[test]
    fn body_size_limit_checks_content_length_before_reading_body_dos_prevention() {
        // AUDIT TEST: Verify that Content-Length is checked BEFORE reading body
        // to prevent DoS attacks via memory exhaustion.
        // Per RFC 9110, should return 413 Payload Too Large based on Content-Length header.

        println!("=== WEB BODY SIZE LIMIT DoS PREVENTION AUDIT ===");

        // Test 1: JSON extractor checks Content-Length early
        let oversized_json_req = Request::new("POST", "/json")
            .with_header("content-type", "application/json")
            .with_header("content-length", "20971520") // 20MB declared
            .with_body(Bytes::from_static(b"{\"small\":\"body\"}")); // But small actual body

        let json_err = Json::<serde_json::Value>::from_request(oversized_json_req).unwrap_err();
        assert_eq!(
            json_err.status,
            crate::web::response::StatusCode::PAYLOAD_TOO_LARGE,
            "JSON extractor should reject based on Content-Length header before body processing"
        );
        assert!(
            json_err.message.contains("Content-Length"),
            "Error message should mention Content-Length header check, got: {}",
            json_err.message
        );

        // Test 2: Form extractor checks Content-Length early
        let oversized_form_req = Request::new("POST", "/form")
            .with_header("content-type", "application/x-www-form-urlencoded")
            .with_header("content-length", "5242880") // 5MB declared
            .with_body(Bytes::from_static(b"name=test")); // But small actual body

        let form_err =
            Form::<HashMap<String, String>>::from_request(oversized_form_req).unwrap_err();
        assert_eq!(
            form_err.status,
            crate::web::response::StatusCode::PAYLOAD_TOO_LARGE,
            "Form extractor should reject based on Content-Length header before body processing"
        );
        assert!(
            form_err.message.contains("Content-Length"),
            "Error message should mention Content-Length header check, got: {}",
            form_err.message
        );

        // Test 3: RawBody extractor checks Content-Length early
        let oversized_raw_req = Request::new("POST", "/upload")
            .with_header("content-length", "15728640") // 15MB declared
            .with_body(Bytes::from_static(b"small data")); // But small actual body

        let raw_err = RawBody::from_request(oversized_raw_req).unwrap_err();
        assert_eq!(
            raw_err.status,
            crate::web::response::StatusCode::PAYLOAD_TOO_LARGE,
            "RawBody extractor should reject based on Content-Length header before body processing"
        );
        assert!(
            raw_err.message.contains("Content-Length"),
            "Error message should mention Content-Length header check, got: {}",
            raw_err.message
        );

        // Test 4: Verify that requests within limit still work
        let valid_json_req = Request::new("POST", "/json")
            .with_header("content-type", "application/json")
            .with_header("content-length", "19") // Small declared size
            .with_body(Bytes::from_static(b"{\"valid\":\"request\"}"));

        let json_result = Json::<serde_json::Value>::from_request(valid_json_req);
        assert!(
            json_result.is_ok(),
            "Valid requests with Content-Length within limit should be processed"
        );

        println!("✅ AUDIT PASSED: Content-Length checked before body processing");
        println!("📋 DoS PROTECTION VERIFIED:");
        println!("  1. Content-Length header checked BEFORE body buffering: ✅");
        println!("  2. 413 Payload Too Large returned early: ✅");
        println!("  3. Memory exhaustion attack prevented: ✅");
        println!("  4. RFC 9110 compliance: ✅");
        println!("\n✅ STATUS: WEB BODY SIZE LIMITS ARE SECURE");
    }
}