ic-asset-router 0.1.0

//! Build full-stack web applications on the Internet Computer with file-based
//! routing conventions familiar from Next.js and SvelteKit — but in Rust,
//! compiled to a single canister. Drop a handler file into `src/routes/`,
//! deploy, and your endpoint is live with automatic response certification,
//! typed parameters, scoped middleware, and configurable security headers.
//!
//! # Features
//!
//! - **File-based routing** — `src/routes/` maps directly to URL paths.
//!   Dynamic segments (`_postId/`), catch-all wildcards (`all.rs`), dotted
//!   filenames (`og.png.rs` → `/og.png`), and nested directories all work
//!   out of the box. See [`build::generate_routes`].
//! - **IC response certification** — responses are automatically certified so
//!   boundary nodes can verify them. Choose from three certification modes
//!   (Skip, ResponseOnly, Full) per route or per asset. See
//!   [Certification Modes](#certification-modes) below.
//! - **Typed route context** — handlers receive a [`RouteContext`] with typed
//!   path params, typed search params, headers, body, and the full URL.
//! - **Scoped middleware** — place a `middleware.rs` in any directory to wrap
//!   all handlers below it. Middleware composes from root to leaf.
//!   See [`middleware::MiddlewareFn`].
//! - **Catch-all wildcards** — name a file `all.rs` to capture the remaining
//!   path. The matched tail is available as `ctx.wildcard`.
//! - **Custom 404 handler** — place a `not_found.rs` at the routes root to
//!   serve a styled error page instead of the default plain-text 404.
//! - **Security headers** — choose from [`SecurityHeaders::strict`],
//!   [`SecurityHeaders::permissive`], or [`SecurityHeaders::none`] presets,
//!   or configure individual headers.
//! - **Cache control & TTL** — set `Cache-Control` per asset type, configure
//!   TTL-based expiry via [`CacheConfig`], and invalidate cached responses
//!   with [`invalidate_path`], [`invalidate_prefix`], or
//!   [`invalidate_all_dynamic`].
//!
//! # Quick Start
//!
//! **1. Build script** — scans `src/routes/` and generates the route tree:
//!
//! ```rust,ignore
//! // build.rs
//! fn main() {
//!     ic_asset_router::build::generate_routes();
//! }
//! ```
//!
//! **2. Route handler** — a file in `src/routes/` with public `get`, `post`,
//! etc. functions:
//!
//! ```rust,ignore
//! // src/routes/index.rs
//! use ic_asset_router::{HttpResponse, RouteContext, StatusCode};
//! use std::borrow::Cow;
//!
//! pub fn get(_ctx: RouteContext<()>) -> HttpResponse<'static> {
//!     HttpResponse::builder()
//!         .with_status_code(StatusCode::OK)
//!         .with_headers(vec![(
//!             "content-type".to_string(),
//!             "text/html; charset=utf-8".to_string(),
//!         )])
//!         .with_body(Cow::<[u8]>::Owned(b"<h1>Hello from the IC!</h1>".to_vec()))
//!         .build()
//! }
//! ```
//!
//! **3. Canister wiring** — include the generated route tree and expose the
//! HTTP interface:
//!
//! ```rust,ignore
//! // src/lib.rs
//! mod route_tree {
//!     include!(concat!(env!("OUT_DIR"), "/__route_tree.rs"));
//! }
//!
//! fn setup() {
//!     route_tree::ROUTES.with(|routes| {
//!         ic_asset_router::setup(routes).build();
//!     });
//! }
//! ```
//!
//! See the [`examples/`](https://github.com/kristoferlund/ic-asset-router/tree/main/examples)
//! directory for complete, deployable canister projects including a
//! [React SPA](https://github.com/kristoferlund/ic-asset-router/tree/main/examples/react-app)
//! with TanStack Router/Query and per-route SEO meta tags.
//!
//! # Route Handlers
//!
//! Each `.rs` file in `src/routes/` is a route handler. Export one or more
//! public functions named after HTTP methods and the build script wires them
//! to the matching URL path automatically.
//!
//! ## Supported Methods
//!
//! Export any combination of `get`, `post`, `put`, `patch`, `delete`, `head`,
//! or `options` as `pub fn` from a single file. Private functions are ignored.
//! A file with no recognized public method function causes a build error.
//!
//! ## Handler Signature
//!
//! Every handler receives a [`RouteContext`] and returns an
//! [`HttpResponse<'static>`](HttpResponse). All types are re-exported from
//! `ic_asset_router` — no need to depend on `ic_http_certification` directly:
//!
//! ```rust,ignore
//! use ic_asset_router::{HttpResponse, RouteContext, StatusCode};
//! use std::borrow::Cow;
//!
//! pub fn get(_ctx: RouteContext<()>) -> HttpResponse<'static> {
//!     HttpResponse::builder()
//!         .with_status_code(StatusCode::OK)
//!         .with_headers(vec![("content-type".into(), "text/plain".into())])
//!         .with_body(Cow::<[u8]>::Owned(b"Hello!".to_vec()))
//!         .build()
//! }
//! ```
//!
//! The type parameter `P` in `RouteContext<P>` is the typed params struct
//! generated by the build script for routes with dynamic segments. Use `()`
//! for routes without dynamic segments.
//!
//! ## Multiple Methods in One File
//!
//! A single file can handle several HTTP methods. The library returns
//! `405 Method Not Allowed` with a correct `Allow` header for methods
//! that exist at the same path but weren't requested:
//!
//! ```rust,ignore
//! // src/routes/items/_itemId/index.rs
//! use ic_asset_router::{HttpResponse, RouteContext, StatusCode};
//!
//! pub fn get(ctx: RouteContext<Params>) -> HttpResponse<'static> {
//!     // GET /items/:itemId — retrieve
//!     # todo!()
//! }
//!
//! pub fn put(ctx: RouteContext<Params>) -> HttpResponse<'static> {
//!     // PUT /items/:itemId — update
//!     # todo!()
//! }
//!
//! pub fn delete(ctx: RouteContext<Params>) -> HttpResponse<'static> {
//!     // DELETE /items/:itemId — delete
//!     # todo!()
//! }
//!
//! use super::Params; // generated: pub struct Params { pub item_id: String }
//! ```
//!
//! ## What RouteContext Provides
//!
//! Handlers receive all request data through the context object:
//!
//! - `ctx.params` — typed path parameters (e.g. `ctx.params.post_id`)
//! - `ctx.search` — typed search (query string) params (default `()`)
//! - `ctx.query` — untyped query params (`HashMap<String, String>`)
//! - `ctx.method` — HTTP method
//! - `ctx.headers` — request headers
//! - `ctx.body` — raw request body bytes
//! - `ctx.url` — full request URL
//! - `ctx.wildcard` — catch-all wildcard tail (`Option<String>`)
//!
//! Convenience methods: [`ctx.header()`](RouteContext::header),
//! [`ctx.body_to_str()`](RouteContext::body_to_str),
//! [`ctx.json::<T>()`](RouteContext::json),
//! [`ctx.form::<T>()`](RouteContext::form),
//! [`ctx.form_data()`](RouteContext::form_data).
//!
//! See the [`json-api`](https://github.com/kristoferlund/ic-asset-router/tree/main/examples/json-api)
//! example for a complete REST API with GET, POST, PUT, and DELETE.
//!
//! # Middleware
//!
//! Place a `middleware.rs` file in any directory under `src/routes/` and it
//! wraps every handler in that directory and all subdirectories below it.
//! The file must export a `pub fn middleware` with the
//! [`MiddlewareFn`](middleware::MiddlewareFn) signature:
//!
//! ```rust,ignore
//! use ic_asset_router::{HttpRequest, HttpResponse, RouteParams};
//!
//! pub fn middleware(
//!     req: HttpRequest,
//!     params: &RouteParams,
//!     next: &dyn Fn(HttpRequest, &RouteParams) -> HttpResponse<'static>,
//! ) -> HttpResponse<'static> {
//!     // Before: inspect or modify the request
//!     let response = next(req, params);
//!     // After: inspect or modify the response
//!     response
//! }
//! ```
//!
//! Middleware can:
//!
//! - **Modify the request** — `req` is owned; construct or alter it before
//!   passing to `next`.
//! - **Modify the response** — capture the return value of `next` and
//!   transform headers, body, or status before returning.
//! - **Short-circuit** — return a response without calling `next` at all
//!   (e.g. return 401 for unauthorized requests). The handler never executes.
//!
//! ## Composition Order
//!
//! Middleware at different directory levels composes automatically in
//! root-to-leaf order. For a request to `/api/v2/data`:
//!
//! ```text
//! root middleware → /api middleware → /api/v2 middleware → handler
//! ```
//!
//! On the way back, responses unwind in reverse (onion model). Only one
//! middleware per directory is allowed. Middleware also wraps the custom
//! 404 handler — root-level middleware runs before `not_found.rs`.
//!
//! ## Example: CORS Middleware
//!
//! ```rust,ignore
//! use ic_asset_router::{HttpRequest, HttpResponse, RouteParams, StatusCode};
//!
//! pub fn middleware(
//!     req: HttpRequest,
//!     params: &RouteParams,
//!     next: &dyn Fn(HttpRequest, &RouteParams) -> HttpResponse<'static>,
//! ) -> HttpResponse<'static> {
//!     let cors_headers = vec![
//!         ("access-control-allow-origin".into(), "*".into()),
//!         ("access-control-allow-methods".into(), "GET, POST, PUT, DELETE, OPTIONS".into()),
//!         ("access-control-allow-headers".into(), "content-type".into()),
//!     ];
//!
//!     // Short-circuit: respond to OPTIONS preflight without running the handler
//!     if req.method().as_str() == "OPTIONS" {
//!         return HttpResponse::builder()
//!             .with_status_code(StatusCode::NO_CONTENT)
//!             .with_headers(cors_headers)
//!             .build();
//!     }
//!
//!     let response = next(req, params);
//!
//!     // Append CORS headers to the response
//!     let mut headers = response.headers().to_vec();
//!     headers.extend(cors_headers);
//!     HttpResponse::builder()
//!         .with_status_code(response.status_code())
//!         .with_headers(headers)
//!         .with_body(response.body().to_vec())
//!         .build()
//! }
//! ```
//!
//! See the [`json-api`](https://github.com/kristoferlund/ic-asset-router/tree/main/examples/json-api)
//! example for a working CORS middleware.
//!
//! # Certification Modes
//!
//! Every response served by an IC canister can be cryptographically certified
//! so that boundary nodes can verify it was not tampered with. This library
//! supports three certification modes, configurable per-route or per-asset:
//!
//! ## Choosing a Mode
//!
//! **Start with Response-Only (the default).** It is correct for 90% of
//! routes and requires zero configuration.
//!
//! | Mode | When to use | Example routes |
//! |------|-------------|----------------|
//! | **Response-only** | Same URL always returns same content | Static pages, blog posts, docs |
//! | **Skip** | Tampering has no security impact | Health checks, `/ping` |
//! | **Skip + handler auth** | Fast auth-gated API (query-path perf) | `/api/customers`, `/api/me` |
//! | **Authenticated** | Response depends on caller identity, must be tamper-proof | User profiles, dashboards |
//! | **Custom (Full)** | Response depends on specific headers/params | Content negotiation, pagination |
//!
//! ## Response-Only (Default)
//!
//! No attribute needed — just write your handler:
//!
//! ```rust,ignore
//! pub fn get(_ctx: RouteContext<()>) -> HttpResponse<'static> {
//!     // Automatically uses ResponseOnly certification
//!     HttpResponse::builder()
//!         .with_status_code(StatusCode::OK)
//!         .with_body(b"Hello!" as &[u8])
//!         .build()
//! }
//! ```
//!
//! The response body, status code, and headers are certified. The request
//! details are not included in the hash. This is sufficient when the
//! response depends only on the URL path and canister state.
//!
//! ## Skip Certification
//!
//! ```rust,ignore
//! #[route(certification = "skip")]
//! pub fn get(_ctx: RouteContext<()>) -> HttpResponse<'static> {
//!     // Handler runs on every query call — like a candid query
//!     HttpResponse::builder()
//!         .with_body(b"{\"status\":\"ok\"}" as &[u8])
//!         .build()
//! }
//! ```
//!
//! **Handler execution:** Skip-mode routes run the handler on every query
//! call, just like candid `query` calls. This makes them ideal for
//! auth-gated API endpoints — combine with handler-level auth (JWT
//! validation, `ic_cdk::caller()` checks) for fast (~200ms) authenticated
//! queries without waiting for consensus (~2s update calls).
//!
//! **Security note:** Skip certification provides the same trust level as
//! candid query calls — both trust the responding replica without
//! cryptographic verification by the boundary node. If candid queries are
//! acceptable for your application, skip certification is equally
//! acceptable.
//!
//! ### Skip + Handler Auth Pattern
//!
//! ```rust,ignore
//! #[route(certification = "skip")]
//! pub fn get(ctx: RouteContext<()>) -> HttpResponse<'static> {
//!     let caller = ic_cdk::caller();
//!     if caller == Principal::anonymous() {
//!         return HttpResponse::builder()
//!             .with_status_code(StatusCode::UNAUTHORIZED)
//!             .with_body(b"unauthorized" as &[u8])
//!             .build();
//!     }
//!     // Return caller-specific data
//!     HttpResponse::builder()
//!         .with_body(format!("hello {caller}").into_bytes())
//!         .build()
//! }
//! ```
//!
//! See the [`api-authentication`](https://github.com/kristoferlund/ic-asset-router/tree/main/examples/api-authentication)
//! example for a complete demonstration of both patterns.
//!
//! ## Authenticated (Full Certification Preset)
//!
//! ```rust,ignore
//! #[route(certification = "authenticated")]
//! pub fn get(_ctx: RouteContext<()>) -> HttpResponse<'static> {
//!     // Authorization header is included in certification
//!     // User A cannot receive User B's cached response
//!     HttpResponse::builder()
//!         .with_body(b"{\"name\":\"Alice\"}" as &[u8])
//!         .build()
//! }
//! ```
//!
//! The `authenticated` preset is a preconfigured Full mode that includes
//! the `Authorization` request header and `Content-Type` response header.
//!
//! ## Custom Full Certification
//!
//! ```rust,ignore
//! #[route(certification = custom(
//!     request_headers = ["accept"],
//!     query_params = ["page", "limit"]
//! ))]
//! pub fn get(_ctx: RouteContext<()>) -> HttpResponse<'static> {
//!     // Each combination of Accept + page + limit is independently certified
//!     HttpResponse::builder()
//!         .with_body(b"page content" as &[u8])
//!         .build()
//! }
//! ```
//!
//! ## Setup with Static Assets
//!
//! Configure and certify assets in a single builder chain during
//! `init`/`post_upgrade`:
//!
//! ```rust,ignore
//! use ic_asset_router::CertificationMode;
//!
//! route_tree::ROUTES.with(|routes| {
//!     ic_asset_router::setup(routes)
//!         .with_assets(&STATIC_DIR)                                   // response-only (default)
//!         .with_assets_certified(&PUBLIC_DIR, CertificationMode::skip()) // skip
//!         .build();
//! });
//! ```
//!
//! ## Performance Comparison
//!
//! | Mode | Relative cost | Witness size |
//! |------|---------------|--------------|
//! | Skip | ~0 | Minimal |
//! | Response-only | Low | ~200 bytes |
//! | Full (authenticated) | Medium | ~300 bytes |
//! | Full (custom) | Medium–High | ~300–500 bytes |
//!
//! ## Security Model: Certification vs Candid Calls
//!
//! IC canisters support two HTTP interfaces and two candid call types, each
//! with different trust assumptions:
//!
//! | Mechanism | Consensus | Boundary node verifies? | Trust model |
//! |-----------|-----------|------------------------|-------------|
//! | Candid **update** call | Yes (2s) | N/A | Consensus — response reflects agreed-upon state |
//! | Candid **query** call | No (200ms) | No | Trust the replica |
//! | HTTP + **ResponseOnly/Full** cert | Yes (2s) | Yes | Consensus — boundary node verifies the certificate |
//! | HTTP + **Skip** cert | No (200ms) | No | Trust the replica |
//!
//! **Key insight:** Skip certification and candid query calls have the same
//! trust model. Both execute on a single replica without consensus, and
//! neither response is cryptographically verified. If your application
//! already uses candid queries (as most IC apps do), skip certification
//! is equally acceptable for equivalent operations.
//!
//! ## Common Mistakes
//!
//! - **Over-certifying:** Certifying `User-Agent` causes cache
//!   fragmentation (every browser version gets a separate certificate).
//!   Only certify headers that affect the response content.
//! - **Under-certifying:** Using response-only for authenticated endpoints
//!   means a malicious replica can serve any cached response to any user.
//!   Use `#[route(certification = "authenticated")]` instead.
//! - **Certifying non-deterministic data:** If the response body changes
//!   every call (e.g., timestamps), the certificate is immediately stale.
//!   Use `skip` or add a TTL.

