armature_core/

http.rs

// HTTP request and response types

use crate::body::RequestBody;
use crate::extensions::Extensions;
use crate::headers::HeaderMap;
use crate::query::{QueryPairs, QueryView, parse as parse_query};
use crate::{ByteStr, Method};
use bytes::Bytes;
use serde::{Deserialize, Serialize};
use smallvec::SmallVec;
use std::collections::HashMap;
use std::sync::{Arc, OnceLock};

/// Route parameters captured from the request target.
///
/// Names are `&'static str` from the compiled route pattern (see
/// [`crate::param_intern`]), so the name half of a match is free. Values are
/// `Bytes` the matchers fill with `Bytes::copy_from_slice`, so a match costs one
/// small copy per captured value. Four inline slots covers the overwhelming
/// majority of routes.
pub type RouteParams = SmallVec<[(&'static str, Bytes); 4]>;

/// Read helpers for [`RouteParams`].
///
/// The type is a `SmallVec` of pairs rather than a map, so `get` on it means
/// "index into the slice". This is the by-name lookup.
pub trait RouteParamsExt {
    /// The value captured for `name`, as UTF-8.
    fn get_str(&self, name: &str) -> Option<&str>;

    /// The value captured for `name`, raw.
    fn get_bytes(&self, name: &str) -> Option<&Bytes>;
}

impl RouteParamsExt for RouteParams {
    #[inline]
    fn get_str(&self, name: &str) -> Option<&str> {
        self.get_bytes(name)
            .and_then(|v| std::str::from_utf8(v).ok())
    }

    #[inline]
    fn get_bytes(&self, name: &str) -> Option<&Bytes> {
        self.iter().find(|(k, _)| *k == name).map(|(_, v)| v)
    }
}

/// The memoized query pairs.
///
/// `OnceLock` rather than `OnceCell` because `HttpRequest` must stay `Sync`:
/// extractors hold `&HttpRequest` across an `await` inside a `Send` future, and
/// `&T: Send` requires `T: Sync`.
#[derive(Debug, Default)]
pub struct QueryCache(OnceLock<QueryPairs>);

impl Clone for QueryCache {
    /// A clone starts cold.
    ///
    /// Carrying the parsed pairs across a clone would be wrong, not merely
    /// wasteful: `path` is a public field, so a caller can clone a request and
    /// then change its target. A cold cache cannot answer for the wrong path.
    fn clone(&self) -> Self {
        Self(OnceLock::new())
    }
}

/// HTTP request wrapper
///
/// The path and body are `Bytes`-backed, so cloning a request is a handful of
/// refcount bumps rather than a deep copy of the target and payload.
#[derive(Debug, Clone)]
pub struct HttpRequest {
    /// The request method.
    ///
    /// Was a `String`. An unrecognized token is carried as `Method::Other`
    /// rather than rejected here; routing answers it with 404
    /// ([`crate::Error::RouteNotFound`]) since no route can match the token.
    pub method: Method,
    /// The raw request target, query string included.
    ///
    /// Was a `String`. A `ByteStr` so it can be a slice of the connection read
    /// buffer once the serve path moves onto `armature-h1`; `Deref<Target = str>`
    /// keeps `&req.path` working wherever a `&str` is wanted.
    pub path: ByteStr,
    /// Request headers stored in a SmallVec-backed `HeaderMap`.
    ///
    /// For typical requests (<12 headers) this is stored inline on the stack,
    /// avoiding the per-request HashMap heap allocation on the read path.
    /// The API is HashMap-compatible (`get`/`insert`/`iter`/`contains_key`/...),
    /// with case-insensitive header name lookup.
    pub headers: HeaderMap,
    /// The request body.
    ///
    /// Was a `Vec<u8>` shadowed by an optional `Bytes` that could disagree with
    /// it. One field, always authoritative.
    pub body: Bytes,
    pub path_params: RouteParams,
    /// Type-safe extensions for storing application state.
    ///
    /// Use this to pass typed data to handlers without DI container lookups.
    /// Access via the `State<T>` extractor for zero-cost state retrieval.
    pub extensions: Extensions,
    /// Parsed lazily by [`HttpRequest::query`].
    query_cache: QueryCache,
}

impl HttpRequest {
    /// Create a request.
    ///
    /// Generic in the method so every existing `HttpRequest::new("GET", …)`
    /// call site compiles unchanged.
    #[inline]
    pub fn new(method: impl Into<Method>, path: impl Into<ByteStr>) -> Self {
        Self {
            method: method.into(),
            path: path.into(),
            headers: HeaderMap::new(),
            body: Bytes::new(),
            path_params: RouteParams::new(),
            extensions: Extensions::new(),
            query_cache: QueryCache::default(),
        }
    }

    /// Create a new request with pre-allocated extensions capacity.
    #[inline]
    pub fn with_extensions_capacity(
        method: impl Into<Method>,
        path: impl Into<ByteStr>,
        capacity: usize,
    ) -> Self {
        Self {
            method: method.into(),
            path: path.into(),
            headers: HeaderMap::new(),
            body: Bytes::new(),
            path_params: RouteParams::new(),
            extensions: Extensions::with_capacity(capacity),
            query_cache: QueryCache::default(),
        }
    }

    /// Create a new request with a Bytes body (zero-copy).
    ///
    /// This is the most efficient way to create a request from Hyper's body,
    /// as it avoids copying the body data.
    #[inline]
    pub fn with_bytes_body(
        method: impl Into<Method>,
        path: impl Into<ByteStr>,
        body: Bytes,
    ) -> Self {
        Self {
            method: method.into(),
            path: path.into(),
            headers: HeaderMap::new(),
            body,
            path_params: RouteParams::new(),
            extensions: Extensions::new(),
            query_cache: QueryCache::default(),
        }
    }

    /// Set the body (zero-copy).
    #[inline]
    pub fn set_body_bytes(&mut self, bytes: Bytes) {
        self.body = bytes;
    }

    /// The body as `Bytes`. A refcount bump, not a copy.
    #[inline]
    pub fn body_bytes(&self) -> Bytes {
        self.body.clone()
    }

    /// The body as a byte slice.
    #[inline]
    pub fn body_slice(&self) -> &[u8] {
        &self.body
    }

    /// The body as a byte slice.
    #[inline]
    pub fn body_ref(&self) -> &[u8] {
        &self.body
    }

    /// The request target as a string, query string included.
    #[inline]
    pub fn path_str(&self) -> &str {
        self.path.as_str()
    }

    /// The request target with any query string removed.
    ///
    /// This is what routing matches on, and what most callers mean when they
    /// say "the path" — `path`/`path_str` are the raw target, which is what the
    /// query is parsed out of.
    #[inline]
    pub fn path_only(&self) -> &str {
        self.path
            .split_once('?')
            .map_or(self.path.as_str(), |(p, _)| p)
    }

    /// Get the body as a RequestBody (zero-copy wrapper).
    #[inline]
    pub fn request_body(&self) -> RequestBody {
        RequestBody::from_bytes(self.body_bytes())
    }

    /// Whether the body holds anything.
    ///
    /// Kept for call-site compatibility from when the body could live in either
    /// of two fields; it is always `Bytes` now.
    #[inline]
    pub fn has_bytes_body(&self) -> bool {
        !self.body.is_empty()
    }

    /// The method as a string, for logging and for code that compares tokens.
    #[inline]
    pub fn method_str(&self) -> &str {
        self.method.as_str()
    }

    /// Set the body from a `Vec<u8>`, taking over its allocation.
    #[inline]
    pub fn set_body(&mut self, body: Vec<u8>) {
        self.body = Bytes::from(body);
    }

    /// Create a request from all parts (for compatibility in tests).
    #[inline]
    pub fn from_parts(
        method: impl Into<Method>,
        path: impl Into<ByteStr>,
        headers: HashMap<String, String>,
        body: Vec<u8>,
        path_params: HashMap<String, String>,
        query_params: HashMap<String, String>,
    ) -> Self {
        // Names are interned rather than borrowed: `from_parts` is a
        // compatibility shim taking an owned map, so there is no route pattern
        // to borrow a `&'static str` from.
        let path_params: RouteParams = path_params
            .into_iter()
            .map(|(k, v)| (crate::param_intern::intern(&k), Bytes::from(v)))
            .collect();
        // `query_params` is accepted for source compatibility and ignored: the
        // query now comes from `path`, parsed on demand. Callers that need one
        // honoured should put it in the path.
        let _ = query_params;
        Self {
            method: method.into(),
            path: path.into(),
            headers: headers.into(),
            body: Bytes::from(body),
            path_params,
            extensions: Extensions::new(),
            query_cache: QueryCache::default(),
        }
    }

    /// Insert a typed value into request extensions.
    ///
    /// Use this to pass application state to handlers.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let mut request = HttpRequest::new("GET", "/");
    /// request.insert_extension(app_state);
    /// ```
    #[inline]
    pub fn insert_extension<T: Send + Sync + 'static>(&mut self, value: T) {
        self.extensions.insert(value);
    }

    /// Insert an Arc-wrapped value into request extensions.
    ///
    /// This is more efficient when you already have an Arc.
    #[inline]
    pub fn insert_extension_arc<T: Send + Sync + 'static>(&mut self, value: Arc<T>) {
        self.extensions.insert_arc(value);
    }

    /// Get a reference to a typed extension.
    ///
    /// Returns `None` if no value of this type exists.
    #[inline]
    pub fn extension<T: Send + Sync + 'static>(&self) -> Option<&T> {
        self.extensions.get::<T>()
    }

    /// Get an Arc reference to a typed extension.
    #[inline]
    pub fn extension_arc<T: Send + Sync + 'static>(&self) -> Option<Arc<T>> {
        self.extensions.get_arc::<T>()
    }

    /// Parse the request body as JSON.
    ///
    /// With the `simd-json` feature enabled, this uses SIMD-accelerated parsing
    /// which can be 2-3x faster on modern x86_64 CPUs.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let user: CreateUser = request.json()?;
    /// ```
    #[inline]
    pub fn json<T: for<'de> Deserialize<'de>>(&self) -> Result<T, crate::Error> {
        crate::json::from_slice(self.body_ref())
            .map_err(|e| crate::Error::Deserialization(e.to_string()))
    }

    /// Parse URL-encoded form data
    pub fn form<T: for<'de> Deserialize<'de>>(&self) -> Result<T, crate::Error> {
        crate::form::parse_form(self.body_ref())
    }

    /// Parse URL-encoded form data into a HashMap
    pub fn form_map(&self) -> Result<HashMap<String, String>, crate::Error> {
        crate::form::parse_form_map(self.body_ref())
    }

    /// Parse multipart form data
    pub fn multipart(&self) -> Result<Vec<crate::form::FormField>, crate::Error> {
        // One lookup: header names intern case-insensitively, so the
        // lowercased retry was always redundant.
        let content_type = self
            .headers
            .get("Content-Type")
            .ok_or_else(|| crate::Error::BadRequest("Missing Content-Type header".to_string()))?;

        let parser = crate::form::MultipartParser::from_content_type(content_type)?;
        parser.parse(self.body_ref())
    }

    /// A captured route parameter, as UTF-8.
    #[inline]
    pub fn param(&self, name: &str) -> Option<&str> {
        self.param_bytes(name)
            .and_then(|v| std::str::from_utf8(v).ok())
    }

    /// A captured route parameter, raw.
    #[inline]
    pub fn param_bytes(&self, name: &str) -> Option<&Bytes> {
        self.path_params
            .iter()
            .find(|(k, _)| *k == name)
            .map(|(_, v)| v)
    }

    /// Add one captured route parameter, interning its name.
    ///
    /// The router uses [`HttpRequest::set_params`] with names already interned
    /// at registration; this is for callers assembling a request by hand. The
    /// interner is hard-capped ([`crate::param_intern::MAX_INTERNED`]), so
    /// feeding this a request-derived name cannot grow the process without
    /// bound — past the cap the name resolves to
    /// [`crate::param_intern::OVERFLOW_NAME`] and the parameter is no longer
    /// retrievable by its own name.
    pub fn push_param(&mut self, name: &str, value: impl Into<Bytes>) {
        self.path_params
            .push((crate::param_intern::intern(name), value.into()));
    }

    /// Replace the captured parameters. Called by the router.
    #[inline]
    pub fn set_params(&mut self, params: RouteParams) {
        self.path_params = params;
    }

    /// The raw query string, without the `?`.
    #[inline]
    pub fn query_string(&self) -> Option<&str> {
        self.path.as_str().split_once('?').map(|(_, q)| q)
    }

    /// A parsed view of the query string.
    ///
    /// Parses on the first call and memoizes; a handler that never calls this
    /// pays nothing. Note the shape change: this used to take a name and return
    /// one value — that accessor is now [`HttpRequest::query_param`].
    #[inline]
    pub fn query(&self) -> QueryView<'_> {
        let pairs = self
            .query_cache
            .0
            .get_or_init(|| match self.query_string() {
                Some(q) => parse_query(q),
                None => QueryPairs::new(),
            });
        QueryView::new(pairs)
    }

    /// Append a query parameter to the target, percent-encoding both sides.
    ///
    /// The query lives in `path` now, so this is how a caller adds one without
    /// hand-assembling the target. Any memoized parse is discarded, since the
    /// target it was parsed from no longer describes this request.
    pub fn push_query_param(&mut self, name: impl AsRef<str>, value: impl AsRef<str>) {
        let pair = [(name.as_ref(), value.as_ref())];
        let Ok(encoded) = serde_urlencoded::to_string(pair) else {
            return;
        };
        let separator = if self.path.contains('?') { '&' } else { '?' };
        self.path = ByteStr::from(format!("{}{separator}{encoded}", self.path.as_str()));
        self.query_cache = QueryCache::default();
    }

    /// The first query value for `name`.
    #[inline]
    pub fn query_param(&self, name: &str) -> Option<&str> {
        self.query().get(name)
    }
}

