majordomus_cli/http/

router.rs

//! Routing and binding, transport-neutral: a request in, a response out.
//!
//! The router names no surface. It asks [`super::surfaces::Served`] — the web topology this
//! process resolved, narrowed to what it can answer — who owns a path, and dispatches to
//! what that surface bound. A route under `/api/v1/` is a capability with an HTTP exposure;
//! `/`, `/openapi.json`, `/swagger`, `/cockpit` and `/mcp` are routes the executable answers
//! itself; `/docs/` and every generated report are directories a producer wrote. All of them
//! are declared once, in `crate::web::discover`, and reach the router, the home page, the
//! `web.surfaces` capability and the publication from there.

use std::sync::Arc;

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};

use crate::capability::{CapabilityError, CaseContext, Context, HttpMethod};
use crate::cockpit::Cockpit;
use crate::live::{IntoLive, Live, Memo};
use crate::ui::Ui;
use crate::web::discover::Runtime;
use crate::web::home;

use super::events;
use super::mcp::McpEndpoint;
use super::surfaces::{Bound, Native, Served};
use super::{openapi, swagger};

/// A request as the router sees it: method, path without query, decoded query pairs,
/// headers, and the body.
#[derive(Debug, Clone)]
pub struct Request {
    /// `GET`, `POST`, ... as received (a `HEAD` arrives as `GET`).
    pub method: String,
    /// The path without the query string.
    pub path: String,
    /// The query pairs, percent-decoded, in order.
    pub query: Vec<(String, String)>,
    /// Header names and values as received; looked up case-insensitively.
    pub headers: Vec<(String, String)>,
    /// The body, raw.
    pub body: Vec<u8>,
    /// The address the request came from, when it came over a socket. A request built in
    /// this process (a test, the Cockpit composing a call) has none, and is this machine's.
    pub remote: Option<std::net::IpAddr>,
}

impl Request {
    /// Split a request target (`/api/v1/objects?kind=rule`) into path and decoded pairs.
    ///
    /// ```
    /// use majordomus_cli::http::Request;
    /// let r = Request::parse_target("GET", "/api/v1/search?query=Git%20is&limit=2", vec![]);
    /// assert_eq!(r.path, "/api/v1/search");
    /// assert_eq!(r.query, vec![("query".to_string(), "Git is".to_string()), ("limit".to_string(), "2".to_string())]);
    /// ```
    pub fn parse_target(method: &str, target: &str, body: Vec<u8>) -> Self {
        let (path, query) = match target.split_once('?') {
            Some((p, q)) => (p.to_string(), q),
            None => (target.to_string(), ""),
        };
        let query = query
            .split('&')
            .filter(|s| !s.is_empty())
            .map(|pair| {
                let (k, v) = pair.split_once('=').unwrap_or((pair, ""));
                (percent_decode(k), percent_decode(v))
            })
            .collect();
        Request {
            method: method.to_string(),
            path,
            query,
            headers: Vec::new(),
            body,
            remote: None,
        }
    }

    /// The request that carries `input` to a capability's route the way the binding says:
    /// `GET` puts every top-level property that is not `null` on the query string (a
    /// scalar as its text, anything else as JSON), `POST` sends the input as the body.
    /// The inverse of the router's binding, so a benchmark case reaches the route as a
    /// client would send it.
    ///
    /// ```
    /// use majordomus_cli::capability::HttpMethod;
    /// use majordomus_cli::http::Request;
    /// use serde_json::json;
    /// let r = Request::bind(HttpMethod::Get, "/api/v1/search", &json!({ "query": "a b", "limit": 2, "kind": null }));
    /// assert_eq!(r.path, "/api/v1/search");
    /// assert_eq!(r.query, vec![("query".to_string(), "a b".to_string()), ("limit".to_string(), "2".to_string())]);
    /// let p = Request::bind(HttpMethod::Post, "/api/v1/peers/announce", &json!({ "intent": "x" }));
    /// assert_eq!(p.body, br#"{"intent":"x"}"#);
    /// ```
    pub fn bind(method: HttpMethod, path: &str, input: &Value) -> Self {
        match method {
            HttpMethod::Get => Request {
                method: "GET".into(),
                path: path.into(),
                query: input
                    .as_object()
                    .map(|m| {
                        m.iter()
                            .filter(|(_, v)| !v.is_null())
                            .map(|(k, v)| {
                                let text = match v {
                                    Value::String(s) => s.clone(),
                                    other => other.to_string(),
                                };
                                (k.clone(), text)
                            })
                            .collect()
                    })
                    .unwrap_or_default(),
                headers: Vec::new(),
                body: Vec::new(),
                remote: None,
            },
            HttpMethod::Post => Request {
                method: "POST".into(),
                path: path.into(),
                query: Vec::new(),
                headers: Vec::new(),
                body: input.to_string().into_bytes(),
                remote: None,
            },
        }
    }

    /// The request target this request would be sent as: the path with the query string,
    /// percent-encoded.
    ///
    /// ```
    /// use majordomus_cli::capability::HttpMethod;
    /// use majordomus_cli::http::Request;
    /// let r = Request::bind(HttpMethod::Get, "/api/v1/search", &serde_json::json!({ "query": "a b&c" }));
    /// assert_eq!(r.target(), "/api/v1/search?query=a%20b%26c");
    /// ```
    pub fn target(&self) -> String {
        if self.query.is_empty() {
            return self.path.clone();
        }
        let pairs: Vec<String> = self
            .query
            .iter()
            .map(|(k, v)| format!("{}={}", percent_encode(k), percent_encode(v)))
            .collect();
        format!("{}?{}", self.path, pairs.join("&"))
    }

    /// The same request with its headers.
    pub fn with_headers(mut self, headers: Vec<(String, String)>) -> Self {
        self.headers = headers;
        self
    }

    /// The same request, as having come from `address`.
    ///
    /// ```
    /// use majordomus_cli::http::Request;
    /// let r = Request::parse_target("GET", "/", vec![]).with_remote(Some("10.0.0.2".parse().unwrap()));
    /// assert_eq!(r.remote, Some("10.0.0.2".parse().unwrap()));
    /// ```
    pub fn with_remote(mut self, address: Option<std::net::IpAddr>) -> Self {
        self.remote = address;
        self
    }