/// Debug logging macro gated behind the `debug-logging` feature flag.
/// When enabled, expands to `ic_cdk::println!`; otherwise compiles to nothing.
#[cfg(feature = "debug-logging")]
macro_rules! debug_log {
    ($($arg:tt)*) => { ic_cdk::println!($($arg)*) };
}

#[cfg(not(feature = "debug-logging"))]
macro_rules! debug_log {
    ($($arg:tt)*) => {};
}

use std::{borrow::Cow, cell::RefCell, rc::Rc};

use assets::get_asset_headers;
use ic_cdk::api::{certified_data_set, data_certificate};
use ic_http_certification::{
    utils::add_v2_certificate_header, DefaultCelBuilder, HttpCertification, HttpCertificationPath,
    HttpCertificationTree, HttpCertificationTreeEntry, CERTIFICATE_EXPRESSION_HEADER_NAME,
};
use router::{RouteNode, RouteResult};

/// Canonical path used to cache the single certified 404 response.
///
/// All not-found responses are certified and cached under this one path
/// instead of per-request-path, preventing memory growth from bot scans.
const NOT_FOUND_CANONICAL_PATH: &str = "/__not_found";

/// Extract the `content-type` header value from an HTTP response.
///
/// Performs a case-insensitive search for the `content-type` header.
/// Returns `"application/octet-stream"` if no content-type header is present.
fn extract_content_type(response: &HttpResponse) -> String {
    response
        .headers()
        .iter()
        .find(|(k, _)| k.eq_ignore_ascii_case("content-type"))
        .map(|(_, v)| v.clone())
        .unwrap_or_else(|| "application/octet-stream".to_string())
}