/// Lazy-initialized HashMap that doesn't allocate until first insert.
///
/// This provides the same API as HashMap but with zero allocation cost
/// for empty maps.
#[derive(Debug, Clone, Default)]
pub struct LazyHeaders {
    inner: Option<HashMap<String, String>>,
}

impl LazyHeaders {
    /// Create a new empty LazyHeaders (no allocation).
    #[inline(always)]
    pub const fn new() -> Self {
        Self { inner: None }
    }

    /// Create with pre-allocated capacity.
    #[inline]
    pub fn with_capacity(cap: usize) -> Self {
        Self {
            inner: Some(HashMap::with_capacity(cap)),
        }
    }

    /// Insert a key-value pair.
    #[inline]
    pub fn insert(&mut self, key: String, value: String) -> Option<String> {
        self.inner
            .get_or_insert_with(HashMap::new)
            .insert(key, value)
    }

    /// Get a value by key.
    #[inline]
    pub fn get(&self, key: &str) -> Option<&String> {
        self.inner.as_ref()?.get(key)
    }

    /// Check if key exists.
    #[inline]
    pub fn contains_key(&self, key: &str) -> bool {
        self.inner.as_ref().is_some_and(|m| m.contains_key(key))
    }

    /// Get number of headers.
    #[inline]
    pub fn len(&self) -> usize {
        self.inner.as_ref().map_or(0, |m| m.len())
    }