    /// Did this request come from another host?
    ///
    /// Loopback is this machine, in either family and in the IPv4-mapped IPv6 form a
    /// dual-stack socket reports. A request with no address was built in this process.
    ///
    /// ```
    /// use majordomus_cli::http::Request;
    /// let r = |a: &str| Request::parse_target("POST", "/", vec![]).with_remote(Some(a.parse().unwrap()));
    /// assert!(!r("127.0.0.1").is_remote());
    /// assert!(!r("::1").is_remote());
    /// assert!(!r("::ffff:127.0.0.1").is_remote());
    /// assert!(r("192.168.100.30").is_remote());
    /// assert!(r("100.92.246.32").is_remote());
    /// assert!(r("::ffff:10.0.0.2").is_remote());
    /// assert!(!Request::parse_target("POST", "/", vec![]).is_remote());
    /// ```
    pub fn is_remote(&self) -> bool {
        self.remote
            .is_some_and(|ip| !ip.to_canonical().is_loopback())
    }

    /// A header value, by case-insensitive name.
    ///
    /// ```
    /// use majordomus_cli::http::Request;
    /// let r = Request::parse_target("POST", "/mcp", vec![])
    ///     .with_headers(vec![("Mcp-Session-Id".into(), "abc".into())]);
    /// assert_eq!(r.header("mcp-session-id"), Some("abc"));
    /// assert_eq!(r.header("x-none"), None);
    /// ```
    pub fn header(&self, name: &str) -> Option<&str> {
        self.headers
            .iter()
            .find(|(k, _)| k.eq_ignore_ascii_case(name))
            .map(|(_, v)| v.as_str())
    }
}

/// What a response carries. Text for everything this projection computes; bytes for a file
/// it serves from disk, which is not always UTF-8 and must not be repaired into it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Body {
    /// A string this process produced.
    Text(String),
    /// Bytes read from somewhere else, passed through unchanged.
    Bytes(Vec<u8>),
}

impl Body {
    /// The bytes on the wire.
    pub fn as_bytes(&self) -> &[u8] {
        match self {
            Body::Text(t) => t.as_bytes(),
            Body::Bytes(b) => b,
        }
    }

    /// How many bytes it is.
    pub fn len(&self) -> usize {
        self.as_bytes().len()
    }

    /// Is it empty?
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// The body as text: borrowed when it is text, and lossy when it is not, which only a
    /// diagnostic or a test ever asks for.
    ///
    /// ```
    /// use majordomus_cli::http::router::Body;
    /// assert_eq!(Body::Text("a".into()).text(), "a");
    /// assert_eq!(Body::Bytes(vec![0xff]).text(), "\u{fffd}");
    /// ```
    pub fn text(&self) -> std::borrow::Cow<'_, str> {
        match self {
            Body::Text(t) => std::borrow::Cow::Borrowed(t),
            Body::Bytes(b) => String::from_utf8_lossy(b),
        }
    }
}

impl From<String> for Body {
    fn from(value: String) -> Self {
        Body::Text(value)
    }
}

impl From<&str> for Body {
    fn from(value: &str) -> Self {
        Body::Text(value.to_string())
    }
}

impl From<Vec<u8>> for Body {
    fn from(value: Vec<u8>) -> Self {
        Body::Bytes(value)
    }
}

impl PartialEq<str> for Body {
    fn eq(&self, other: &str) -> bool {
        self.as_bytes() == other.as_bytes()
    }
}

impl PartialEq<&str> for Body {
    fn eq(&self, other: &&str) -> bool {
        self.as_bytes() == other.as_bytes()
    }
}

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

#[derive(Debug, Clone, PartialEq, Eq)]
/// A response as the router produces it; the server adds the wire.
pub struct Response {
    /// The HTTP status.
    pub status: u16,
    /// The `Content-Type` value.
    pub content_type: &'static str,
    /// The body.
    pub body: Body,
    /// Further headers (`Mcp-Session-Id`); the server adds `Content-Length` and `Cache-Control`.
    pub headers: Vec<(String, String)>,
}

impl Response {
    /// A response with no further headers.
    pub fn new(status: u16, content_type: &'static str, body: impl Into<Body>) -> Self {
        Response {
            status,
            content_type,
            body: body.into(),
            headers: Vec::new(),
        }
    }

    /// The same response with one more header.
    pub fn with_header(mut self, name: &str, value: impl Into<String>) -> Self {
        self.headers.push((name.to_string(), value.into()));
        self
    }

    /// The JSON error body every failure of the projection uses.
    pub fn error(status: u16, code: &str, message: &str) -> Self {
        error_response(status, code, message)
    }
}

/// The body of every error response.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ErrorBody {
    /// The one error.
    pub error: ErrorDetail,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
/// What went wrong, as the HTTP projection names it.
pub struct ErrorDetail {
    /// What kind of failure it is: `invalid_input`, `not_found`, `method_not_allowed`,
    /// `refused`, `forbidden`, `too_large`, `unavailable` (a surface whose producer has not
    /// run) or `internal`.
    pub code: String,
    /// The reason, for a person.
    pub message: String,
}

#[derive(Clone)]
/// Routes requests to the surfaces this process serves. Cheap to clone: every worker
/// thread holds one, and the resolution behind it is shared.
pub struct Router {
    /// The repository as it is now. Every request takes the current context from here
    /// before it is answered, which is what keeps a server that has run for hours from
    /// serving the repository it started in.
    live: Arc<Live>,
    version: &'static str,
    /// The OpenAPI document, rendered once per generation of the repository: it is a
    /// projection of the registry, and the registry is a projection of the index.
    openapi: Arc<Memo<Result<String, String>>>,
    /// MCP over HTTP at the mount its surface declares, when this router serves a shared
    /// server.
    mcp: Option<Arc<McpEndpoint>>,
    /// The Cockpit, when the process located a distribution to serve its assets from.
    cockpit: Option<Arc<Cockpit>>,
    ui: Option<Arc<Ui>>,
    /// The resolved surfaces and their handlers, and the context narrowed to them. Built
    /// on first use, because the builder learns what this process offers after `new`, and
    /// again for each generation, because the topology is read out of the repository.
    served: Arc<Memo<Result<Resolution, String>>>,
    /// Which git repository the served checkout belongs to, asked once: the index route
    /// answers it on every probe, and a probe must not cost a subprocess.
    git: Arc<std::sync::OnceLock<Option<crate::repository::GitIdentity>>>,
}

/// Which checkout a router is answering for, read from the repository model: the identity
/// the home page, its JSON projection and the API shell all name, so that a page fetched
/// from one server cannot be mistaken for another's (I1031). None of it is a path.
struct ServedCheckout {
    repository: String,
    id: String,
    git: Option<crate::repository::GitIdentity>,
    branch: Option<String>,
    head: Option<String>,
}