/// Build a 405 Method Not Allowed response with an `Allow` header listing the
/// permitted methods for the requested path.
fn method_not_allowed(allowed: &[Method]) -> HttpResponse<'static> {
    let allow = allowed
        .iter()
        .map(|m| m.as_str())
        .collect::<Vec<_>>()
        .join(", ");
    HttpResponse::builder()
        .with_status_code(StatusCode::METHOD_NOT_ALLOWED)
        .with_headers(vec![
            ("allow".to_string(), allow),
            ("content-type".to_string(), "text/plain".to_string()),
        ])
        .with_body(Cow::<[u8]>::Owned(b"Method Not Allowed".to_vec()))
        .build()
}

/// Build a plain-text error response for the given HTTP status code and message.
///
/// This avoids canister traps by returning a well-formed HTTP response instead
/// of panicking on malformed input or missing internal state.
fn error_response(status: u16, message: &str) -> HttpResponse<'static> {
    HttpResponse::builder()
        .with_status_code(StatusCode::from_u16(status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR))
        .with_headers(vec![("content-type".to_string(), "text/plain".to_string())])
        .with_body(Cow::<[u8]>::Owned(message.as_bytes().to_vec()))
        .build()
}

/// Custom asset router with per-asset certification modes.
pub mod asset_router;
/// Static and dynamic asset certification, invalidation, and serving helpers.
pub mod assets;
/// Build-script utilities for file-based route generation.
pub mod build;
/// Certification mode configuration types.
pub mod certification;
/// Global configuration types: security headers, cache control, TTL settings.
pub mod config;
/// Request context types passed to route handlers.
pub mod context;
/// Middleware type definition.
pub mod middleware;
/// MIME type detection from file extensions.
pub mod mime;
/// Per-route configuration types (certification mode, TTL, headers).
pub mod route_config;
/// Route trie, handler types, and dispatch logic.
pub mod router;

