clustervision 0.15.1

//! `cv serve` — one local HTTP server: the read API at `/api/*` (`cv_core::api::route_json`, plus
//! the two tantivy routes `/api/search` and `/api/stats`), the task inbox page at `/inbox` with
//! the routes its buttons use (`serve_tasks`), and, with `--web <dir>`, the browser dashboard from
//! `/`. Without `--web`, `/` is the inbox. A lightweight *synchronous* server ([`tiny_http`]) with a
//! small worker pool: the workload is a handful of pollers, and simplicity wins.
//!
//! The transcript corpus is sensitive (it can contain secrets) and the inbox writes identity-bearing
//! events, so both are locked to local callers: the `Host` header must name this machine (defeats
//! DNS rebinding), and CORS is echoed only for an allow-list of local origins (the served pages,
//! `localhost`/`127.0.0.1` dev servers, and the Tauri app) — never `*`. A write (`POST`) must be
//! `application/json` (so a cross-site form cannot send one without a preflight this server refuses)
//! and, when it carries an `Origin`, an allowed one. An optional bearer token (`--token` /
//! `$CV_SERVE_TOKEN`) gates every `/api/*` request; a non-loopback bind demands one (or an explicit
//! `--insecure-expose`). `OPTIONS` preflight is answered with a 204.

use anyhow::Result;
use cv_core::Harness;
use serde_json::{json, Value};
use std::io::Read;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use tiny_http::{Header, Method, Request, Response, Server};

use super::serve_tasks;

/// Everything `cv serve` was asked for.
pub(crate) struct ServeOpts {
    pub host: String,
    pub port: u16,
    pub web: Option<PathBuf>,
    pub token: Option<String>,
    pub insecure_expose: bool,
    /// Whose inbox `/inbox` opens on, and who a write is by when the request names nobody.
    pub who: Option<String>,
    /// Open the page in the default browser once the server is up.
    pub open: bool,
}

/// What one request handler needs to know beyond the request itself.
struct Ctx {
    /// The configured bind host, accepted in `Host`/`Origin` checks alongside the loopback names.
    bind_host: String,
    web_root: Option<PathBuf>,
    /// When set, every `/api/*` request must carry `Authorization: Bearer <token>`.
    token: Option<String>,
    default_who: Option<String>,
}

/// Gatekeep the exposure, then serve until the process is killed: a non-loopback bind serves the
/// whole transcript corpus (secrets included) and the inbox's writes to anyone who can reach the
/// port, so it demands a bearer token or an explicit `--insecure-expose`, and warns either way.
pub(crate) fn cmd_serve(opts: ServeOpts) -> Result<()> {
    if std::env::var_os("CVD_TOKEN").is_some() && std::env::var_os("CV_SERVE_TOKEN").is_none() {
        return crate::util::usage(
            "$CVD_TOKEN was renamed $CV_SERVE_TOKEN in 0.15.0 with `cvd serve` → `cv serve` \
             (or pass --token)",
        );
    }
    let token = opts
        .token
        .or_else(|| std::env::var("CV_SERVE_TOKEN").ok())
        .filter(|t| !t.is_empty());
    let host = opts.host.as_str();
    if !is_loopback_host(host) {
        if token.is_none() && !opts.insecure_expose {
            anyhow::bail!(
                "refusing to bind non-loopback host {host:?} without auth: the API serves your full \
                 transcript corpus (which can contain secrets) to anyone who can reach the port.\n\
                 Set a token (--token or $CV_SERVE_TOKEN), or pass --insecure-expose to serve it open."
            );
        }
        eprintln!("cv serve: WARNING: binding non-loopback host {host:?} — the API is reachable from the network.");
        if token.is_none() {
            eprintln!(
                "cv serve: WARNING: --insecure-expose without a token: anyone who can reach {host}:{} can read \
                 every transcript and act in the inbox as web:<who>.",
                opts.port
            );
        }
    }
    run(&opts.host, opts.port, opts.web, token, opts.who, opts.open)
}