impl ServedCheckout {
    fn as_home(&self) -> home::Checkout<'_> {
        home::Checkout {
            id: &self.id,
            git_repository: self.git.as_ref().map(|g| g.id.as_str()),
            linked: self.git.as_ref().is_some_and(|g| g.linked),
            branch: self.branch.as_deref(),
            head: self.head.as_deref(),
        }
    }
}

/// What one router serves: the bound surfaces, and the context every capability call is
/// given so that `web.surfaces` answers with what this process actually serves.
struct Resolution {
    served: Served,
    ctx: Arc<Context>,
}

/// The surfaces a router serves, held for as long as its reader needs them.
///
/// A resolution belongs to one generation of the repository and is replaced when the
/// repository moves under the process, so it cannot be lent out as a bare reference tied
/// to the router. This holds the generation alive while the caller reads it, and derefs to
/// the surfaces themselves so that a caller writes `router.served()?.summary(url)` exactly
/// as it did when the index was immutable.
///
/// ```
/// # use majordomus_cli::http::Router;
/// # use majordomus_cli::http::router::ServedRef;
/// # fn example(router: &Router) {
/// // the surfaces, read through the generation that resolved them
/// let served: ServedRef = router.served().expect("a topology that resolves");
/// assert!(served.topology().surfaces.iter().any(|s| s.id == "home"));
/// # }
/// ```
pub struct ServedRef {
    resolution: Arc<Result<Resolution, String>>,
}

impl std::ops::Deref for ServedRef {
    type Target = Served;

    fn deref(&self) -> &Served {
        match &*self.resolution {
            Ok(resolution) => &resolution.served,
            // `served()` is the only constructor and it builds one only from `Ok`
            Err(reason) => unreachable!("a resolved surface set that did not resolve: {reason}"),
        }
    }
}

impl std::fmt::Debug for ServedRef {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ServedRef").finish()
    }
}

impl Router {
    /// A router over a view of the repository, without `/mcp` and without the Cockpit.
    ///
    /// `live` is either the [`Live`] the shared server follows the repository with or a
    /// plain [`Arc<Context>`], which becomes a pinned view: a one-shot process and a
    /// benchmark have nothing to follow and pay nothing to prove it.
    pub fn new(live: impl IntoLive, version: &'static str) -> Self {
        crate::perf::Counters::bump(&crate::perf::COUNTERS.http_projection_builds);
        Router {
            live: live.into_live(),
            version,
            openapi: Arc::new(Memo::default()),
            mcp: None,
            cockpit: None,
            ui: None,
            served: Arc::new(Memo::default()),
            git: Arc::new(std::sync::OnceLock::new()),
        }
    }

    /// The same router, serving the Cockpit's pages with its assets read from `share_dir`.
    pub fn with_cockpit(mut self, share_dir: Option<&std::path::Path>) -> Self {
        self.cockpit = Some(Arc::new(Cockpit::new(
            Arc::clone(&self.live),
            self.version,
            share_dir,
        )));
        self
    }

    /// The same router, serving the UI's pages (ADR 0135) with its assets read from
    /// `share_dir`. Without a distribution the screens are still complete HTML, unstyled;
    /// either way the UI becomes one of the surfaces the topology says this process serves.
    ///
    /// ```
    /// # use majordomus_cli::http::Router;
    /// # fn example(router: Router) {
    /// let router = router.with_ui(None);
    /// let served = router.served().expect("a topology that resolves");
    /// assert!(served.topology().surfaces.iter().any(|s| s.id == majordomus_cli::ui::SURFACE));
    /// # }
    /// ```
    pub fn with_ui(mut self, share_dir: Option<&std::path::Path>) -> Self {
        self.ui = Some(Arc::new(Ui::new(
            Arc::clone(&self.live),
            self.version,
            share_dir,
        )));
        self
    }

    /// The same router, serving MCP over HTTP through `endpoint`.
    pub fn with_mcp(mut self, endpoint: Arc<McpEndpoint>) -> Self {
        self.mcp = Some(endpoint);
        self
    }

    /// What this process offers, as the topology's feature gates read it.
    fn runtime(&self) -> Runtime {
        Runtime {
            mcp: self.mcp.is_some(),
            cockpit: self.cockpit.is_some(),
            ui: self.ui.is_some(),
        }
    }

    /// The resolved surfaces, narrowed and validated once per generation of the
    /// repository.
    ///
    /// Once per *generation* and not once per process: the topology is discovered from the
    /// site's configuration and the generated web root, both of which are files in the
    /// repository, so a checkout that moved may serve a different set of surfaces.
    fn resolution(&self) -> Arc<Result<Resolution, String>> {
        self.resolution_of(self.live.view())
    }

    /// The resolution of the generation there is, without waiting for a reload: what a
    /// page of the UI is routed by (ADR 0142). The UI says itself when the repository has
    /// moved past what it shows; every other surface is routed by [`Router::resolution`].
    fn resolution_without_waiting(&self) -> Arc<Result<Resolution, String>> {
        self.resolution_of(self.live.view_without_waiting().0)
    }

    fn resolution_of(&self, view: crate::live::View) -> Arc<Result<Resolution, String>> {
        self.served.get_or_init(view.generation, || {
            let root = std::path::Path::new(&view.ctx.index.repository.root);
            Served::resolve(&view.ctx.web, root, self.runtime())
                .map(|served| Resolution {
                    ctx: Arc::new(view.ctx.with_web(served.shared())),
                    served,
                })
                // the reason alone: `served()` puts it back into the same error, and a
                // message that names its own kind twice reads as a bug in the tool
                .map_err(|e| match e {
                    crate::error::Error::InvalidSurface { reason, .. } => reason,
                    other => other.to_string(),
                })
        })
    }

    /// The surfaces this router serves, for a caller that wants to describe them: the
    /// server's startup line, and the tests.
    ///
    /// The answer is the resolution, not a fresh discovery — a router that could not
    /// resolve its topology never answered a request either, and says the same thing here
    /// that it says to a client.
    pub fn served(&self) -> crate::error::Result<ServedRef> {
        let resolution = self.resolution();
        match &*resolution {
            Ok(_) => Ok(ServedRef { resolution }),
            Err(reason) => Err(crate::error::Error::InvalidSurface {
                surface: "topology".into(),
                reason: reason.clone(),
            }),
        }
    }