pub use assets::{
    delete_assets, invalidate_all_dynamic, invalidate_path, invalidate_prefix, last_certified_at,
};
pub use certification::{CertificationMode, FullConfig, FullConfigBuilder, ResponseOnlyConfig};
pub use config::{AssetConfig, CacheConfig, CacheControl, SecurityHeaders};
pub use context::{
    deserialize_search_params, parse_form_body, parse_query, url_decode, FormBodyError,
    JsonBodyError, QueryParams, RouteContext,
};
pub use ic_asset_router_macros::route;
pub use ic_http_certification::{HttpRequest, HttpResponse, Method, StatusCode};
pub use route_config::RouteConfig;
pub use router::{HandlerResult, RouteParams};

thread_local! {
    static HTTP_TREE: Rc<RefCell<HttpCertificationTree>> = Default::default();
    static ASSET_ROUTER: RefCell<asset_router::AssetRouter> = RefCell::new(asset_router::AssetRouter::with_tree(HTTP_TREE.with(|tree| tree.clone())));
    static ROUTER_CONFIG: RefCell<AssetConfig> = RefCell::new(AssetConfig::default());
}

/// Set the global router configuration.
fn set_asset_config(config: AssetConfig) {
    ROUTER_CONFIG.with(|c| {
        *c.borrow_mut() = config;
    });
}

/// Register skip-certification tree entries for all routes configured with
/// [`CertificationMode::Skip`].
fn register_skip_routes(root_route_node: &router::RouteNode) {
    let skip_paths = root_route_node.skip_certified_paths();
    if skip_paths.is_empty() {
        return;
    }

    // Insert skip certification tree entries directly into the shared tree
    // WITHOUT storing a CertifiedAsset. This ensures the skip handler runs
    // on every query call instead of serving a cached empty response.
    HTTP_TREE.with(|tree| {
        let mut tree = tree.borrow_mut();
        for path in &skip_paths {
            let tree_path = HttpCertificationPath::exact(path.to_string());
            let certification = HttpCertification::skip();
            let tree_entry = HttpCertificationTreeEntry::new(tree_path, certification);
            tree.insert(&tree_entry);
        }
    });

    // Update the root hash to include the new skip entries.
    ASSET_ROUTER.with_borrow(|asset_router| {
        certified_data_set(&asset_router.root_hash());
    });

    debug_log!("registered {} skip certification entries", skip_paths.len());
}

// ---------------------------------------------------------------------------
// Setup builder
// ---------------------------------------------------------------------------

/// Entry point for canister initialization. Returns a [`SetupBuilder`] that
/// configures the asset router, certifies assets, and registers skip routes
/// in a single fluent chain.
///
/// Call this during `init` and `post_upgrade`:
///
/// ```rust,ignore
/// use include_dir::{include_dir, Dir};
///
/// mod route_tree {
///     include!(concat!(env!("OUT_DIR"), "/__route_tree.rs"));
/// }
///
/// static ASSET_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/assets");
///
/// fn setup() {
///     route_tree::ROUTES.with(|routes| {
///         ic_asset_router::setup(routes)
///             .with_assets(&ASSET_DIR)
///             .build();
///     });
/// }
/// ```
pub fn setup(routes: &router::RouteNode) -> SetupBuilder<'_> {
    SetupBuilder {
        routes,
        config: None,
        asset_dirs: Vec::new(),
        delete_paths: Vec::new(),
    }
}

/// Builder for canister initialization. Created by [`setup()`].
///
/// Calling [`.build()`](SetupBuilder::build) executes the following steps
/// in order:
///
/// 1. Sets the global [`AssetConfig`] (or uses the default).
/// 2. Certifies each registered asset directory.
/// 3. Deletes any paths registered via [`delete_assets`](SetupBuilder::delete_assets).
/// 4. Registers skip-certification tree entries for all skip-mode routes.
/// 5. Calls `certified_data_set` with the final root hash.
pub struct SetupBuilder<'r> {
    routes: &'r router::RouteNode,
    config: Option<AssetConfig>,
    asset_dirs: Vec<(
        &'static include_dir::Dir<'static>,
        certification::CertificationMode,
    )>,
    delete_paths: Vec<&'static str>,
}

impl<'r> SetupBuilder<'r> {
    /// Override the default [`AssetConfig`].
    ///
    /// If not called, [`AssetConfig::default()`] is used.
    pub fn with_config(mut self, config: AssetConfig) -> Self {
        self.config = Some(config);
        self
    }

    /// Certify all files in `dir` with the default certification mode
    /// (response-only).
    pub fn with_assets(mut self, dir: &'static include_dir::Dir<'static>) -> Self {
        self.asset_dirs
            .push((dir, certification::CertificationMode::response_only()));
        self
    }

    /// Certify all files in `dir` with a specific [`CertificationMode`].
    pub fn with_assets_certified(
        mut self,
        dir: &'static include_dir::Dir<'static>,
        mode: certification::CertificationMode,
    ) -> Self {
        self.asset_dirs.push((dir, mode));
        self
    }

    /// Delete previously certified assets at the given paths.
    ///
    /// Useful when static assets (e.g. a SPA's `index.html`) should be
    /// replaced by dynamically generated responses with route-specific
    /// content (e.g. SEO meta tags).
    pub fn delete_assets(mut self, paths: Vec<&'static str>) -> Self {
        self.delete_paths.extend(paths);
        self
    }

    /// Execute the setup: apply config, certify assets, register skip
    /// routes, and commit the certification tree root hash.
    pub fn build(self) {
        // 1. Set config.
        set_asset_config(self.config.unwrap_or_default());

        // 2. Certify asset directories.
        for (dir, mode) in &self.asset_dirs {
            assets::certify_assets_with_mode(dir, mode.clone());
        }

        // 3. Delete specified asset paths.
        if !self.delete_paths.is_empty() {
            assets::delete_assets(self.delete_paths);
        }

        // 4. Register skip routes.
        register_skip_routes(self.routes);
    }
}