    /// Check if empty.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.inner.as_ref().is_none_or(|m| m.is_empty())
    }

    /// Iterate over headers.
    #[inline]
    pub fn iter(&self) -> impl Iterator<Item = (&String, &String)> {
        self.inner.iter().flat_map(|m| m.iter())
    }

    /// Convert to HashMap (for compatibility).
    #[inline]
    pub fn to_hashmap(&self) -> HashMap<String, String> {
        self.inner.clone().unwrap_or_default()
    }

    /// Remove a header by key.
    #[inline]
    pub fn remove(&mut self, key: &str) -> Option<String> {
        self.inner.as_mut()?.remove(key)
    }

    /// Get an entry for in-place manipulation.
    #[inline]
    pub fn entry(&mut self, key: String) -> std::collections::hash_map::Entry<'_, String, String> {
        self.inner.get_or_insert_with(HashMap::new).entry(key)
    }

    /// Extend with headers from an iterator.
    #[inline]
    pub fn extend<I: IntoIterator<Item = (String, String)>>(&mut self, iter: I) {
        let map = self.inner.get_or_insert_with(HashMap::new);
        map.extend(iter);
    }

    /// Clear all headers.
    #[inline]
    pub fn clear(&mut self) {
        if let Some(ref mut map) = self.inner {
            map.clear();
        }
    }

    /// Clone the inner HashMap if present.
    #[inline]
    pub fn clone_inner(&self) -> Option<HashMap<String, String>> {
        self.inner.clone()
    }
}