    /// Does this request open the live channel, and may it?
    ///
    /// The server asks before it reads a body or writes a response, because an upgrade is
    /// the one thing a router cannot answer: it hands the socket over. `None` means the
    /// request is not for the live channel at all and is routed normally.
    pub fn websocket(&self, req: &Request) -> Option<Result<events::Accepted, Response>> {
        if req.path != events::PATH {
            return None;
        }
        if !super::ws::is_upgrade(req) {
            return None;
        }
        // the upgrade is answered before `handle`, so it is refused here for the reason
        // `handle` refuses every other request a DNS-rebinding page sends: otherwise a page
        // whose domain was made to resolve to this machine follows every execution
        if let Some(refusal) = Self::rebound(req) {
            return Some(Err(refusal));
        }
        // a process whose topology does not resolve serves nothing, the live channel
        // included: the same answer every other path gets
        let resolution = self.resolution();
        let ctx = match &*resolution {
            Ok(resolution) => &resolution.ctx,
            Err(reason) => return Some(Err(Response::error(500, "internal", reason))),
        };
        Some(events::accept(
            ctx.executions.store(),
            req,
            &snapshot_route(ctx),
        ))
    }

    fn openapi(&self) -> Response {
        let view = self.live.view();
        let rendered = self.openapi.get_or_init(view.generation, || {
            let cases = CaseContext {
                index: &view.ctx.index,
            };
            openapi::document(&view.ctx.registry, self.version, Some(&cases))
                .map(|d| openapi::render(&d))
        });
        match &*rendered {
            Ok(text) => Response::new(200, "application/json", text.clone()),
            Err(e) => error_response(500, "internal", e),
        }
    }

    /// Answer one request: the surface that owns its path, or nothing.
    ///
    /// A request that carries an `Origin` header came from a page in a browser. A browser
    /// cannot read a cross-origin response without the headers this server never sends,
    /// so a read is already contained; a request that changes something is not, and one
    /// from another origin is refused before it reaches a handler. A client that is not a
    /// browser sends no `Origin` and is unaffected.
    pub fn handle(&self, req: &Request) -> Response {
        if let Some(refusal) = Self::rebound(req) {
            return refusal;
        }
        if req.method != "GET" && req.method != "HEAD" {
            if let Some(refusal) = self.foreign_origin(req) {
                return refusal;
            }
        }
        // a page of the UI is drawn from the generation there is and never waits for the next
        // one; every other request waits for the generation its caller saw
        let page = req.method == "GET"
            && (req.path == crate::ui::PREFIX
                || req.path.starts_with(&format!("{}/", crate::ui::PREFIX)));
        let held = if page {
            self.resolution_without_waiting()
        } else {
            self.resolution()
        };
        let resolution = match &*held {
            Ok(resolution) => resolution,
            Err(reason) => return error_response(500, "internal", reason),
        };
        let Some((surface, bound)) = resolution.served.owner(&req.path) else {
            return error_response(
                404,
                "not_found",
                &format!(
                    "no surface owns {}; what this process serves is listed at / and at {}web/surfaces",
                    req.path,
                    crate::capability::model::HttpExposure::PREFIX
                ),
            );
        };
        // a surface owns its mount and everything under it, which is what a directory and a
        // prefix want and what a single route does not: `/swagger/anything` is not the
        // Swagger UI, and answering it as though it were would invent a route nothing
        // declared. The surfaces that answer one path say so here, once.
        let exact = req.path == surface.mount.as_str() || req.path == surface.mount.prefix();
        // the home page is not among them: its mount is the root, which owns every path
        // nothing else claims, and it answers those with a 404 that names what is served
        let single_path = matches!(
            bound,
            Bound::Route(Native::OpenApi | Native::Swagger | Native::Mcp | Native::Events)
        );
        if single_path && !exact {
            return error_response(
                404,
                "not_found",
                &format!(
                    "{} is the whole of the '{}' surface; nothing is served under it. What this process serves is listed at / and at {}web/surfaces",
                    surface.mount,
                    surface.id,
                    crate::capability::model::HttpExposure::PREFIX
                ),
            );
        }
        match bound {
            Bound::Directory(files) => {
                if req.method != "GET" {
                    return error_response(
                        405,
                        "method_not_allowed",
                        &format!(
                            "{} is a generated directory; it is read with GET",
                            surface.mount
                        ),
                    );
                }
                files.respond(&req.path)
            }
            Bound::Route(Native::Home) => self.home(req, resolution),
            Bound::Route(Native::OpenApi) => self.openapi(),
            Bound::Route(Native::Swagger) => {
                let checkout = self.checkout(&resolution.ctx);
                swagger_response(&checkout.as_home().line(&checkout.repository))
            }
            Bound::Route(Native::Mcp) => match &self.mcp {
                Some(endpoint) => endpoint.handle(req),
                None => error_response(
                    500,
                    "internal",
                    "the MCP surface is served with no endpoint behind it",
                ),
            },
            // the upgrade itself never reaches here: the server answers it before routing,
            // because handing the socket over is something only the server can do. What
            // reaches here is a request that did not ask to be upgraded, and the reply says
            // what this path is and where the same events are readable over HTTP.
            Bound::Route(Native::Events) => match events::accept(
                resolution.ctx.executions.store(),
                req,
                &snapshot_route(&resolution.ctx),
            ) {
                Ok(_) => Response::error(
                    500,
                    "internal",
                    "a WebSocket upgrade reached the router; the server answers it before routing",
                ),
                Err(response) => response,
            },
            Bound::Route(Native::Cockpit) => match &self.cockpit {
                Some(cockpit) => cockpit.handle(req),
                None => error_response(
                    500,
                    "internal",
                    "the Cockpit surface is served with no Cockpit behind it",
                ),
            },
            Bound::Route(Native::Ui) => match &self.ui {
                Some(ui) => {
                    Ui::warm_once(ui);
                    ui.handle(req)
                }
                None => error_response(
                    500,
                    "internal",
                    "the UI surface is served with no UI behind it",
                ),
            },
            Bound::Route(Native::Api) => {
                let prefix = crate::capability::model::HttpExposure::PREFIX;
                if req.path == prefix || req.path == prefix.trim_end_matches('/') {
                    return self.routes(&resolution.ctx);
                }
                self.capability(req, &resolution.ctx)
            }
        }
    }