/// Options controlling the behavior of [`http_request`].
pub struct HttpRequestOptions {
    /// Whether to attempt serving a certified response from the asset router.
    ///
    /// When `true` (the default), the library checks the asset router for a
    /// previously certified response and returns it directly if available.
    /// When `false`, the handler runs on every request and the response is
    /// served with a skip-certification proof.
    pub certify: bool,
}

impl Default for HttpRequestOptions {
    fn default() -> Self {
        HttpRequestOptions { certify: true }
    }
}

/// Handle an HTTP query-path request.
///
/// This is the IC `http_request` entry point. It resolves the incoming
/// request against the route tree and either:
///
/// 1. Serves a previously certified response from the asset router, or
/// 2. Upgrades the request to an update call (returns `upgrade: true`) so
///    that the handler can run in `http_request_update` and certify a new
///    response.
///
/// Non-GET/HEAD requests are always upgraded. GET requests for dynamic
/// routes with expired TTLs are also upgraded.
pub fn http_request(
    req: HttpRequest,
    root_route_node: &RouteNode,
    opts: HttpRequestOptions,
) -> HttpResponse<'static> {
    debug_log!("http_request: {:?}", req.url());

    let path = match req.get_path() {
        Ok(p) => p,
        Err(_) => return error_response(400, "Bad Request: malformed URL"),
    };

    let method = req.method().clone();

    // Non-GET requests arriving at the query endpoint must be upgraded to an
    // update call so that state-mutating handlers execute in the update path.
    if method != Method::GET && method != Method::HEAD {
        debug_log!(
            "upgrading non-GET request ({}) to update call",
            method.as_str()
        );
        return HttpResponse::builder().with_upgrade(true).build();
    }

    match root_route_node.resolve(&path, &method) {
        RouteResult::Found(handler, params, _result_handler, pattern) => match opts.certify {
            false => {
                debug_log!("Serving {} without certification", path);
                let mut response =
                    root_route_node.execute_with_middleware(&path, handler, req, params);

                // Add the CEL expression header so the boundary node knows
                // this response uses skip certification.
                response.add_header((
                    CERTIFICATE_EXPRESSION_HEADER_NAME.to_string(),
                    DefaultCelBuilder::skip_certification().to_string(),
                ));

                HTTP_TREE.with(|tree| {
                    let tree = tree.borrow();

                    let cert = match data_certificate() {
                        Some(c) => c,
                        None => {
                            return error_response(
                                500,
                                "Internal Server Error: no data certificate available",
                            );
                        }
                    };

                    let tree_path = HttpCertificationPath::exact(&path);
                    let certification = HttpCertification::skip();
                    let tree_entry = HttpCertificationTreeEntry::new(&tree_path, certification);

                    let witness = match tree.witness(&tree_entry, &path) {
                        Ok(w) => w,
                        Err(_) => {
                            return error_response(
                                500,
                                "Internal Server Error: failed to create certification witness",
                            );
                        }
                    };

                    add_v2_certificate_header(
                        &cert,
                        &mut response,
                        &witness,
                        &tree_path.to_expr_path(),
                    );

                    response
                })
            }
            true => {
                // Full certification mode (e.g. authenticated routes) binds the
                // proof to specific request header values. A cached response
                // certified for Alice's token will fail verification when served
                // to Bob. Always upgrade Full-mode routes to http_request_update
                // so each request gets a freshly certified response.
                let route_config = root_route_node.get_route_config(&pattern);
                let cert_mode = route_config.map(|rc| &rc.certification);

                // Full certification mode binds the proof to specific request
                // header values. Always upgrade to http_request_update so each
                // caller gets a freshly certified response.
                if matches!(cert_mode, Some(certification::CertificationMode::Full(_))) {
                    debug_log!("upgrading (full certification mode: {})", path);
                    return HttpResponse::builder().with_upgrade(true).build();
                }

                // Skip certification mode: run the handler on every query call,
                // like a candid query call. The skip tree entry was registered
                // at init time by `register_skip_routes`, so we just run the
                // handler and attach the skip certification witness.
                if matches!(cert_mode, Some(certification::CertificationMode::Skip)) {
                    debug_log!("skip mode: running handler inline for {}", path);
                    let mut response =
                        root_route_node.execute_with_middleware(&path, handler, req, params);

                    // Add the CEL expression header so the boundary node knows
                    // this response uses skip certification.
                    response.add_header((
                        CERTIFICATE_EXPRESSION_HEADER_NAME.to_string(),
                        DefaultCelBuilder::skip_certification().to_string(),
                    ));

                    // Add skip certification proof from the shared tree.
                    return HTTP_TREE.with(|tree| {
                        let tree = tree.borrow();
                        let cert = match data_certificate() {
                            Some(c) => c,
                            None => {
                                return error_response(
                                    500,
                                    "Internal Server Error: no data certificate available",
                                );
                            }
                        };

                        let tree_path = HttpCertificationPath::exact(path.to_string());
                        let tree_certification = HttpCertification::skip();
                        let tree_entry =
                            HttpCertificationTreeEntry::new(tree_path.clone(), tree_certification);

                        let witness = match tree.witness(&tree_entry, &path) {
                            Ok(w) => w,
                            Err(_) => {
                                return error_response(
                                    500,
                                    "Internal Server Error: failed to create skip certification witness",
                                );
                            }
                        };

                        add_v2_certificate_header(
                            &cert,
                            &mut response,
                            &witness,
                            &tree_path.to_expr_path(),
                        );
                        response
                    });
                }

                // Check the unified AssetRouter to determine cache state.
                // Three outcomes:
                //   Missing  — no asset at this path; upgrade to generate.
                //   Expired  — dynamic asset with elapsed TTL; upgrade to regenerate.
                //   Valid    — serve from asset router.
                //
                // We check the asset directly (not via serve_asset) to avoid
                // matching a fallback when the exact asset was invalidated.
                enum CacheState {
                    Missing,
                    Expired,
                    Valid,
                }

                let cache_state = ASSET_ROUTER.with_borrow(|asset_router| {
                    match asset_router.get_asset(&path) {
                        Some(asset) => {
                            if asset.is_dynamic() {
                                // Check TTL: first asset's own TTL, then global config.
                                let is_expired = if asset.ttl.is_some() {
                                    asset.is_expired(ic_cdk::api::time())
                                } else {
                                    // Check global config TTL.
                                    let effective_ttl = ROUTER_CONFIG
                                        .with(|c| c.borrow().cache_config.effective_ttl(&path));
                                    if let Some(ttl) = effective_ttl {
                                        let now_ns = ic_cdk::api::time();
                                        let expiry_ns = asset
                                            .certified_at
                                            .saturating_add(ttl.as_nanos() as u64);
                                        now_ns >= expiry_ns
                                    } else {
                                        false
                                    }
                                };
                                if is_expired {
                                    CacheState::Expired
                                } else {
                                    CacheState::Valid
                                }
                            } else {
                                // Static asset — always valid.
                                CacheState::Valid
                            }
                        }
                        None => CacheState::Missing,
                    }
                });

                match cache_state {
                    CacheState::Missing => {
                        debug_log!("upgrading (no asset: {})", path);
                        HttpResponse::builder().with_upgrade(true).build()
                    }
                    CacheState::Expired => {
                        debug_log!("upgrading (TTL expired for {})", path);
                        HttpResponse::builder().with_upgrade(true).build()
                    }
                    CacheState::Valid => ASSET_ROUTER.with_borrow(|asset_router| {
                        let cert = match data_certificate() {
                            Some(c) => c,
                            None => {
                                debug_log!("upgrading (no data certificate)");
                                return HttpResponse::builder().with_upgrade(true).build();
                            }
                        };
                        if let Some((mut response, witness, expr_path)) =
                            asset_router.serve_asset(&req)
                        {
                            add_v2_certificate_header(&cert, &mut response, &witness, &expr_path);
                            debug_log!("serving directly");
                            response
                        } else {
                            debug_log!("upgrading");
                            HttpResponse::builder().with_upgrade(true).build()
                        }
                    }),
                }
            }
        },
        RouteResult::MethodNotAllowed(allowed) => method_not_allowed(&allowed),
        RouteResult::NotFound => {
            if opts.certify {
                // Check the unified AssetRouter for the canonical /__not_found entry.
                // All 404 responses are certified under this single path to
                // prevent memory growth from bot scans.
                let canonical_state = ASSET_ROUTER.with_borrow(|asset_router| {
                    asset_router
                        .get_asset(NOT_FOUND_CANONICAL_PATH)
                        .map(|asset| {
                            if asset.is_dynamic() {
                                // Check TTL.
                                let is_expired = if asset.ttl.is_some() {
                                    asset.is_expired(ic_cdk::api::time())
                                } else {
                                    let effective_ttl = ROUTER_CONFIG.with(|c| {
                                        c.borrow()
                                            .cache_config
                                            .effective_ttl(NOT_FOUND_CANONICAL_PATH)
                                    });
                                    if let Some(ttl) = effective_ttl {
                                        let now_ns = ic_cdk::api::time();
                                        let expiry_ns = asset
                                            .certified_at
                                            .saturating_add(ttl.as_nanos() as u64);
                                        now_ns >= expiry_ns
                                    } else {
                                        false
                                    }
                                };
                                is_expired
                            } else {
                                false // Static not-found assets don't expire
                            }
                        })
                });

                match canonical_state {
                    Some(true) => {
                        // Cached but TTL-expired — upgrade to regenerate.
                        debug_log!("upgrading not-found (TTL expired for canonical path)");
                        return HttpResponse::builder().with_upgrade(true).build();
                    }
                    Some(false) => {
                        // Cached and valid — serve from AssetRouter using the
                        // original request. The /__not_found asset is registered
                        // as a fallback for scope "/", so serve_asset() will
                        // match any path that has no exact asset and produce a
                        // correctly certified response for the original URL.
                        return ASSET_ROUTER.with_borrow(|asset_router| {
                            let cert = match data_certificate() {
                                Some(c) => c,
                                None => {
                                    debug_log!("upgrading not-found (no data certificate)");
                                    return HttpResponse::builder().with_upgrade(true).build();
                                }
                            };
                            if let Some((mut response, witness, expr_path)) =
                                asset_router.serve_asset(&req)
                            {
                                add_v2_certificate_header(
                                    &cert,
                                    &mut response,
                                    &witness,
                                    &expr_path,
                                );
                                debug_log!("serving cached not-found for {}", path);
                                response
                            } else {
                                debug_log!(
                                    "upgrading not-found (serve_asset failed for canonical path)"
                                );
                                HttpResponse::builder().with_upgrade(true).build()
                            }
                        });
                    }
                    None => {
                        // Not in router. Try serving a static asset
                        // for the original path before triggering the update.
                        let maybe_response = ASSET_ROUTER.with_borrow(|asset_router| {
                            let cert = data_certificate()?;
                            let (mut response, witness, expr_path) =
                                asset_router.serve_asset(&req)?;
                            add_v2_certificate_header(&cert, &mut response, &witness, &expr_path);
                            Some(response)
                        });
                        if let Some(response) = maybe_response {
                            debug_log!("serving static asset for {}", path);
                            return response;
                        }

                        // No cached response at all — upgrade to run the
                        // not-found handler.
                        debug_log!("upgrading not-found (no cached entry for {})", path);
                        return HttpResponse::builder().with_upgrade(true).build();
                    }
                }
            }

            // Non-certified mode: execute the not-found handler directly
            // without upgrade, same as any other non-certified response.
            if let Some(response) = root_route_node.execute_not_found_with_middleware(&path, req) {
                response
            } else {
                HttpResponse::not_found(
                    b"Not Found",
                    vec![("Content-Type".into(), "text/plain".into())],
                )
                .build()
            }
        }
    }
}