/// Run the HTTP server until the process is killed. Never returns under normal operation.
fn run(
    host: &str,
    port: u16,
    web_root: Option<PathBuf>,
    token: Option<String>,
    who: Option<String>,
    open: bool,
) -> Result<()> {
    let server = Server::http((host, port)).map_err(|e| anyhow::anyhow!("failed to bind {host}:{port}: {e}"))?;
    // `--port 0` binds an ephemeral port; the banner below must carry the REAL bound port so
    // callers (test harnesses, scripts) can parse the address instead of racing to guess a free
    // one. For a fixed port this is the same number.
    let port = server.server_addr().to_ip().map_or(port, |a| a.port());
    // Canonicalize the web root once so per-request path-traversal checks are cheap and robust.
    let web_root = web_root.and_then(|d| match d.canonicalize() {
        Ok(c) => Some(c),
        Err(e) => {
            eprintln!("cv serve: --web {} is unreadable ({e}); serving API only", d.display());
            None
        }
    });
    match &web_root {
        Some(dir) => eprintln!(
            "cv serve on http://{host}:{port} — dashboard at /, inbox at /inbox, API at /api/* (web root {})",
            dir.display()
        ),
        None => eprintln!("cv serve on http://{host}:{port} — inbox at /, API at /api/* (no --web)"),
    }
    let display_host = if is_loopback_host(host) || host == "0.0.0.0" || host == "::" {
        "127.0.0.1"
    } else {
        host
    };
    let inbox = match &who {
        Some(w) => format!("http://{display_host}:{port}/inbox?who={}", urlencoding::encode(w)),
        None => format!("http://{display_host}:{port}/inbox"),
    };
    eprintln!("inbox: {inbox}");
    if open {
        let opener = if cfg!(target_os = "macos") { "open" } else { "xdg-open" };
        if let Err(e) = std::process::Command::new(opener).arg(&inbox).spawn() {
            eprintln!("could not open a browser ({e}); open {inbox} yourself");
        }
    }

    let server = Arc::new(server);
    let ctx = Arc::new(Ctx {
        bind_host: host.to_string(),
        web_root,
        token,
        default_who: who,
    });
    let mut workers = Vec::new();
    // A handful of workers is plenty for dashboard polling; they share the listener.
    for _ in 0..4 {
        let server = Arc::clone(&server);
        let ctx = Arc::clone(&ctx);
        workers.push(std::thread::spawn(move || {
            for request in server.incoming_requests() {
                // A panicking handler must cost one response, not a worker for the process's life.
                let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| handle(request, &ctx)));
                if outcome.is_err() {
                    eprintln!("cv serve: request handler panicked; worker continuing");
                }
            }
        }));
    }
    for w in workers {
        // If a worker panics we keep serving on the others, but join here so `run` blocks forever.
        let _ = w.join();
    }
    Ok(())
}