impl From<HashMap<String, String>> for LazyHeaders {
    #[inline]
    fn from(map: HashMap<String, String>) -> Self {
        Self { inner: Some(map) }
    }
}

impl From<LazyHeaders> for HashMap<String, String> {
    #[inline]
    fn from(lazy: LazyHeaders) -> Self {
        lazy.inner.unwrap_or_default()
    }
}

// Allow iteration
impl<'a> IntoIterator for &'a LazyHeaders {
    type Item = (&'a String, &'a String);
    type IntoIter = std::iter::Flatten<std::option::Iter<'a, HashMap<String, String>>>;

    fn into_iter(self) -> Self::IntoIter {
        self.inner.iter().flatten()
    }
}

/// HTTP response wrapper
///
/// The body is `Bytes`, so handing a response to the writer — or cloning one out
/// of a cache — is a refcount bump rather than a copy. Build one from an
/// existing buffer with `with_bytes_body()`.
///
/// ## Performance Note
///
/// Response creation is optimized for minimal allocation:
/// - `headers` uses `LazyHeaders` which doesn't allocate until first insert
/// - `body` is an empty `Bytes` until set, which doesn't allocate
/// - Use `FastResponse` from `armature_core::fast_response` for even faster creation
#[derive(Debug)]
pub struct HttpResponse {
    pub status: u16,
    /// Response headers with lazy allocation.
    pub headers: LazyHeaders,
    /// Set-Cookie headers (supports multiple cookies per response).
    pub cookies: Vec<String>,
    /// The response body.
    ///
    /// Was a `Vec<u8>` shadowed by an optional `Bytes`. One field, always
    /// authoritative.
    pub body: Bytes,
}

/// Default pre-allocated response buffer size (512 bytes).
pub const DEFAULT_RESPONSE_CAPACITY: usize = 512;

impl HttpResponse {
    /// Create a new response with the given status code.
    ///
    /// This is optimized for minimal allocation - headers use `LazyHeaders`
    /// which doesn't allocate until first insert, and body uses `Vec::new()`
    /// which is zero-cost.
    #[inline(always)]
    pub fn new(status: u16) -> Self {
        Self {
            status,
            headers: LazyHeaders::new(),
            cookies: Vec::new(),
            body: Bytes::new(),
        }
    }

    /// Create a new response with pre-allocated header capacity.
    ///
    /// The `capacity` argument is retained for source compatibility but no
    /// longer reserves body space: `Bytes` is handed a finished buffer rather
    /// than grown in place.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let response = HttpResponse::with_capacity(200, 512);
    /// ```
    #[inline]
    pub fn with_capacity(status: u16, _capacity: usize) -> Self {
        Self {
            status,
            headers: LazyHeaders::with_capacity(8),
            cookies: Vec::new(),
            body: Bytes::new(),
        }
    }

    /// Create a 200 OK response.
    #[inline(always)]
    pub fn ok() -> Self {
        Self::new(200)
    }

    /// Create a 200 OK response with pre-allocated buffer (512 bytes default).
    #[inline]
    pub fn ok_preallocated() -> Self {
        Self::with_capacity(200, DEFAULT_RESPONSE_CAPACITY)
    }

    /// Create a 201 Created response.
    #[inline(always)]
    pub fn created() -> Self {
        Self::new(201)
    }

    /// Create a 204 No Content response.
    #[inline(always)]
    pub fn no_content() -> Self {
        Self::new(204)
    }

    /// Create a 400 Bad Request response.
    #[inline(always)]
    pub fn bad_request() -> Self {
        Self::new(400)
    }

    /// Create a 404 Not Found response.
    #[inline(always)]
    pub fn not_found() -> Self {
        Self::new(404)
    }

    /// Create a 500 Internal Server Error response.
    #[inline(always)]
    pub fn internal_server_error() -> Self {
        Self::new(500)
    }