    /// `/`: the home page for a browser, the same topology as JSON for everything else.
    ///
    /// The root surface owns every path nothing else claims, which is how a request for a
    /// path no surface declares reaches the most useful 404 this server can give: one from
    /// a process that knows what it does serve.
    fn home(&self, req: &Request, resolution: &Resolution) -> Response {
        if req.path != "/" {
            return error_response(
                404,
                "not_found",
                &format!(
                    "no surface owns {}; what this process serves is listed at / and at {}web/surfaces",
                    req.path,
                    crate::capability::model::HttpExposure::PREFIX
                ),
            );
        }
        if req.method != "GET" {
            return error_response(405, "method_not_allowed", "the home page is read with GET");
        }
        let topology = resolution.served.topology();
        let checkout = self.checkout(&resolution.ctx);
        if prefers_html(req) {
            let identity = home::Identity {
                version: self.version,
                summary: crate::about::SUMMARY,
                repository: repository_name(&resolution.ctx.index.repository.root),
                revision: match &resolution.ctx.index.repository.git {
                    crate::git::GitState::Available(info) => info.head.as_deref(),
                    crate::git::GitState::Unavailable { .. } => None,
                },
                capabilities: resolution.ctx.registry.summary().total,
                checkout: checkout.as_home(),
            };
            let ready = |id: &str| {
                if resolution.served.ready(id) {
                    home::Availability::Ready
                } else {
                    home::Availability::NotBuilt
                }
            };
            return Response::new(
                200,
                "text/html; charset=utf-8",
                home::page(topology, &identity, &ready),
            );
        }
        let surfaces: Vec<Value> = topology
            .surfaces
            .iter()
            .map(|s| {
                json!({
                    "id": s.id,
                    "title": s.title,
                    "path": s.mount.as_str(),
                    "category": s.category.to_string(),
                    "visibility": s.visibility.to_string(),
                    "kind": s.kind.to_string(),
                    "ready": resolution.served.ready(&s.id),
                })
            })
            .collect();
        let git = checkout.git.as_ref();
        // whether this process is still the checkout's server. A server whose lease was
        // taken over keeps serving the peers it already has, so it goes on answering here,
        // and every other field is as true of it as of the current server. This is the one
        // that tells them apart; `lease::probe` reads it under the same name, which is why
        // the name is the constant and not a literal.
        let mut index = json!({
                "name": "majordomus",
                "version": self.version,
                // the commit this executable was built from, the value `health.live` and
                // `health.ready` answer under the same names: a checkout's server that
                // answers from another commit than the checkout's HEAD is serving another
                // tree, and a reader can only say so if the server names its own
                "commit": crate::COMMIT,
                "dirty": crate::DIRTY,
                // and whether that code still exists: null while the file this process was
                // started from is the file on disk, the reason once it has been replaced —
                // the same answer `health.ready` gives, so a client reading only this
                // document can tell a current server from one serving yesterday's code
                "stale": crate::lease::serving_replaced_code(),
                "description": crate::about::SUMMARY,
                "reference": crate::about::REFERENCE_URL,
                // the repository's name and not its path: this answer is served to whoever
                // can reach the socket, and where the checkout sits on the host is of no
                // use to them and of some use to somebody else. The HTML page has always
                // withheld it; the two projections of one surface now agree.
                "repository": repository_name(&resolution.ctx.index.repository.root),
                // which repository, without saying where it is: a second process that
                // already knows the root computes the same value and knows this server is
                // its own (crate::repository::identity)
                "repository_id": checkout.id,
                // and which git repository that checkout belongs to: one value for every
                // worktree of it, so that a reader can tell two servers of one repository
                // from the servers of two (crate::repository::git_identity)
                "git_repository_id": git.map(|g| g.id.clone()),
                "linked_worktree": git.is_some_and(|g| g.linked),
                // the branch and commit the served answers were read from, as the index
                // read them: two servers of one repository can serve two trees (I1031)
                "branch": checkout.branch,
                "head": checkout.head,
                "surfaces": surfaces,
        });
        index[crate::lease::LEASEHOLDER_KEY] = json!(!crate::lease::was_lost());
        json_response(200, &index)
    }

    /// Which checkout this router answers for, from the repository model the context was
    /// built from: the checkout's identity, its git repository's, the branch and commit the
    /// index read. No second inspection: the identity is the repository module's, asked
    /// once per process, and the branch and commit are the index's own.
    fn checkout(&self, ctx: &Context) -> ServedCheckout {
        let root = std::path::Path::new(&ctx.index.repository.root);
        let git = self
            .git
            .get_or_init(|| crate::repository::git_identity(root))
            .clone();
        let (branch, head) = match &ctx.index.repository.git {
            crate::git::GitState::Available(info) => (info.branch.clone(), info.head.clone()),
            crate::git::GitState::Unavailable { .. } => (None, None),
        };
        ServedCheckout {
            repository: repository_name(&ctx.index.repository.root).to_string(),
            id: crate::repository::identity(root),
            git,
            branch,
            head,
        }
    }

    /// The refusal for a state-changing request from another origin, when there is one.
    /// The allowed origins are this server's own: whatever host the request was addressed
    /// to. Nothing else is configured, because nothing else should be able to change this
    /// process from a browser.
    fn foreign_origin(&self, req: &Request) -> Option<Response> {
        let origin = req.header("origin")?;
        // `null` is what a sandboxed frame or a `file://` page sends; neither is this server
        let host = req.header("host").unwrap_or_default();
        let allowed = [format!("http://{host}"), format!("https://{host}")];
        // The origin matching the Host header is only this server's own origin when the Host
        // cannot be chosen by a page: a DNS-rebinding page names its own domain in both and
        // matches. So the request must also be addressed by an IP literal or `localhost`,
        // which no rebinding domain is.
        if allowed.iter().any(|a| a == origin) && Self::host_is_literal(host) {
            return None;
        }
        tracing::warn!(
            origin = %crate::redaction::redact_secrets(origin).text,
            method = %req.method,
            path = %crate::redaction::redact_secrets(&req.path).text,
            "a state-changing request from another origin was refused"
        );
        Some(error_response(
            403,
            "forbidden",
            &format!(
                "a {} from origin '{origin}' is refused: this server accepts a state-changing request from a browser only from its own origin",
                req.method
            ),
        ))
    }