/// Handle one request: any error becomes a JSON error response.
fn handle(mut request: Request, ctx: &Ctx) {
    // DNS-rebinding guard: a hostile page can point its own domain at 127.0.0.1 and fetch us
    // same-origin, but it can't forge the Host header — reject anything that isn't our own name.
    if !host_allowed(header_value(&request, "Host").as_deref(), &ctx.bind_host) {
        let _ = request.respond(json_response(403, &json!({"error": "forbidden host"}), None, &[]));
        return;
    }
    // Echoed on API responses only when the Origin is on the local allow-list; never `*`.
    let raw_origin = header_value(&request, "Origin");
    let origin = allowed_origin(raw_origin.as_deref(), &ctx.bind_host);

    let method = request.method().clone();
    let raw_url = request.url().to_string();

    // CORS preflight: a 204, CORS-tagged only for allowed origins. Unauthenticated by design —
    // browsers strip credentials from preflights, and it discloses nothing.
    if method == Method::Options {
        let _ = request.respond(no_content(origin.as_deref()));
        return;
    }

    // Split off the query string, then normalise the path (strip trailing slash, decode segments).
    let (path, query) = match raw_url.split_once('?') {
        Some((p, q)) => (p, q),
        None => (raw_url.as_str(), ""),
    };
    let segments: Vec<String> = path
        .trim_end_matches('/')
        .split('/')
        .filter(|s| !s.is_empty())
        .map(cv_core::api::decode)
        .collect();
    let parts: Vec<&str> = segments.iter().map(String::as_str).collect();
    let is_api = parts.first() == Some(&"api");
    let post = method == Method::Post;

    // GET reads anything; POST is only ever an inbox write (`/api/task/<id>/<verb>`).
    if !(method == Method::Get || (post && matches!(parts.as_slice(), ["api", "task", _, _]))) {
        let _ = request.respond(json_response(
            405,
            &json!({"error": "method not allowed"}),
            origin.as_deref(),
            &[],
        ));
        return;
    }

    if !is_api {
        // The inbox page: at `/inbox` always, and at `/` when no dashboard is being hosted.
        let page = matches!(parts.as_slice(), ["inbox"] | ["inbox.html"])
            || (ctx.web_root.is_none() && matches!(parts.as_slice(), [] | ["index.html"]));
        if page {
            let _ = request.respond(text_response(
                200,
                "text/html; charset=utf-8",
                serve_tasks::PAGE.as_bytes().to_vec(),
            ));
            return;
        }
        if let Some(root) = &ctx.web_root {
            let _ = request.respond(static_file(root, &segments));
            return;
        }
    }

    if let Some(token) = &ctx.token {
        let authed = header_value(&request, "Authorization")
            .and_then(|v| v.strip_prefix("Bearer ").map(str::to_string))
            .is_some_and(|t| t == *token);
        if !authed {
            let _ = request.respond(json_response(
                401,
                &json!({"error": "missing or invalid bearer token"}),
                origin.as_deref(),
                &[],
            ));
            return;
        }
    }

    // A write: JSON only (a cross-site form or `text/plain` fetch is a "simple" request that needs
    // no preflight; requiring JSON forces one, which a foreign origin fails), and a foreign Origin
    // is refused outright rather than merely denied the response.
    let mut body = Value::Null;
    if post {
        let json_ct = header_value(&request, "Content-Type")
            .is_some_and(|ct| ct.to_ascii_lowercase().starts_with("application/json"));
        if !json_ct || (raw_origin.is_some() && origin.is_none()) {
            let _ = request.respond(json_response(
                403,
                &json!({"error": "a write must be application/json from a local origin"}),
                origin.as_deref(),
                &[],
            ));
            return;
        }
        // Capped: a note is a paragraph, not an upload.
        let mut buf = String::new();
        if request.as_reader().take(1 << 20).read_to_string(&mut buf).is_err() {
            let _ = request.respond(json_response(
                400,
                &json!({"error": "unreadable body"}),
                origin.as_deref(),
                &[],
            ));
            return;
        }
        if !buf.trim().is_empty() {
            match serde_json::from_str::<Value>(&buf) {
                Ok(v) => body = v,
                Err(e) => {
                    let _ = request.respond(json_response(
                        400,
                        &json!({"error": format!("body is not JSON: {e}")}),
                        origin.as_deref(),
                        &[],
                    ));
                    return;
                }
            }
        }
    }

    let q = cv_core::api::Query::parse(query);
    match serve_tasks::route(post, &parts, &q, &body, ctx.default_who.as_deref()) {
        Some(serve_tasks::Answer::Json(status, v)) => {
            let _ = request.respond(json_response(
                status,
                &v,
                origin.as_deref(),
                &[("Cache-Control", "no-store".into())],
            ));
        }
        Some(serve_tasks::Answer::Ndjson(lines)) => {
            let mut resp = text_response(200, "application/x-ndjson; charset=utf-8", lines.into_bytes());
            for h in cors_headers(origin.as_deref()) {
                resp.add_header(h);
            }
            resp.add_header(header("Cache-Control", "no-store"));
            let _ = request.respond(resp);
        }
        None if post => {
            let _ = request.respond(json_response(
                404,
                &json!({"error": "no such route"}),
                origin.as_deref(),
                &[],
            ));
        }
        None => {
            let (status, body, extra) = route(&parts, query);
            let _ = request.respond(json_response(status, &body, origin.as_deref(), &extra));
        }
    }
}