    /// Set the body from a `Vec<u8>`, taking over its allocation.
    pub fn with_body(mut self, body: Vec<u8>) -> Self {
        self.body = Bytes::from(body);
        self
    }

    /// Set the body using Bytes (zero-copy).
    ///
    /// This is the most efficient way to set response body data,
    /// as it can be passed directly to Hyper without copying.
    #[inline]
    pub fn with_bytes_body(mut self, bytes: Bytes) -> Self {
        self.body = bytes;
        self
    }

    /// Set the body from a static byte slice (zero-copy).
    #[inline]
    pub fn with_static_body(mut self, body: &'static [u8]) -> Self {
        self.body = Bytes::from_static(body);
        self
    }

    /// The body as `Bytes`. A refcount bump, not a copy.
    #[inline]
    pub fn body_bytes(&self) -> Bytes {
        self.body.clone()
    }

    /// Consume the response and return the body.
    #[inline]
    pub fn into_body_bytes(self) -> Bytes {
        self.body
    }

    /// The body as a byte slice.
    #[inline]
    pub fn body_slice(&self) -> &[u8] {
        &self.body
    }

    /// The body as a byte slice.
    #[inline]
    pub fn body_ref(&self) -> &[u8] {
        &self.body
    }

    /// The body length in bytes.
    #[inline]
    pub fn body_len(&self) -> usize {
        self.body.len()
    }

    /// Whether the body holds anything.
    ///
    /// Kept for call-site compatibility from when the body could live in either
    /// of two fields; it is always `Bytes` now.
    #[inline]
    pub fn has_bytes_body(&self) -> bool {
        !self.body.is_empty()
    }

    /// Serialize a value as JSON and set it as the response body.
    ///
    /// With the `simd-json` feature enabled, this uses SIMD-accelerated serialization
    /// which can be 1.5-2x faster on modern x86_64 CPUs.
    ///
    /// The body is stored as `Bytes` for zero-copy passthrough to Hyper.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// HttpResponse::ok().with_json(&user)?
    /// ```
    #[inline]
    pub fn with_json<T: Serialize>(mut self, value: &T) -> Result<Self, crate::Error> {
        let vec =
            crate::json::to_vec(value).map_err(|e| crate::Error::Serialization(e.to_string()))?;
        self.body = Bytes::from(vec);
        self.headers
            .insert("Content-Type".to_string(), "application/json".to_string());
        Ok(self)
    }

    pub fn with_header(mut self, key: String, value: String) -> Self {
        self.headers.insert(key, value);
        self
    }

    /// Set multiple headers from a HashMap.
    #[inline]
    pub fn with_headers(mut self, headers: HashMap<String, String>) -> Self {
        self.headers = LazyHeaders::from(headers);
        self
    }

    /// Create a response with status and headers (for CORS preflight, etc.).
    #[inline]
    pub fn with_status_and_headers(status: u16, headers: HashMap<String, String>) -> Self {
        Self {
            status,
            headers: LazyHeaders::from(headers),
            cookies: Vec::new(),
            body: Bytes::new(),
        }
    }

    /// Create a response with all components (for compatibility).
    ///
    /// This is useful when you need to construct a response with all parts at once.
    #[inline]
    pub fn from_parts(status: u16, headers: HashMap<String, String>, body: Vec<u8>) -> Self {
        Self {
            status,
            headers: LazyHeaders::from(headers),
            cookies: Vec::new(),
            body: Bytes::from(body),
        }
    }

    // ============================================================================
    // Convenience Methods for Common Response Types
    // ============================================================================

    /// Create an accepted response (202).
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::accepted();
    /// assert_eq!(response.status, 202);
    /// ```
    pub fn accepted() -> Self {
        Self::new(202)
    }

    /// Create an unauthorized response (401).
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::unauthorized();
    /// assert_eq!(response.status, 401);
    /// ```
    pub fn unauthorized() -> Self {
        Self::new(401)
    }

    /// Create a forbidden response (403).
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::forbidden();
    /// assert_eq!(response.status, 403);
    /// ```
    pub fn forbidden() -> Self {
        Self::new(403)
    }

    /// Create a conflict response (409).
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::conflict();
    /// assert_eq!(response.status, 409);
    /// ```
    pub fn conflict() -> Self {
        Self::new(409)
    }

    /// Create a service unavailable response (503).
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::service_unavailable();
    /// assert_eq!(response.status, 503);
    /// ```
    pub fn service_unavailable() -> Self {
        Self::new(503)
    }

    /// Shorthand for creating a JSON response with 200 OK status.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// use serde_json::json;
    ///
    /// let response = HttpResponse::json(&json!({"message": "Hello"})).unwrap();
    /// assert_eq!(response.status, 200);
    /// ```
    pub fn json<T: Serialize>(value: &T) -> Result<Self, crate::Error> {
        Self::ok().with_json(value)
    }

    /// Create an HTML response with 200 OK status.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::html("<h1>Hello</h1>");
    /// assert_eq!(response.status, 200);
    /// assert_eq!(response.headers.get("Content-Type"), Some(&"text/html; charset=utf-8".to_string()));
    /// ```
    pub fn html(content: impl Into<String>) -> Self {
        Self::ok()
            .with_header(
                "Content-Type".to_string(),
                "text/html; charset=utf-8".to_string(),
            )
            .with_body(content.into().into_bytes())
    }