    /// Whether a `Host` header names this machine by an address rather than by a domain a
    /// third party could point at it: an IPv4 or bracketed IPv6 literal, `localhost` or a
    /// `*.localhost` name, each with an optional port.
    /// The refusal for a request a DNS-rebinding page sent, when this is one.
    ///
    /// A page on another domain cannot read this server's answers, until its domain is made
    /// to resolve to this machine: then the browser on this machine sends the page's requests
    /// here, from loopback, naming the page's domain as the host. Nothing else sends a
    /// loopback request under a name that is neither an address nor `localhost`, so that
    /// request is refused before any surface answers it, reads included. A request from
    /// another host is judged by ADR 0126, and one that names no host is a program's.
    fn rebound(req: &Request) -> Option<Response> {
        let from_loopback = req.remote.is_some_and(|ip| ip.to_canonical().is_loopback());
        let host = req.header("host")?;
        if !from_loopback || Self::host_is_literal(host) {
            return None;
        }
        tracing::warn!(host = host, path = %req.path, "a loopback request under a foreign host name was refused");
        Some(error_response(
            403,
            "forbidden",
            &format!(
                "a request from this machine addressed to '{host}' is refused: this server answers loopback requests only under an address or `localhost`, so a page whose domain was made to resolve here reads nothing"
            ),
        ))
    }

    fn host_is_literal(host: &str) -> bool {
        let name = if let Some(rest) = host.strip_prefix('[') {
            match rest.split_once(']') {
                Some((v6, tail)) if tail.is_empty() || tail.starts_with(':') => {
                    return v6.parse::<std::net::Ipv6Addr>().is_ok();
                }
                _ => return false,
            }
        } else {
            host.rsplit_once(':').map_or(host, |(name, port)| {
                if port.parse::<u16>().is_ok() {
                    name
                } else {
                    host
                }
            })
        };
        name.parse::<std::net::Ipv4Addr>().is_ok()
            || name.eq_ignore_ascii_case("localhost")
            || name.to_ascii_lowercase().ends_with(".localhost")
    }

    /// The capability mount itself: every route under it, from the registry that declares
    /// them.
    ///
    /// It exists so that the surface the home page offers is a page a person can open
    /// rather than a prefix that answers 404, and it is the registry's own list rather
    /// than a second one — the schemas, the parameters and the examples stay in the
    /// OpenAPI document, which is generated from the same descriptors.
    fn routes(&self, ctx: &Arc<Context>) -> Response {
        // Ordered as routes, then serialised — the same order the Cockpit's table and the
        // OpenAPI document read in. The previous sort compared `Value::to_string()`, which
        // is the JSON encoding of the path, quotes included, and had no method tiebreak.
        let mut declared: Vec<_> = ctx
            .registry
            .iter()
            .filter_map(|c| c.exposure.http.as_ref().map(|http| (c, http)))
            .collect();
        declared.sort_by(|(a, ha), (b, hb)| {
            crate::order::natural_cmp(&ha.path, &hb.path)
                .then_with(|| crate::order::natural_cmp(ha.method.as_str(), hb.method.as_str()))
                .then_with(|| crate::order::natural_cmp(a.id.as_str(), b.id.as_str()))
        });
        let routes: Vec<Value> = declared
            .into_iter()
            .map(|(c, http)| {
                json!({
                    "method": http.method.as_str(),
                    "path": http.path,
                    "capability": c.id.as_str(),
                    "title": c.title,
                })
            })
            .collect();
        json_response(
            200,
            &json!({
                "description": "Every capability with an HTTP exposure, as the registry declares it.",
                "openapi": swagger::SPEC_PATH,
                "swagger": swagger::SWAGGER_PATH,
                "routes": routes,
            }),
        )
    }

    fn capability(&self, req: &Request, ctx: &Arc<Context>) -> Response {
        let Some(method) = HttpMethod::parse(&req.method) else {
            return error_response(
                405,
                "method_not_allowed",
                &format!("method {} is not served", req.method),
            );
        };
        let Some(c) = ctx.registry.by_http(method, &req.path) else {
            let other_method = [HttpMethod::Get, HttpMethod::Post]
                .into_iter()
                .filter(|m| *m != method)
                .any(|m| ctx.registry.by_http(m, &req.path).is_some());
            return if other_method {
                error_response(
                    405,
                    "method_not_allowed",
                    &format!(
                        "{} {} is not a route; another method is",
                        req.method, req.path
                    ),
                )
            } else {
                error_response(
                    404,
                    "not_found",
                    &format!(
                        "no route {} {}; the routes are listed at /openapi.json",
                        req.method, req.path
                    ),
                )
            };
        };
        if req.is_remote() && !c.execution.admits_remote() {
            let e = CapabilityError::remote(c.id.as_str());
            return error_response(403, e.code(), &e.to_string());
        }
        let input = match method {
            HttpMethod::Get => {
                let (props, _) = c.input.properties();
                let mut obj = serde_json::Map::new();
                for (k, raw) in &req.query {
                    let property = props
                        .iter()
                        .find(|(n, _)| n == k)
                        .map(|(_, s)| s.clone())
                        .unwrap_or(Value::Null);
                    match crate::capability::schema::coerce(&property, raw) {
                        Ok(v) => {
                            obj.insert(k.clone(), v);
                        }
                        Err(e) => {
                            return error_response(
                                400,
                                "invalid_input",
                                &format!("parameter '{k}': {e}"),
                            )
                        }
                    }
                }
                Value::Object(obj)
            }
            HttpMethod::Post => {
                if req.body.iter().all(u8::is_ascii_whitespace) {
                    json!({})
                } else {
                    match serde_json::from_slice::<Value>(&req.body) {
                        Ok(v) if v.is_object() => v,
                        Ok(_) => {
                            return error_response(
                                400,
                                "invalid_input",
                                "the body must be a JSON object",
                            )
                        }
                        Err(e) => {
                            return error_response(
                                400,
                                "invalid_input",
                                &format!("the body is not JSON: {e}"),
                            )
                        }
                    }
                }
            }
        };
        // one line per request is debug: a client that does not drain stderr must not be
        // able to wedge the workers on a full pipe at the default level
        tracing::debug!(capability_id = %c.id, route = %format!("{} {}", req.method, req.path), "http");
        match ctx.execute(c.id.as_str(), input) {
            Ok(v) => json_response(200, &v),
            // the word is the error's own, the same one an MCP tool result carries; only
            // the status is this transport's
            Err(e) => failed(&e),
        }
    }
}

/// A capability's error as an HTTP response: the status is this transport's, the code and
/// the message are the error's own.
fn failed(e: &CapabilityError) -> Response {
    let status = match e {
        CapabilityError::InvalidInput(_) => 400,
        CapabilityError::NotFound(_) => 404,
        CapabilityError::Refused(_) => 422,
        CapabilityError::Internal(_) => 500,
        CapabilityError::Forbidden(_) => 403,
    };
    let (CapabilityError::InvalidInput(m)
    | CapabilityError::NotFound(m)
    | CapabilityError::Refused(m)
    | CapabilityError::Internal(m)
    | CapabilityError::Forbidden(m)) = e;
    error_response(status, e.code(), m)
}