/// First value of a (case-insensitively named) request header, if present.
fn header_value(request: &Request, name: &'static str) -> Option<String> {
    request
        .headers()
        .iter()
        .find(|h| h.field.equiv(name))
        .map(|h| h.value.as_str().to_string())
}

/// The hostname part of a `Host` header or URL authority: strips a `:port`, unbrackets IPv6.
fn host_name(authority: &str) -> &str {
    match authority.strip_prefix('[') {
        Some(rest) => rest.split(']').next().unwrap_or(rest),
        None => authority.rsplit_once(':').map(|(name, _)| name).unwrap_or(authority),
    }
}

/// A name this server answers to: the loopback names, or the configured bind host.
fn is_local_name(name: &str, bind_host: &str) -> bool {
    name == "127.0.0.1" || name == "::1" || name.eq_ignore_ascii_case("localhost") || name == bind_host
}

/// Whether a configured bind host is a loopback name/address.
pub(crate) fn is_loopback_host(host: &str) -> bool {
    host.eq_ignore_ascii_case("localhost")
        || host
            .trim_matches(['[', ']'])
            .parse::<std::net::IpAddr>()
            .map(|ip| ip.is_loopback())
            .unwrap_or(false)
}

/// Whether the `Host` header names this machine. An explicitly non-loopback bind is an opt-in to
/// remote clients whose Host we can't predict, so the check only bites on loopback binds.
fn host_allowed(host_header: Option<&str>, bind_host: &str) -> bool {
    if !is_loopback_host(bind_host) {
        return true;
    }
    host_header.is_some_and(|h| is_local_name(host_name(h), bind_host))
}

/// The specific `Origin` to echo in `Access-Control-Allow-Origin`, if it's on the allow-list:
/// the Tauri app's origins, or an http(s) origin on a local name (any port — a dev dashboard on
/// e.g. `http://localhost:5173` is same-machine).
fn allowed_origin(origin: Option<&str>, bind_host: &str) -> Option<String> {
    let o = origin?;
    if o == "tauri://localhost" || o == "http://tauri.localhost" {
        return Some(o.to_string());
    }
    let authority = o.strip_prefix("http://").or_else(|| o.strip_prefix("https://"))?;
    is_local_name(host_name(authority), bind_host).then(|| o.to_string())
}