    /// Create a plain text response with 200 OK status.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::text("Hello, World!");
    /// assert_eq!(response.status, 200);
    /// assert_eq!(response.headers.get("Content-Type"), Some(&"text/plain; charset=utf-8".to_string()));
    /// ```
    pub fn text(content: impl Into<String>) -> Self {
        Self::ok()
            .with_header(
                "Content-Type".to_string(),
                "text/plain; charset=utf-8".to_string(),
            )
            .with_body(content.into().into_bytes())
    }

    /// Create a redirect response (302 Found).
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::redirect("https://example.com");
    /// assert_eq!(response.status, 302);
    /// assert_eq!(response.headers.get("Location"), Some(&"https://example.com".to_string()));
    /// ```
    pub fn redirect(url: impl Into<String>) -> Self {
        Self::new(302).with_header("Location".to_string(), url.into())
    }

    /// Create a permanent redirect response (301 Moved Permanently).
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::redirect_permanent("https://example.com");
    /// assert_eq!(response.status, 301);
    /// ```
    pub fn redirect_permanent(url: impl Into<String>) -> Self {
        Self::new(301).with_header("Location".to_string(), url.into())
    }

    /// Create a see other redirect response (303 See Other).
    /// Useful after a POST request to redirect to a GET.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::see_other("/success");
    /// assert_eq!(response.status, 303);
    /// ```
    pub fn see_other(url: impl Into<String>) -> Self {
        Self::new(303).with_header("Location".to_string(), url.into())
    }

    /// Alias for no_content() - returns 204 with empty body.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::empty();
    /// assert_eq!(response.status, 204);
    /// ```
    pub fn empty() -> Self {
        Self::no_content()
    }

    /// Set the Content-Type header.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::ok().content_type("application/xml");
    /// assert_eq!(response.headers.get("Content-Type"), Some(&"application/xml".to_string()));
    /// ```
    pub fn content_type(self, content_type: impl Into<String>) -> Self {
        self.with_header("Content-Type".to_string(), content_type.into())
    }

    /// Set the Cache-Control header.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::ok().cache_control("max-age=3600");
    /// ```
    pub fn cache_control(self, directive: impl Into<String>) -> Self {
        self.with_header("Cache-Control".to_string(), directive.into())
    }

    /// Mark the response as not cacheable.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::ok().no_cache();
    /// ```
    pub fn no_cache(self) -> Self {
        self.cache_control("no-store, no-cache, must-revalidate")
    }

    /// Set a cookie on the response. Can be called multiple times to set
    /// multiple cookies — each produces a separate `Set-Cookie` header.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::ok()
    ///     .cookie("session", "abc123; HttpOnly; Secure")
    ///     .cookie("theme", "dark; Path=/");
    /// ```
    pub fn cookie(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.cookies
            .push(format!("{}={}", name.into(), value.into()));
        self
    }

    /// Clear a cookie by setting it with an expired Max-Age.
    ///
    /// # Example
    /// ```
    /// use armature_core::HttpResponse;
    /// let response = HttpResponse::ok().clear_cookie("session", "/");
    /// ```
    pub fn clear_cookie(mut self, name: impl Into<String>, path: impl Into<String>) -> Self {
        self.cookies
            .push(format!("{}=; Path={}; Max-Age=0", name.into(), path.into(),));
        self
    }

    /// Get the response body as a string (lossy UTF-8 conversion).
    pub fn body_string(&self) -> String {
        String::from_utf8_lossy(self.body_ref()).to_string()
    }

    /// Check if the response is successful (2xx status code).
    pub fn is_success(&self) -> bool {
        (200..300).contains(&self.status)
    }

    /// Check if the response is a redirect (3xx status code).
    pub fn is_redirect(&self) -> bool {
        (300..400).contains(&self.status)
    }

    /// Check if the response is a client error (4xx status code).
    pub fn is_client_error(&self) -> bool {
        (400..500).contains(&self.status)
    }

    /// Check if the response is a server error (5xx status code).
    pub fn is_server_error(&self) -> bool {
        (500..600).contains(&self.status)
    }
}

/// JSON response helper
#[derive(Debug)]
pub struct Json<T: Serialize>(pub T);