/// Certify a dynamically generated response and store it for future query-path
/// serving.
///
/// The response body is stored in the `AssetRouter` via `certify_asset()`,
/// which lets the query path use `serve_asset()`. All responses — including
/// not-found handler output — go through this single path. The not-found
/// handler's response is certified at the canonical `/__not_found` path so
/// that only one cache entry exists for all 404s.
#[allow(dead_code)]
fn certify_dynamic_response(response: HttpResponse<'static>, path: &str) -> HttpResponse<'static> {
    certify_dynamic_response_inner(
        response,
        path,
        None,
        certification::CertificationMode::response_only(),
        None,
    )
}

/// Certify a dynamic response with per-route certification mode and optional
/// fallback configuration.
///
/// When `fallback_for` is `Some`, the asset is registered as a fallback
/// for the given scope. This is used by the not-found handler to certify
/// a single `/__not_found` asset that serves as a fallback for all paths.
///
/// The `mode` parameter controls how the response is certified:
/// - `Skip` / `ResponseOnly` — uses `certify_asset()` (no request needed).
/// - `Full` — uses `certify_dynamic_asset()` with the original request.
///
/// The `request` parameter is required for `Full` mode and ignored otherwise.
fn certify_dynamic_response_inner(
    response: HttpResponse<'static>,
    path: &str,
    fallback_for: Option<String>,
    mode: certification::CertificationMode,
    request: Option<&HttpRequest>,
) -> HttpResponse<'static> {
    certify_dynamic_response_with_ttl(response, path, fallback_for, mode, request, None)
}