/// A reply: status, JSON body, and any response headers beyond the standard set. Only `/api/search`
/// uses the third element today (to say which door answered — see [`search`]).
type Reply = (u16, Value, Vec<(&'static str, String)>);

/// Route a decoded read path + raw query string. Never panics.
fn route(parts: &[&str], query: &str) -> Reply {
    // Routes that carry extra response headers answer here; everything else is header-free.
    if let ["api", "search"] = parts {
        return search(query);
    }
    if let ["api", "stats"] = parts {
        let (status, body) = stats(query);
        return (status, body, Vec::new());
    }
    // Every other noun is the one read API every door maps onto.
    let (status, body) = cv_core::api::route_json(parts, query);
    (status, body, Vec::new())
}

// --- search & stats: the two things the CLI could do and the dashboard could not ------------

/// `cv search`'s default `--limit`. The doors agree on defaults too, or a caller gets a different
/// number of rows depending on which one it asked.
const SEARCH_LIMIT: usize = 20;

/// `GET /api/stats?q=<query-calculus>` — corpus-wide fleet statistics: exactly what `cv stats
/// --json` prints (`sessions, messages, by_harness, top_cwds, earliest_created, latest_updated`),
/// computed by [`cv_core::stats::CorpusStats`] so the two doors cannot drift.
///
/// Why this exists: the dashboard's Stats view used to accumulate its totals from whichever
/// sessions the user had happened to click, and had to confess it ("…reflect the 1 opened session
/// — 6,872 not yet loaded"). The numbers are catalog-cheap for the whole fleet; there was never a
/// reason to guess at them.
///
/// The optional `q` is cv's query calculus (`cv schema`), the same string `cv stats -q` takes; a
/// parse error is a 400 quoting the core's own message.
fn stats(query: &str) -> (u16, Value) {
    let params = Query::parse(query);
    let q = match params.get("q") {
        Some(s) => match cv_core::SessionQuery::parse(&s) {
            Ok(q) => Some(q),
            // The core points at the reference by its 0.10 name; re-point it like the CLI does.
            Err(e) => return err(400, &e.replace("`cv query`", "`cv schema`")),
        },
        None => None,
    };
    let mut refs = cv_core::sessions();
    if let Some(q) = &q {
        cv_core::query::filter_refs(&mut refs, q, &crate::cmd::query::text_sets(q));
    }
    ok(cv_core::stats::CorpusStats::compute(&refs).to_json())
}

/// `GET /api/search?q=&limit=&harness=&cwd=&semantic=1` — full-text (or `semantic=1`) search over
/// the whole corpus, as the JSON array of rows `cv search --json` emits: the §3 session row plus
/// `score`, `snippet` and the sub-agent provenance trio, shaped by [`cv_core::rows::SearchRow`].
///
/// Why this exists: the dashboard's search box could only filter the session stubs it had already
/// downloaded, so it could not find a message it had not fetched — while `cv search` answers over
/// the whole archive instantly off the tantivy index `cv index` maintains. Same index, same rows,
/// through the other door.
///
/// **Degradation, and saying so.** With no index (or an unreadable one) this does not error — it
/// takes the same head-capped live scan `cv search` falls back to ([`cv_core::scan::live_search`]),
/// which is slower and only sees each session's capped head. Which path answered rides on
/// `X-Cv-Search-Source` (`index` | `semantic` | `live`), with a human sentence in `X-Cv-Search-Note`
/// whenever the answer is degraded or truncated, so the UI can tell the user rather than silently
/// showing a worse result. Both headers are CORS-exposed. The body stays exactly the CLI's array.
fn search(query: &str) -> Reply {
    let params = Query::parse(query);
    // An empty query would mean "every session", which is `/api/sessions`' job; searching for
    // nothing is a caller mistake, not an empty result set.
    let Some(q) = params.get("q") else {
        let (s, v) = err(400, "missing q parameter");
        return (s, v, Vec::new());
    };
    // Validate harness up front so a typo is a clear 400 rather than silently empty.
    let want = match params.get("harness") {
        Some(h) => match Harness::parse(&h) {
            Some(h) => Some(h),
            None => {
                let (s, v) = err(400, &format!("unknown harness {h:?}"));
                return (s, v, Vec::new());
            }
        },
        None => None,
    };
    let limit = params
        .get("limit")
        .and_then(|l| l.parse::<usize>().ok())
        .unwrap_or(SEARCH_LIMIT);
    let cwd = params.get("cwd");
    let semantic = params
        .get("semantic")
        .is_some_and(|v| v == "1" || v.eq_ignore_ascii_case("true"));

    // Same fetch-then-filter shape as `cv search`: ask the index for 4× the wanted rows so the
    // harness filter has something to cut into, then take `limit`.
    let fetch = limit.saturating_mul(4);
    let (hits, source, mut note) = if semantic {
        match cv_search::semantic_search(None, &q, fetch) {
            Ok(hits) => (hits, "semantic", None),
            Err(e) => {
                // A live scan cannot stand in for semantic ranking, so this is an error, exactly
                // as `cv search --semantic` exits non-zero rather than quietly changing mode.
                let (s, v) = err(
                    500,
                    &format!("semantic search failed (run `cv index --semantic` first?): {e:#}"),
                );
                return (s, v, Vec::new());
            }
        }
    } else if cv_search::default_tantivy_dir().exists() {
        // The index is authoritative when present — an empty result means "no match", never
        // "fall back to a live scan".
        match cv_search::text_search(None, &q, fetch) {
            Ok(hits) => (hits, "index", None),
            Err(e) => (
                Vec::new(),
                "live",
                Some(format!("tantivy index unavailable ({e:#}); scanned live")),
            ),
        }
    } else {
        (
            Vec::new(),
            "live",
            Some("no index yet — scanned live; run `cv index` for instant, full-transcript search".into()),
        )
    };

    let mut rows: Vec<Value> = if source == "live" {
        match cv_core::scan::live_search(&q, want, limit) {
            Ok(found) => {
                if found.truncated {
                    note = Some(format!(
                        "{} (stopped at {limit} hits; raise limit for more)",
                        note.unwrap_or_default()
                    ));
                }
                found
                    .hits
                    .iter()
                    .map(|h| cv_core::rows::live_search_row(&h.session, &h.title, &h.snippet))
                    .collect()
            }
            Err(e) => {
                let (s, v) = err(500, &format!("live scan failed: {e:#}"));
                return (s, v, Vec::new());
            }
        }
    } else {
        hits.iter()
            .filter(|h| want.is_none_or(|w| h.harness == w.as_str()))
            .map(|h| {
                cv_core::rows::SearchRow {
                    id: &h.id,
                    harness: &h.harness,
                    cwd: h.cwd.as_deref(),
                    title: h.title.as_deref(),
                    created_at: h.created_at,
                    updated_at: h.updated_at,
                    score: Some(h.score),
                    snippet: &h.snippet,
                    agent_id: h.agent_id.as_deref(),
                    parent_id: h.parent_id.as_deref(),
                    workflow: h.workflow.as_deref(),
                }
                .to_json()
            })
            .collect()
    };
    // `cwd` is the daemon's own filter (the CLI has no `search --cwd`): a substring of the row's
    // cwd as the caller will see it, matching `/api/sessions?cwd=`. A row with no cwd never matches.
    if let Some(needle) = &cwd {
        rows.retain(|r| r["cwd"].as_str().is_some_and(|c| c.contains(needle.as_str())));
    }
    rows.truncate(limit);

    // The index is authoritative, so an empty result means "no match" — but the two reasons a real
    // conversation is unfindable are both about the index, not the query, and `cv search` says so
    // on a miss. Same note here, and only on a miss (the staleness check costs a metadata-only
    // discovery sweep, which is not something to pay on every hit).
    if source == "index" && rows.is_empty() {
        note = index_miss_note();
    }

    let mut headers = vec![("X-Cv-Search-Source", source.to_string())];
    if let Some(n) = note {
        headers.push(("X-Cv-Search-Note", header_safe(&n)));
    }
    (200, json!(rows), headers)
}

/// Why an indexed search might have come back empty for something that really was said — the same
/// two hints `cv search` prints on a miss: the index has fallen behind the newest session, and/or
/// it holds no sub-agent transcripts (so nothing an Agent/Workflow lane discussed is searchable).
fn index_miss_note() -> Option<String> {
    let mut parts: Vec<String> = Vec::new();
    if let Some(days) = index_days_behind() {
        parts.push(format!(
            "the index is ~{days} day(s) behind the newest session — run `cv index`"
        ));
    }
    if !cv_search::fts::has_subagent_docs(&cv_search::default_tantivy_dir()) {
        parts.push(
            "sub-agent transcripts aren't searched yet — rebuild with `cv index --subagents` to \
             include the Agent/Workflow lanes"
                .into(),
        );
    }
    (!parts.is_empty()).then(|| parts.join("; "))
}

/// Whole days the FTS index lags the newest session file on disk, when ≥ 1: one stored-field scan
/// of the index plus a metadata-only discovery sweep (a stat per session, no parsing).
fn index_days_behind() -> Option<u64> {
    const DAY_NS: i64 = 86_400 * 1_000_000_000;
    let indexed = cv_search::fts::newest_indexed_mtime(&cv_search::default_tantivy_dir())?;
    let newest_on_disk = cv_core::discover_all()
        .iter()
        .map(|r| cv_core::offsets::file_sig(&r.path).0)
        .max()?;
    let days = newest_on_disk.saturating_sub(indexed) / DAY_NS;
    (days >= 1).then_some(days as u64)
}

/// A header-safe rendering of a note: header values are a byte channel with no escaping, so keep
/// them printable ASCII on one line (`tiny_http` refuses anything else, which would drop the note).
fn header_safe(s: &str) -> String {
    s.chars()
        .map(|c| if (' '..='~').contains(&c) { c } else { ' ' })
        .collect::<String>()
        .trim()
        .to_string()
}

// --- small helpers ---------------------------------------------------------

use cv_core::api::Query;

fn ok(value: Value) -> (u16, Value) {
    (200, value)
}

/// Serve a static file from the configured web root for a non-`/api` request.
///
/// `segments` is the already-decoded path (so `["web", "components", "cv-forest.js"]`). An empty
/// path maps to `index.html`. The resolved path is canonicalized and must stay inside the (already
/// canonical) root — any traversal (`..`, symlink escape, absolute injection) yields a 403. A
/// missing file falls back to `index.html` (so client-side deep links work), and only a missing
/// index is a 404. The `Content-Type` is inferred from the extension; static assets are not
/// CORS-tagged (same-origin) — only the JSON API is.
fn static_file(root: &Path, segments: &[String]) -> Response<std::io::Cursor<Vec<u8>>> {
    let index = root.join("index.html");
    let resolved = if segments.is_empty() {
        index.clone()
    } else {
        // Reject obviously hostile components before touching the filesystem.
        if segments.iter().any(|s| s == ".." || s.contains('\0')) {
            return text_response(403, "text/plain; charset=utf-8", b"forbidden".to_vec());
        }
        let mut p = root.to_path_buf();
        for s in segments {
            p.push(s);
        }
        p
    };

    // A deep link is a ROUTE and falls back to the SPA index; a missing ASSET is a 404. Falling
    // back for an asset hands the browser `index.html` under the asset's name, and for a module
    // script that surfaces as "Expected a JavaScript-or-Wasm module script but the server
    // responded with a MIME type of text/html" — which reads like a server misconfiguration
    // rather than the truth, that the file is not there. (`/pkg/cv_web.js`, the optional wasm
    // bundle, is not built unless you run wasm-pack.)
    let is_asset = resolved
        .extension()
        .and_then(|e| e.to_str())
        .is_some_and(|e| !e.eq_ignore_ascii_case("html"));

    let serve_path = match resolved.canonicalize() {
        Ok(c) if c.starts_with(root) && c.is_file() => c,
        _ if is_asset => return text_response(404, "text/plain; charset=utf-8", b"not found".to_vec()),
        _ => match index.canonicalize() {
            Ok(c) if c.starts_with(root) && c.is_file() => c,
            _ => return text_response(404, "text/plain; charset=utf-8", b"not found".to_vec()),
        },
    };

    match std::fs::read(&serve_path) {
        Ok(bytes) => text_response(200, content_type_for(&serve_path), bytes),
        Err(_) => text_response(404, "text/plain; charset=utf-8", b"not found".to_vec()),
    }
}

/// Guess a `Content-Type` from a file extension — enough for the dashboard's asset set.
fn content_type_for(path: &Path) -> &'static str {
    match path
        .extension()
        .and_then(|e| e.to_str())
        .map(str::to_ascii_lowercase)
        .as_deref()
    {
        Some("html") => "text/html; charset=utf-8",
        Some("js") | Some("mjs") => "text/javascript; charset=utf-8",
        Some("css") => "text/css; charset=utf-8",
        Some("json") => "application/json; charset=utf-8",
        Some("wasm") => "application/wasm",
        Some("svg") => "image/svg+xml",
        Some("png") => "image/png",
        Some("jpg") | Some("jpeg") => "image/jpeg",
        Some("gif") => "image/gif",
        Some("ico") => "image/x-icon",
        Some("woff2") => "font/woff2",
        Some("woff") => "font/woff",
        Some("map") => "application/json; charset=utf-8",
        _ => "application/octet-stream",
    }
}

/// A raw-bytes response with a `Content-Type` and no CORS headers (static assets are same-origin).
fn text_response(status: u16, content_type: &str, body: Vec<u8>) -> Response<std::io::Cursor<Vec<u8>>> {
    let mut resp = Response::from_data(body).with_status_code(status);
    resp.add_header(header("Content-Type", content_type));
    resp
}

fn err(status: u16, msg: &str) -> (u16, Value) {
    (status, json!({ "error": msg }))
}

/// Build a JSON response, CORS-tagged for `origin` when one was allowed, plus any route-specific
/// headers (see [`EXPOSED_HEADERS`] — a header a cross-origin dashboard cannot read is not a
/// channel).
fn json_response(
    status: u16,
    body: &Value,
    origin: Option<&str>,
    extra: &[(&'static str, String)],
) -> Response<std::io::Cursor<Vec<u8>>> {
    let data = serde_json::to_vec(body).unwrap_or_else(|_| b"{\"error\":\"serialize failed\"}".to_vec());
    let mut resp = Response::from_data(data).with_status_code(status);
    for h in cors_headers(origin) {
        resp.add_header(h);
    }
    for (field, value) in extra {
        resp.add_header(header(field, value));
    }
    resp.add_header(header("Content-Type", "application/json"));
    resp
}

/// A 204 No Content, CORS-tagged for `origin` when one was allowed — for `OPTIONS` preflight.
fn no_content(origin: Option<&str>) -> Response<std::io::Empty> {
    let mut resp = Response::empty(204);
    for h in cors_headers(origin) {
        resp.add_header(h);
    }
    resp
}

/// Response headers a cross-origin caller is allowed to READ. A browser hides every non-safelisted
/// response header from `fetch` unless it is named here, so `/api/search`'s "this answer is
/// degraded" signal would be invisible to a dashboard on a dev server without it.
const EXPOSED_HEADERS: &str = "X-Cv-Search-Source, X-Cv-Search-Note";

/// CORS headers echoing the one allowed `origin` — an unlisted origin gets none (the browser then
/// refuses to share the response with it). `Vary: Origin` keeps caches from mixing the two.
fn cors_headers(origin: Option<&str>) -> Vec<Header> {
    let mut headers = vec![header("Vary", "Origin")];
    if let Some(o) = origin {
        headers.push(header("Access-Control-Allow-Origin", o));
        headers.push(header("Access-Control-Allow-Methods", "GET, POST, OPTIONS"));
        headers.push(header("Access-Control-Allow-Headers", "Authorization, Content-Type"));
        headers.push(header("Access-Control-Expose-Headers", EXPOSED_HEADERS));
    }
    headers
}

fn header(field: &str, value: &str) -> Header {
    // These are all static, valid headers; the parse cannot fail in practice.
    Header::from_bytes(field.as_bytes(), value.as_bytes())
        .unwrap_or_else(|_| Header::from_bytes(&b"X-Invalid"[..], &b"1"[..]).unwrap())
}