impl<T: Serialize> Json<T> {
    pub fn into_response(self) -> Result<HttpResponse, crate::Error> {
        HttpResponse::ok().with_json(&self.0)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn new_accepts_str_and_string_and_method() {
        // All three forms must compile: existing call sites pass a String, and
        // new code should be able to pass a Method directly.
        let a = HttpRequest::new("GET", "/a".to_string());
        let b = HttpRequest::new("POST", "/b".to_string());
        let c = HttpRequest::new(Method::Put, "/c".to_string());
        assert_eq!(a.method, Method::Get);
        assert_eq!(b.method, Method::Post);
        assert_eq!(c.method, Method::Put);
    }

    #[test]
    fn from_parts_ignores_query_params_entirely() {
        // The argument is kept for source compatibility only — the query comes
        // from the target now. Pinned so a caller still passing a map can't
        // silently depend on it being honoured.
        let mut query = HashMap::new();
        query.insert("page".to_string(), "2".to_string());

        let req = HttpRequest::from_parts(
            "GET",
            "/items",
            HashMap::new(),
            Vec::new(),
            HashMap::new(),
            query,
        );

        assert_eq!(req.query_string(), None);
        assert_eq!(req.query_param("page"), None);
        assert_eq!(req.query().len(), 0);
    }

    #[test]
    fn with_capacity_ignores_its_capacity_argument() {
        // `Bytes` is handed a finished buffer rather than grown in place, so
        // there is no body capacity to reserve. Any two capacities must produce
        // indistinguishable responses.
        let small = HttpResponse::with_capacity(200, 0);
        let large = HttpResponse::with_capacity(200, 1 << 20);

        assert_eq!(small.status, large.status);
        assert_eq!(small.body.len(), large.body.len());
        assert!(small.body.is_empty());
        assert_eq!(small.headers.len(), large.headers.len());
    }

    #[test]
    fn params_read_back_as_str_and_bytes() {
        let mut req = HttpRequest::new("GET", "/users/42/posts/7");
        let mut params = RouteParams::new();
        params.push((
            crate::param_intern::intern("user_id"),
            Bytes::from_static(b"42"),
        ));
        params.push((
            crate::param_intern::intern("post_id"),
            Bytes::from_static(b"7"),
        ));
        req.set_params(params);

        assert_eq!(req.param("user_id"), Some("42"));
        assert_eq!(req.param("post_id"), Some("7"));
        assert_eq!(req.param("nope"), None);
        assert_eq!(req.param_bytes("user_id").map(|b| b.len()), Some(2));
        assert_eq!(
            req.param("user_id").and_then(|v| v.parse::<u32>().ok()),
            Some(42)
        );
    }

    #[test]
    fn four_params_stay_inline() {
        let mut params = RouteParams::new();
        for name in ["a", "b", "c", "d"] {
            params.push((crate::param_intern::intern(name), Bytes::from_static(b"x")));
        }
        assert!(!params.spilled(), "four params must not allocate");
    }

    #[test]
    fn path_is_a_bytestr_and_still_compares_and_prints_as_a_str() {
        let req = HttpRequest::new("GET", "/users/42?a=1");
        assert_eq!(req.path_str(), "/users/42?a=1");
        assert!(req.path == "/users/42?a=1");
        assert_eq!(format!("{}", req.path), "/users/42?a=1");
        // Deref<Target = str> keeps the `&str` surface intact.
        assert!(req.path.starts_with("/users"));
    }

    #[test]
    fn request_body_is_bytes_and_the_shadow_field_is_gone() {
        let mut req = HttpRequest::new("POST", "/x");
        req.set_body(b"hello".to_vec());
        assert_eq!(req.body_slice(), b"hello");
        // The old two-field arrangement could disagree with itself; one field
        // cannot.
        assert_eq!(req.body_bytes(), Bytes::from_static(b"hello"));
        assert!(req.has_bytes_body());

        req.set_body_bytes(Bytes::from_static(b"world"));
        assert_eq!(req.body_slice(), b"world");
        assert_eq!(req.body_ref(), b"world");
    }

    #[test]
    fn cloning_a_body_does_not_copy_it() {
        let big = Bytes::from(vec![7u8; 64 * 1024]);
        let mut req = HttpRequest::new("POST", "/x");
        req.set_body_bytes(big.clone());
        let copy = req.clone();
        // Same allocation, reached from two requests: the whole point of Bytes.
        assert_eq!(copy.body.as_ptr(), req.body.as_ptr());
    }

    #[test]
    fn response_body_is_bytes() {
        let mut resp = HttpResponse::new(200);
        resp.body = Bytes::from_static(b"{}");
        assert_eq!(resp.body_slice(), b"{}");
        assert_eq!(resp.body_len(), 2);
    }

    #[test]
    fn method_compares_against_str_and_reports_itself_as_str() {
        let req = HttpRequest::new("DELETE", "/x".to_string());
        assert!(req.method == "DELETE");
        assert!(req.method != "GET");
        assert_eq!(req.method_str(), "DELETE");

        // An unknown token survives intact rather than being coerced.
        let odd = HttpRequest::new("PURGE", "/x".to_string());
        assert_eq!(odd.method_str(), "PURGE");
        assert!(odd.method == "PURGE");
    }

    #[test]
    fn test_http_request_new() {
        let req = HttpRequest::new("GET", "/test".to_string());
        assert_eq!(req.method, "GET");
        assert_eq!(req.path, "/test");
        assert!(req.headers.is_empty());
        assert!(req.body.is_empty());
    }

    #[test]
    fn test_http_request_with_body() {
        let mut req = HttpRequest::new("POST", "/api".to_string());
        req.body = Bytes::from(vec![1, 2, 3, 4]);
        assert_eq!(req.body.len(), 4);
    }

    #[test]
    fn test_http_request_json_deserialization() {
        #[derive(Deserialize, Debug, PartialEq)]
        struct TestData {
            name: String,
            age: u32,
        }

        let mut req = HttpRequest::new("POST", "/api".to_string());
        req.body = Bytes::from(
            serde_json::to_vec(&serde_json::json!({
                "name": "John",
                "age": 30
            }))
            .unwrap(),
        );

        let data: TestData = req.json().unwrap();
        assert_eq!(data.name, "John");
        assert_eq!(data.age, 30);
    }

    #[test]
    fn test_http_request_param() {
        let mut req = HttpRequest::new("GET", "/users/123".to_string());
        req.push_param("id", "123");

        assert_eq!(req.param("id"), Some("123"));
        assert_eq!(req.param("name"), None);
    }

    #[test]
    fn test_http_request_query() {
        let req = HttpRequest::new("GET", "/users?sort=asc");

        assert_eq!(req.query_param("sort"), Some("asc"));
        assert_eq!(req.query_param("limit"), None);
    }

    #[test]
    fn test_http_request_clone() {
        let req1 = HttpRequest::new("GET", "/test".to_string());
        let req2 = req1.clone();

        assert_eq!(req1.method, req2.method);
        assert_eq!(req1.path, req2.path);
    }

    #[test]
    fn test_http_response_ok() {
        let res = HttpResponse::ok();
        assert_eq!(res.status, 200);
    }

    #[test]
    fn test_http_response_created() {
        let res = HttpResponse::created();
        assert_eq!(res.status, 201);
    }

    #[test]
    fn test_http_response_no_content() {
        let res = HttpResponse::no_content();
        assert_eq!(res.status, 204);
    }

    #[test]
    fn test_http_response_bad_request() {
        let res = HttpResponse::bad_request();
        assert_eq!(res.status, 400);
    }

    #[test]
    fn test_http_response_not_found() {
        let res = HttpResponse::not_found();
        assert_eq!(res.status, 404);
    }

    #[test]
    fn test_http_response_internal_server_error() {
        let res = HttpResponse::internal_server_error();
        assert_eq!(res.status, 500);
    }

    #[test]
    fn test_http_response_with_body() {
        let body = b"Hello, World!".to_vec();
        let res = HttpResponse::ok().with_body(body.clone());
        assert_eq!(res.body, body);
    }

    #[test]
    fn test_http_response_with_json() {
        #[derive(Serialize)]
        struct TestData {
            message: String,
        }

        let data = TestData {
            message: "test".to_string(),
        };

        let res = HttpResponse::ok().with_json(&data).unwrap();
        assert!(!res.body_ref().is_empty());
        assert_eq!(
            res.headers.get("Content-Type"),
            Some(&"application/json".to_string())
        );
    }

    #[test]
    fn test_http_response_with_header() {
        let res = HttpResponse::ok().with_header("X-Custom".to_string(), "value".to_string());

        assert_eq!(res.headers.get("X-Custom"), Some(&"value".to_string()));
    }

    #[test]
    fn test_http_response_multiple_headers() {
        let res = HttpResponse::ok()
            .with_header("X-Header-1".to_string(), "value1".to_string())
            .with_header("X-Header-2".to_string(), "value2".to_string());

        assert_eq!(res.headers.len(), 2);
    }

    #[test]
    fn test_json_helper() {
        #[derive(Serialize)]
        struct Data {
            value: i32,
        }

        let json = Json(Data { value: 42 });
        let response = json.into_response().unwrap();

        assert_eq!(response.status, 200);
        assert!(!response.body_ref().is_empty());
    }

    #[test]
    fn test_http_request_with_headers() {
        let mut req = HttpRequest::new("GET", "/api".to_string());
        req.headers
            .insert("Authorization", "Bearer token".to_string());
        req.headers
            .insert("Content-Type", "application/json".to_string());

        assert_eq!(req.headers.len(), 2);
    }

    #[test]
    fn test_http_request_from_parts_headermap_roundtrip() {
        // `from_parts` still takes a HashMap for backwards compatibility, but
        // now stores headers in a `HeaderMap`. Lookups must be case-insensitive.
        let mut headers = HashMap::new();
        headers.insert("Content-Type".to_string(), "application/json".to_string());
        headers.insert("X-Custom".to_string(), "abc".to_string());

        let req = HttpRequest::from_parts(
            "GET",
            "/api".to_string(),
            headers,
            Vec::new(),
            HashMap::new(),
            HashMap::new(),
        );

        assert_eq!(req.headers.len(), 2);
        // Case-insensitive lookup via HeaderMap.
        assert_eq!(req.headers.get("content-type"), Some("application/json"));
        assert_eq!(req.headers.get("Content-Type"), Some("application/json"));
        assert!(req.headers.contains_key("x-custom"));
    }

    #[test]
    fn test_http_request_json_invalid() {
        #[derive(Deserialize)]
        #[allow(dead_code)]
        struct TestData {
            name: String,
        }

        let mut req = HttpRequest::new("POST", "/api".to_string());
        req.body = Bytes::from_static(b"invalid json");

        let result: Result<TestData, crate::Error> = req.json();
        assert!(result.is_err());
    }

    #[test]
    fn test_http_response_new_custom_status() {
        let res = HttpResponse::new(418); // I'm a teapot
        assert_eq!(res.status, 418);
    }

    #[test]
    fn test_http_response_with_json_complex() {
        #[derive(Serialize)]
        struct ComplexData {
            nested: Vec<HashMap<String, i32>>,
        }

        let mut map = HashMap::new();
        map.insert("key".to_string(), 123);

        let data = ComplexData { nested: vec![map] };

        let res = HttpResponse::ok().with_json(&data);
        assert!(res.is_ok());
    }
}