/// Core certification function with all parameters including optional TTL override.
fn certify_dynamic_response_with_ttl(
    response: HttpResponse<'static>,
    path: &str,
    fallback_for: Option<String>,
    mode: certification::CertificationMode,
    request: Option<&HttpRequest>,
    ttl_override: Option<std::time::Duration>,
) -> HttpResponse<'static> {
    let content_type = extract_content_type(&response);
    let effective_ttl = ttl_override
        .or_else(|| ROUTER_CONFIG.with(|c| c.borrow().cache_config.effective_ttl(path)));

    let dynamic_cache_control =
        ROUTER_CONFIG.with(|c| c.borrow().cache_control.dynamic_assets.clone());

    let config = asset_router::AssetCertificationConfig {
        mode: mode.clone(),
        content_type: Some(content_type),
        status_code: response.status_code(),
        headers: get_asset_headers(vec![("cache-control".to_string(), dynamic_cache_control)]),
        encodings: vec![],
        fallback_for,
        aliases: vec![],
        certified_at: ic_cdk::api::time(),
        ttl: effective_ttl,
        dynamic: true,
    };

    ASSET_ROUTER.with_borrow_mut(|asset_router| {
        // Delete any existing asset at this path before re-certifying.
        asset_router.delete_asset(path);

        match &mode {
            certification::CertificationMode::Full(_) => {
                // Full mode requires the original request for certification.
                let req = request.unwrap_or_else(|| {
                    ic_cdk::trap(
                        "Full certification mode requires the original request, \
                         but none was provided",
                    )
                });
                if let Err(err) = asset_router.certify_dynamic_asset(path, req, &response, config) {
                    ic_cdk::trap(format!("Failed to certify dynamic asset (full): {err}"));
                }
            }
            _ => {
                // Skip and ResponseOnly modes use certify_asset.
                if let Err(err) = asset_router.certify_asset(path, response.body().to_vec(), config)
                {
                    ic_cdk::trap(format!("Failed to certify dynamic asset: {err}"));
                }
            }
        }

        certified_data_set(&asset_router.root_hash());
    });

    response
}

/// Handle an HTTP update-path request.
///
/// This is the IC `http_request_update` entry point. It runs the matched
/// route handler (through the middleware chain), certifies the response in
/// the asset router, and caches it for future query-path serving.
///
/// If a [`HandlerResultFn`](router::HandlerResultFn) is registered for the
/// route, it is called first to check for [`HandlerResult::NotModified`].
/// A `NotModified` result preserves the existing cached response and resets
/// the TTL timer (if TTL-based caching is active).
pub fn http_request_update(req: HttpRequest, root_route_node: &RouteNode) -> HttpResponse<'static> {
    debug_log!("http_request_update: {:?}", req.url());

    let path = match req.get_path() {
        Ok(p) => p,
        Err(_) => return error_response(400, "Bad Request: malformed URL"),
    };

    let method = req.method().clone();

    match root_route_node.resolve(&path, &method) {
        RouteResult::Found(handler, params, result_handler, pattern) => {
            // Look up the per-route certification configuration.
            let route_config = root_route_node.get_route_config(&pattern);
            let cert_mode = route_config
                .map(|rc| rc.certification.clone())
                .unwrap_or_else(certification::CertificationMode::response_only);
            let route_ttl = route_config.and_then(|rc| rc.ttl);

            // Skip-mode routes are handled entirely on the query path.
            // They should never reach http_request_update. If they do
            // (e.g. due to a stale upgrade response), just run the handler
            // and return without re-certifying.
            if matches!(&cert_mode, certification::CertificationMode::Skip) {
                debug_log!("skip mode in update path (unexpected): {}", path);
                return root_route_node.execute_with_middleware(&path, handler, req, params);
            }

            // If a HandlerResultFn is registered, call it first to check for
            // NotModified. This avoids running the full middleware + certification
            // pipeline when the handler signals that the content hasn't changed.
            if let Some(result_fn) = result_handler {
                let result = result_fn(req.clone(), params.clone());
                match result {
                    router::HandlerResult::NotModified => {
                        debug_log!("handler returned NotModified for {}", path);

                        // Reset the certified_at timestamp if TTL-based caching
                        // is active. The content was confirmed fresh, so the TTL
                        // timer should restart.
                        ASSET_ROUTER.with_borrow_mut(|asset_router| {
                            if let Some(asset) = asset_router.get_asset_mut(&path) {
                                if asset.ttl.is_some() {
                                    asset.certified_at = ic_cdk::api::time();
                                }
                            }
                        });

                        // Serve the existing cached response from the asset router.
                        return ASSET_ROUTER.with_borrow(|asset_router| {
                            match asset_router.serve_asset(&req) {
                                Some((mut resp, witness, expr_path)) => {
                                    // In an update call, data_certificate() may be unavailable.
                                    // Try to add cert header; if not available, return without it.
                                    // The next query call will attach the valid proof.
                                    if let Some(cert) = data_certificate() {
                                        add_v2_certificate_header(
                                            &cert, &mut resp, &witness, &expr_path,
                                        );
                                    }
                                    resp
                                }
                                None => error_response(
                                    500,
                                    "Internal Server Error: NotModified but no cached asset found",
                                ),
                            }
                        });
                    }
                    router::HandlerResult::Response(response) => {
                        // Handler produced a new response — proceed with the
                        // standard certification pipeline below. We use the
                        // response from the HandlerResultFn directly (middleware
                        // has already been bypassed for result handlers).
                        return certify_dynamic_response_with_ttl(
                            response,
                            &path,
                            None,
                            cert_mode,
                            Some(&req),
                            route_ttl,
                        );
                    }
                }
            }

            // Standard path: call handler through middleware chain, then certify.
            let response =
                root_route_node.execute_with_middleware(&path, handler, req.clone(), params);
            certify_dynamic_response_with_ttl(
                response,
                &path,
                None,
                cert_mode,
                Some(&req),
                route_ttl,
            )
        }
        RouteResult::MethodNotAllowed(allowed) => method_not_allowed(&allowed),
        RouteResult::NotFound => {
            // Check if the canonical 404 entry already has a valid cached
            // response. If so, skip re-execution and serve directly.
            let cached_valid = ASSET_ROUTER.with_borrow(|asset_router| {
                if let Some(asset) = asset_router.get_asset(NOT_FOUND_CANONICAL_PATH) {
                    if asset.is_dynamic() {
                        let is_expired = if asset.ttl.is_some() {
                            asset.is_expired(ic_cdk::api::time())
                        } else {
                            let effective_ttl = ROUTER_CONFIG.with(|c| {
                                c.borrow()
                                    .cache_config
                                    .effective_ttl(NOT_FOUND_CANONICAL_PATH)
                            });
                            if let Some(ttl) = effective_ttl {
                                let now_ns = ic_cdk::api::time();
                                let expiry_ns =
                                    asset.certified_at.saturating_add(ttl.as_nanos() as u64);
                                now_ns >= expiry_ns
                            } else {
                                false
                            }
                        };
                        !is_expired
                    } else {
                        true // Static not-found asset is always valid
                    }
                } else {
                    false
                }
            });

            if cached_valid {
                // Already certified and not expired — serve from asset router.
                debug_log!("not-found canonical entry still valid, serving from cache");
                return ASSET_ROUTER.with_borrow(|asset_router| {
                    let canonical_req =
                        HttpRequest::get(NOT_FOUND_CANONICAL_PATH.to_string()).build();
                    match asset_router.serve_asset(&canonical_req) {
                        Some((resp, _witness, _expr_path)) => resp,
                        None => error_response(
                            500,
                            "Internal Server Error: cached not-found entry missing from asset router",
                        ),
                    }
                });
            }

            // Execute the not-found handler and certify at the canonical path.
            let response = if let Some(response) =
                root_route_node.execute_not_found_with_middleware(&path, req)
            {
                response
            } else {
                HttpResponse::not_found(
                    b"Not Found",
                    vec![("Content-Type".into(), "text/plain".into())],
                )
                .build()
            };
            certify_dynamic_response_inner(
                response,
                NOT_FOUND_CANONICAL_PATH,
                Some("/".to_string()),
                certification::CertificationMode::response_only(),
                None,
            )
        }
    }
}