/// Does this request come from something that would rather have a page than a document?
/// Only an explicit `text/html` in `Accept` counts: a client that sends none, or `*/*`,
/// gets the JSON index, which is what every existing caller does.
///
/// ```
/// use majordomus_cli::http::{router::prefers_html, Request};
/// let plain = Request::parse_target("GET", "/", vec![]);
/// assert!(!prefers_html(&plain));
/// let browser = plain.clone().with_headers(vec![
///     ("Accept".into(), "text/html,application/xhtml+xml,*/*;q=0.8".into()),
/// ]);
/// assert!(prefers_html(&browser));
/// ```
pub fn prefers_html(req: &Request) -> bool {
    req.header("accept").is_some_and(|accept| {
        accept.split(',').any(|part| {
            part.split(';')
                .next()
                .is_some_and(|t| t.trim() == "text/html")
        })
    })
}

/// The repository's name: the last component of its root, which is what a person calls it.
/// The root itself is a filesystem path and is not put on a page anyone can reach.
fn repository_name(root: &str) -> &str {
    root.rsplit('/')
        .find(|s| !s.is_empty())
        .unwrap_or("repository")
}

/// The Swagger UI shell. `/swagger` and `/swagger/` both answer it: the page loads its
/// distribution and the document by absolute path, so neither form can resolve wrongly.
/// `checkout` is the line naming the checkout that serves it, already escaped.
fn swagger_response(checkout: &str) -> Response {
    Response::new(200, "text/html; charset=utf-8", swagger::page_for(checkout))
        .with_header("Content-Security-Policy", swagger::csp())
        .with_header("X-Content-Type-Options", "nosniff")
        .with_header("Referrer-Policy", "no-referrer")
}

fn json_response(status: u16, v: &Value) -> Response {
    Response::new(
        status,
        "application/json",
        serde_json::to_string_pretty(v).unwrap_or_else(|_| v.to_string()),
    )
}

fn error_response(status: u16, code: &str, message: &str) -> Response {
    // an error often echoes what it was asked — a path, a parameter, an input — and what it
    // was asked may hold a credential; no answer of this server carries one back
    let body = ErrorBody {
        error: ErrorDetail {
            code: code.into(),
            message: crate::redaction::redact_secrets(message).text,
        },
    };
    Response::new(
        status,
        "application/json",
        serde_json::to_string_pretty(&body).unwrap_or_default(),
    )
}

/// Percent-encode everything but the unreserved characters of RFC 3986.
pub fn percent_encode(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
                out.push(b as char)
            }
            _ => out.push_str(&format!("%{b:02X}")),
        }
    }
    out
}

/// `%XX` and `+` decoding; a malformed escape is kept as it is.
pub fn percent_decode(s: &str) -> String {
    let bytes = s.as_bytes();
    let mut out = Vec::with_capacity(bytes.len());
    let mut i = 0;
    while i < bytes.len() {
        match bytes[i] {
            b'+' => out.push(b' '),
            b'%' if i + 2 < bytes.len() => {
                match u8::from_str_radix(
                    std::str::from_utf8(&bytes[i + 1..i + 3]).unwrap_or("zz"),
                    16,
                ) {
                    Ok(b) => {
                        out.push(b);
                        i += 2;
                    }
                    Err(_) => out.push(b'%'),
                }
            }
            b => out.push(b),
        }
        i += 1;
    }
    String::from_utf8_lossy(&out).into_owned()
}