// Test coverage audit (Session 7, Spec 5.5):
//
// Covered:
//   - Malformed URL → 400 response (both http_request and http_request_update)
//   - Handler without content-type doesn't panic
//   - extract_content_type: JSON, HTML, missing (fallback to octet-stream), case-insensitive
//
// No significant gaps for unit-testable code. IC runtime-dependent paths
// (certification, asset serving, TTL upgrade, NotModified flow) require PocketIC
// E2E tests (spec 5.7).
#[cfg(test)]
mod tests {
    use super::*;
    use ic_http_certification::Method;
    use router::{NodeType, RouteNode, RouteParams};

    fn noop_handler(_: HttpRequest, _: RouteParams) -> HttpResponse<'static> {
        HttpResponse::builder()
            .with_status_code(StatusCode::OK)
            .with_body(b"ok" as &[u8])
            .build()
    }

    fn setup_router() -> RouteNode {
        let mut root = RouteNode::new(NodeType::Static("".into()));
        root.insert("/", Method::GET, noop_handler);
        root.insert("/*", Method::GET, noop_handler);
        root
    }

    // ---- 1.3.5: malformed URL returns 400 (not a trap) ----

    #[test]
    fn http_request_malformed_url_returns_400() {
        let root = setup_router();
        // Construct a request with a URL that will fail `get_path()` parsing.
        // A bare NUL byte in the URL makes the URI parser fail.
        let req = HttpRequest::builder()
            .with_method(Method::GET)
            .with_url("http://[::bad")
            .build();
        let opts = HttpRequestOptions { certify: false };
        let response = http_request(req, &root, opts);
        assert_eq!(response.status_code(), StatusCode::BAD_REQUEST);
        assert!(std::str::from_utf8(response.body())
            .unwrap()
            .contains("malformed URL"));
    }

    #[test]
    fn http_request_update_malformed_url_returns_400() {
        let root = setup_router();
        let req = HttpRequest::builder()
            .with_method(Method::GET)
            .with_url("http://[::bad")
            .build();
        let response = http_request_update(req, &root);
        assert_eq!(response.status_code(), StatusCode::BAD_REQUEST);
        assert!(std::str::from_utf8(response.body())
            .unwrap()
            .contains("malformed URL"));
    }

    // ---- 1.3.6: missing content-type in handler response doesn't trap ----

    fn handler_no_content_type(_: HttpRequest, _: RouteParams) -> HttpResponse<'static> {
        // Response with no content-type header — should not cause the library to trap.
        HttpResponse::builder()
            .with_status_code(StatusCode::OK)
            .with_body(b"no content-type" as &[u8])
            .build()
    }

    #[test]
    fn handler_without_content_type_does_not_trap() {
        // This test verifies that a handler returning a response without a
        // content-type header does not cause a panic. The http_request_update
        // function calls IC runtime APIs (certify_assets, certified_data_set)
        // that are unavailable in unit tests, so we test the handler directly
        // and verify the router dispatch path up to the handler call.
        let mut root = RouteNode::new(NodeType::Static("".into()));
        root.insert("/no-ct", Method::GET, handler_no_content_type);

        // Verify the route matches and the handler runs without panic.
        let req = HttpRequest::builder()
            .with_method(Method::GET)
            .with_url("/no-ct")
            .build();
        match root.resolve("/no-ct", &Method::GET) {
            RouteResult::Found(handler, params, _, _) => {
                let response = handler(req, params);
                assert_eq!(response.status_code(), StatusCode::OK);
                assert_eq!(response.body(), b"no content-type");
                // No content-type header present — and no panic occurred.
                assert!(response
                    .headers()
                    .iter()
                    .all(|(name, _): &(String, String)| name.to_lowercase() != "content-type"));
            }
            _ => panic!("expected Found for GET /no-ct"),
        }
    }

    // ---- 1.2: handler-controlled response metadata ----

    #[test]
    fn extract_content_type_json() {
        let response = HttpResponse::builder()
            .with_status_code(StatusCode::OK)
            .with_headers(vec![(
                "content-type".to_string(),
                "application/json".to_string(),
            )])
            .with_body(b"{}" as &[u8])
            .build();
        assert_eq!(extract_content_type(&response), "application/json");
    }

    #[test]
    fn extract_content_type_html() {
        let response = HttpResponse::builder()
            .with_status_code(StatusCode::OK)
            .with_headers(vec![("Content-Type".to_string(), "text/html".to_string())])
            .with_body(b"<h1>hi</h1>" as &[u8])
            .build();
        assert_eq!(extract_content_type(&response), "text/html");
    }

    #[test]
    fn extract_content_type_missing_falls_back() {
        let response = HttpResponse::builder()
            .with_status_code(StatusCode::OK)
            .with_body(b"raw bytes" as &[u8])
            .build();
        assert_eq!(extract_content_type(&response), "application/octet-stream");
    }

    #[test]
    fn extract_content_type_case_insensitive() {
        let response = HttpResponse::builder()
            .with_status_code(StatusCode::OK)
            .with_headers(vec![("CONTENT-TYPE".to_string(), "text/plain".to_string())])
            .with_body(b"hello" as &[u8])
            .build();
        assert_eq!(extract_content_type(&response), "text/plain");
    }
}