/// The route of `executions.get` as the registry declares it: where the live channel tells
/// a client to read a value too large for one frame.
fn snapshot_route(ctx: &Context) -> String {
    ctx.registry
        .get("executions.get")
        .and_then(|c| c.exposure.http.as_ref())
        .map(|h| h.path.clone())
        .unwrap_or_default()
}

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

    /// A topology resolved while the UI was there, answered after it is gone, says so
    /// rather than serving an empty page or another surface.
    #[test]
    fn a_ui_route_with_no_ui_behind_it_says_so() {
        let repo = crate::synthetic::SyntheticRepository::new(crate::synthetic::Shape::default())
            .expect("a synthetic repository");
        let mut router = Router::new(repo.context().expect("a context"), "test").with_ui(None);
        assert!(
            router.served().is_ok(),
            "the topology resolves with the UI in it"
        );
        router.ui = None;
        let r = router.handle(&Request::parse_target("GET", crate::ui::PREFIX, Vec::new()));
        assert_eq!(r.status, 500, "{}", r.body.text());
        assert!(
            r.body.text().contains("no UI behind it"),
            "{}",
            r.body.text()
        );
    }

    #[test]
    fn every_capability_error_has_its_status_and_keeps_its_word() {
        for (e, status, code) in [
            (
                CapabilityError::InvalidInput("m".into()),
                400,
                "invalid_input",
            ),
            (CapabilityError::NotFound("m".into()), 404, "not_found"),
            (CapabilityError::Refused("m".into()), 422, "refused"),
            (CapabilityError::Internal("m".into()), 500, "internal"),
            (CapabilityError::remote("plan.transition"), 403, "forbidden"),
        ] {
            let r = failed(&e);
            assert_eq!(r.status, status, "{e:?}");
            let body: serde_json::Value = serde_json::from_str(&r.body.text()).unwrap();
            assert_eq!(body["error"]["code"], code, "{body}");
        }
        let body: serde_json::Value = serde_json::from_str(
            &failed(&CapabilityError::remote("plan.transition"))
                .body
                .text(),
        )
        .unwrap();
        assert!(body.to_string().contains("plan.transition"), "{body}");
    }

    /// The live channel is upgraded before `handle` is reached, so the DNS-rebinding guard
    /// `handle` applies must be applied to the upgrade as well: a page whose domain resolves
    /// here names that domain in both Host and Origin, which match, from loopback.
    #[test]
    fn a_rebound_page_cannot_open_the_live_channel() {
        let repo = crate::synthetic::SyntheticRepository::new(crate::synthetic::Shape::default())
            .expect("a synthetic repository");
        let router = Router::new(repo.context().expect("a context"), "test").with_ui(None);
        let upgrade = |host: &str| {
            Request::parse_target("GET", events::PATH, Vec::new())
                .with_headers(vec![
                    ("Upgrade".into(), "websocket".into()),
                    ("Connection".into(), "Upgrade".into()),
                    (
                        "Sec-WebSocket-Key".into(),
                        "dGhlIHNhbXBsZSBub25jZQ==".into(),
                    ),
                    ("Sec-WebSocket-Version".into(), "13".into()),
                    ("Host".into(), host.into()),
                    ("Origin".into(), format!("http://{host}")),
                ])
                .with_remote(Some("127.0.0.1".parse().unwrap()))
        };
        match router.websocket(&upgrade("rebound.example:8741")) {
            Some(Err(r)) => {
                assert_eq!(r.status, 403, "{}", r.body.text());
                assert!(
                    r.body.text().contains("rebound.example"),
                    "{}",
                    r.body.text()
                );
            }
            Some(Ok(_)) => panic!("a rebound page was handed the live channel"),
            None => panic!("an upgrade of the live channel was not recognised"),
        }
        assert!(
            matches!(router.websocket(&upgrade("127.0.0.1:8741")), Some(Ok(_))),
            "this server's own page still opens it"
        );
    }

    #[test]
    fn only_an_address_or_localhost_is_a_host_no_rebinding_domain_can_name() {
        for host in [
            "127.0.0.1",
            "127.0.0.1:8742",
            "192.168.1.20:8742",
            "[::1]:8742",
            "[::1]",
            "localhost",
            "LOCALHOST:80",
            "cockpit.localhost:8742",
        ] {
            assert!(Router::host_is_literal(host), "{host} names this machine");
        }
        for host in [
            "",
            "evil.example",
            "evil.example:8742",
            "127.0.0.1.evil.example",
            "localhost.evil.example:8742",
            "[::1",
            "[::1]x",
            "[evil]:8742",
        ] {
            assert!(!Router::host_is_literal(host), "{host} could be rebound");
        }
    }

    #[test]
    fn a_body_is_text_or_bytes_and_says_so_the_same_way() {
        let text = Body::from("hello".to_string());
        assert_eq!(text.len(), 5);
        assert!(!text.is_empty());
        assert_eq!(text.as_bytes(), b"hello");
        assert_eq!(text, *"hello");
        assert_eq!(format!("{text}"), "hello");
        assert!(matches!(text.text(), std::borrow::Cow::Borrowed(_)));

        let bytes = Body::from(vec![0x89, b'P', b'N', b'G']);
        assert_eq!(bytes.len(), 4);
        assert_eq!(bytes.as_bytes()[0], 0x89);
        assert_ne!(bytes, *"PNG");
        // a file that is not UTF-8 is passed through unchanged and only repaired when a
        // diagnostic asks for text
        assert!(matches!(bytes.text(), std::borrow::Cow::Owned(_)));
        assert!(Body::from(Vec::new()).is_empty());
        assert_eq!(Body::from("a"), Body::Text("a".into()));
    }

    #[test]
    fn a_response_carries_the_headers_it_was_given() {
        let r = Response::new(200, "text/plain; charset=utf-8", "hi".to_string())
            .with_header("Cache-Control", "no-cache");
        assert_eq!(r.status, 200);
        assert_eq!(r.body, *"hi");
        assert!(r
            .headers
            .iter()
            .any(|(k, v)| k == "Cache-Control" && v == "no-cache"));

        let e = Response::error(404, "not_found", "nothing here");
        assert_eq!(e.status, 404);
        assert_eq!(e.content_type, "application/json");
        let parsed: ErrorBody = serde_json::from_str(&e.body.text()).expect("errors are JSON");
        assert_eq!(parsed.error.code, "not_found");
        assert_eq!(parsed.error.message, "nothing here");
    }

    #[test]
    fn the_repository_is_named_and_its_path_is_not() {
        assert_eq!(
            repository_name("/a/b/prismatic-majordomus"),
            "prismatic-majordomus"
        );
        assert_eq!(repository_name("/a/b/repo/"), "repo");
        assert_eq!(repository_name("/"), "repository");
        assert_eq!(repository_name(""), "repository");
    }

    #[test]
    fn the_swagger_shell_is_the_same_page_however_it_is_reached() {
        let page = swagger_response("<p class=\"mj-checkout\">checkout 0123456789ab</p>");
        assert_eq!(page.status, 200);
        assert!(page.content_type.starts_with("text/html"));
        assert!(page.body.text().contains("/openapi.json"));
        assert!(
            page.body.text().contains("checkout 0123456789ab"),
            "the shell names its checkout"
        );
    }

    #[test]
    fn only_an_explicit_html_accept_asks_for_a_page() {
        let plain = Request::parse_target("GET", "/", vec![]);
        assert!(!prefers_html(&plain));
        for accept in [
            "text/html",
            "text/html,application/xhtml+xml",
            "application/json, text/html;q=0.9",
        ] {
            let r = plain
                .clone()
                .with_headers(vec![("Accept".into(), accept.into())]);
            assert!(prefers_html(&r), "{accept}");
        }
        for accept in ["*/*", "application/json", "text/plain"] {
            let r = plain
                .clone()
                .with_headers(vec![("Accept".into(), accept.into())]);
            assert!(!prefers_html(&r), "{accept}");
        }
    }

    #[test]
    fn a_request_binds_the_way_the_projection_says_and_reads_back_the_same() {
        let get = Request::bind(
            HttpMethod::Get,
            "/api/v1/search",
            &json!({ "query": "a b", "limit": 2, "kind": null }),
        );
        assert_eq!(get.target(), "/api/v1/search?query=a%20b&limit=2");
        let back = Request::parse_target("GET", &get.target(), vec![]);
        assert_eq!(back.query, get.query);
        assert_eq!(back.path, get.path);

        let post = Request::bind(HttpMethod::Post, "/api/v1/x", &json!({ "a": 1 }));
        assert_eq!(post.target(), "/api/v1/x");
        assert_eq!(post.body, br#"{"a":1}"#);
    }

    #[test]
    fn target_parsing_and_decoding() {
        let r = Request::parse_target(
            "GET",
            "/api/v1/search?query=Git%20is%20the%20authority&limit=3&x=a%2Fb",
            vec![],
        );
        assert_eq!(r.path, "/api/v1/search");
        assert_eq!(
            r.query,
            vec![
                ("query".into(), "Git is the authority".into()),
                ("limit".into(), "3".into()),
                ("x".into(), "a/b".into())
            ]
        );
        assert_eq!(percent_decode("a+b%41%"), "a bA%");
        assert_eq!(Request::parse_target("GET", "/", vec![]).query, vec![]);
    }
}