v0.31.8

src/admin/file_logs.rs

@@ -35,6 +35,8 @@ struct FileLogQuery {
     aggregate_field: Option<String>,
     aggregate_limit: Option<usize>,
     aggregate_min_count: Option<usize>,
+    sort_by: Option<String>,
+    sort_descending: Option<bool>,
     offset: Option<usize>,
     limit: Option<usize>,
 }

src/admin/file_logs_query.rs

@@ -50,6 +50,91 @@ fn record_matches(value: &Value, query: &FileLogQuery, search: &[FileLogSearchCl
     true
 }
 
+// Order the entire bounded matching scan before applying offset/limit. Sorting
+// only the current browser page would give misleading navigation results.
+#[derive(Debug)]
+enum FileLogSortKey {
+    Number(serde_json::Number),
+    Text(String),
+}
+
+fn stored_log_summary(value: &Value) -> String {
+    let field = |name| value.get(name).and_then(Value::as_str).filter(|text| !text.is_empty());
+    if let Some(reason) = field("reason").or_else(|| field("protocol_error")) {
+        return reason.to_owned();
+    }
+    if field("method").is_some() || field("path").is_some() {
+        return format!("{} {}{}", field("method").unwrap_or(""),
+            field("host").or_else(|| field("authority")).unwrap_or(""),
+            field("path").unwrap_or("")).trim().to_owned();
+    }
+    for key in ["error", "error_detail", "message", "raw", "outcome"] {
+        if let Some(text) = field(key) { return text.to_owned(); }
+    }
+    String::new()
+}
+
+fn stored_log_sort_key(record: &Value, field: &str) -> Option<FileLogSortKey> {
+    if field == "record" {
+        return Some(FileLogSortKey::Text(stored_log_summary(record).to_lowercase()));
+    }
+    // Prefer millisecond timestamps for numeric chronological sorting. RAW
+    // file timestamps use the existing ISO/text fallback.
+    let value = if field == "time" {
+        record.get("time_ms").filter(|value| value.is_number())
+            .or_else(|| record.get("timestamp"))
+    } else {
+        file_log_field(record, field)
+    }?;
+    match value {
+        Value::Null => None,
+        Value::Number(number) => Some(FileLogSortKey::Number(number.clone())),
+        Value::String(text) if !text.is_empty() => Some(FileLogSortKey::Text(text.to_lowercase())),
+        Value::Bool(boolean) => Some(FileLogSortKey::Text(boolean.to_string())),
+        Value::Array(_) | Value::Object(_) => Some(FileLogSortKey::Text(value.to_string().to_lowercase())),
+        _ => None,
+    }
+}
+
+fn file_log_timestamp_cmp_desc(left: &Value, right: &Value) -> std::cmp::Ordering {
+    match (left.get("time_ms").and_then(Value::as_u64), right.get("time_ms").and_then(Value::as_u64)) {
+        (Some(a), Some(b)) => b.cmp(&a),
+        _ => right.get("timestamp").and_then(Value::as_str).unwrap_or("")
+            .cmp(left.get("timestamp").and_then(Value::as_str).unwrap_or("")),
+    }
+}
+
+fn sort_file_log_records(records: &mut Vec<Value>, field: &str, descending: bool) {
+    use std::cmp::Ordering;
+    // Build one key per record; do not repeatedly allocate/parse strings in
+    // the O(n log n) comparison loop. The scan itself is limited to 20k lines.
+    let mut keyed = std::mem::take(records).into_iter().enumerate()
+        .map(|(ordinal, record)| (stored_log_sort_key(&record, field), ordinal, record))
+        .collect::<Vec<_>>();
+    keyed.sort_by(|left, right| {
+        let order = match (&left.0, &right.0) {
+            (None, None) => Ordering::Equal,
+            (None, Some(_)) => return Ordering::Greater, // missing values always last
+            (Some(_), None) => return Ordering::Less,
+            (Some(FileLogSortKey::Number(a)), Some(FileLogSortKey::Number(b))) =>
+                match (a.as_i64(), b.as_i64()) {
+                    (Some(left), Some(right)) => left.cmp(&right),
+                    _ => match (a.as_u64(), b.as_u64()) {
+                        (Some(left), Some(right)) => left.cmp(&right),
+                        _ => a.as_f64().partial_cmp(&b.as_f64()).unwrap_or(Ordering::Equal),
+                    },
+                },
+            (Some(FileLogSortKey::Text(a)), Some(FileLogSortKey::Text(b))) => a.cmp(b),
+            (Some(FileLogSortKey::Number(_)), Some(FileLogSortKey::Text(_))) => Ordering::Less,
+            (Some(FileLogSortKey::Text(_)), Some(FileLogSortKey::Number(_))) => Ordering::Greater,
+        };
+        (if descending { order.reverse() } else { order })
+            .then_with(|| file_log_timestamp_cmp_desc(&left.2, &right.2))
+            .then_with(|| left.1.cmp(&right.1))
+    });
+    records.extend(keyed.into_iter().map(|(_, _, record)| record));
+}
+
 fn validate_file_log_query(query: &FileLogQuery) -> Result<(), ApiError> {
     let text_ok = |value: &Option<String>, max: usize| {
         value
@@ -61,6 +146,7 @@ fn validate_file_log_query(query: &FileLogQuery) -> Result<(), ApiError> {
         || !text_ok(&query.client_ip, 128)
         || !text_ok(&query.vhost, 256)
         || query.aggregate_field.as_ref().is_some_and(|field| !valid_raw_field_key(field))
+        || query.sort_by.as_ref().is_some_and(|field| !valid_raw_field_key(field))
         || query.aggregate_limit.is_some_and(|value| value == 0 || value > FILE_LOG_MAX_AGGREGATE_RESULTS)
         || query.aggregate_min_count.is_some_and(|value| value < 2 || value > FILE_LOG_SCAN_LINES)
         || query.offset.unwrap_or(0) > FILE_LOG_MAX_OFFSET
@@ -171,17 +257,8 @@ async fn file_logs_query(
                 Err(_) => truncated = true,
             }
         }
-        records.sort_by(|a, b| {
-            let numeric = |value: &Value| value.get("time_ms").and_then(Value::as_u64);
-            match (numeric(a), numeric(b)) {
-                (Some(left), Some(right)) => right.cmp(&left),
-                _ => b
-                    .get("timestamp")
-                    .and_then(Value::as_str)
-                    .unwrap_or("")
-                    .cmp(a.get("timestamp").and_then(Value::as_str).unwrap_or("")),
-            }
-        });
+        sort_file_log_records(&mut records, query.sort_by.as_deref().unwrap_or("time"),
+            query.sort_descending.unwrap_or(true));
         let mut aggregation = aggregate_counts.into_iter()
             .filter(|(_, count)| *count >= aggregate_min_count)
             .map(|(value, count)| json!({"value": value, "count": count}))

src/admin/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "RustProxy Administration API",
-    "version": "0.31.7",
+    "version": "0.31.8",
     "description": "Administration API for the active panel origin. Sign in through the panel; the same-origin HttpOnly cookie authenticates all private operations. Mutations also require the exact Origin, X-RustProxy-Request: 1 and a session-bound X-CSRF-Token. Loopback HTTP is the default; Settings can enable HTTPS before using a non-loopback administration bind. This document contains no live configuration or credentials. Object schemas marked extensible are summaries: full configuration validation is authoritative in Rust."
   },
   "servers": [
@@ -3625,6 +3625,17 @@
                 "default": 60
               }
             }
+          },
+          "file_log_sort": {
+            "type": "string",
+            "maxLength": 128,
+            "default": "time",
+            "description": "Account-scoped Stored Logs sort column; a fixed or discovered parsed JSON field, including nested dotted fields."
+          },
+          "file_log_descending": {
+            "type": "boolean",
+            "default": true,
+            "description": "Account-scoped Stored Logs sort direction."
           }
         },
         "required": [
@@ -11009,6 +11020,27 @@
               "maximum": 500,
               "default": 100
             }
+          },
+          {
+            "name": "sort_by",
+            "in": "query",
+            "required": false,
+            "description": "Sort field applied across the entire bounded matching scan before pagination. Includes time, record summary, source and parsed nested field names.",
+            "schema": {
+              "type": "string",
+              "maxLength": 128,
+              "default": "time"
+            }
+          },
+          {
+            "name": "sort_descending",
+            "in": "query",
+            "required": false,
+            "description": "Descending sort direction; null/missing field values are always last.",
+            "schema": {
+              "type": "boolean",
+              "default": true
+            }
           }
         ],
         "responses": {

src/admin/preferences.rs

@@ -30,6 +30,8 @@ fn default_admin_dashboard_widgets() -> Vec<String> {
         .map(|value| (*value).to_owned())
         .collect()
 }
+fn default_file_log_sort() -> String { "time".to_owned() }
+fn default_file_log_descending() -> bool { true }
 fn default_file_log_columns() -> Vec<String> {
     [
         "time",
@@ -99,6 +101,10 @@ struct AdminPreferences {
     dashboard_hidden_widgets: Vec<String>,
     #[serde(default = "default_file_log_columns")]
     file_log_columns: Vec<String>,
+    #[serde(default = "default_file_log_sort")]
+    file_log_sort: String,
+    #[serde(default = "default_file_log_descending")]
+    file_log_descending: bool,
     #[serde(default = "default_backend_table_columns")]
     backend_table_columns: Vec<String>,
     #[serde(default = "default_backend_table_sort")]
@@ -146,6 +152,8 @@ impl Default for AdminPreferences {
             dashboard_widgets: default_admin_dashboard_widgets(),
             dashboard_hidden_widgets: Vec::new(),
             file_log_columns: default_file_log_columns(),
+            file_log_sort: default_file_log_sort(),
+            file_log_descending: default_file_log_descending(),
             backend_table_columns: default_backend_table_columns(),
             backend_table_sort: default_backend_table_sort(),
             backend_table_descending: false,
@@ -203,6 +211,12 @@ fn validate_admin_preferences(preferences: &AdminPreferences) -> Result<(), ApiE
             ));
         }
     }
+    if !valid_raw_field_key(&preferences.file_log_sort) {
+        return Err(ApiError(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "invalid stored-log sort column preference".into(),
+        ));
+    }
     if !matches!(preferences.theme.as_str(), "dark" | "light") {
         return Err(ApiError(
             StatusCode::UNPROCESSABLE_ENTITY,

src/admin/web/app/core.js

@@ -151,6 +151,7 @@ async function api(path, options = {}) {
 function setPanel(name, navigate = true) {
     if (name === "security") { setPanel("settings", navigate); window.rustProxySettings?.select("security"); return; }
     if (!Object.hasOwn(PANEL_PATHS, name)) name = "overview";
+    const previousPanel = currentPanel;
     currentPanel = name;
     $("overview-refresh").hidden = name !== "overview";
     document.querySelectorAll(".nav").forEach(e => e.classList.toggle("active", e.dataset.panel === name));
@@ -159,6 +160,9 @@ function setPanel(name, navigate = true) {
     if (navigate && typeof location !== "undefined" && ["http:", "https:"].includes(location.protocol) && location.pathname !== PANEL_PATHS[name]) history.pushState({ panel: name }, "", PANEL_PATHS[name]);
     if (name === "settings") window.rustProxySettings?.syncLocation?.();
     window.rustProxyRefresh?.setPanel(name);
+    // Read the cached Docker status on each visit, independent of the Live-view toggle.
+    // This is GET /api/docker, not the POST that triggers an agent poll.
+    if (name === "docker-vhosts" && previousPanel !== name && authenticated && envelope) void window.rustProxyRefresh?.manual("docker");
     if (name === "tls") window.rustProxyAcme?.syncLocation?.();
     if (name === "filelogs") void window.rustProxyFileLogs?.refresh();
     if (name === "tls") void refreshCertificateInventory().then(() => { if (authenticated && currentPanel === "tls") renderCertificates(); });

src/admin/web/docker.js

@@ -10,6 +10,7 @@
   const HIDDEN_KEY = "rustproxy.docker.hidden-vhosts";
   const cfg = () => envelope?.config?.docker_agents || { agents: [] };
   const obs = id => observations.find(item => item.agent_id === id);
+  const hasUnobservedAgent = () => (cfg().agents || []).some(agent => agent.enabled !== false && !obs(agent.id));
   const firstListener = () => envelope?.config?.listeners?.endpoints?.find(item => item.enabled !== false)?.id || "http";
   const defaultHealth = () => ({ mode: "tcp", path: "/", host: null, interval_ms: 5000, timeout_ms: 2000, slow_response_ms: 1500, fall: 3, rise: 2, expected_status_min: 200, expected_status_max: 399 });
   const defaultPassiveHealth = () => ({ enabled: false, count_connect_errors: true, count_timeouts: true, count_io_errors: true, count_http_5xx: true, count_slow_responses: false, fall: null, rise: null });
@@ -115,7 +116,7 @@
     const https = String(agent?.endpoint || "").toLowerCase().startsWith("https://");
     const pinned = !!agent?.tls_fingerprint_sha256;
     if (!https) return { key: "dockerTlsPlain", cls: "warn", detail: t("dockerTlsPlainHelp") };
-    if (pinned) return { key: "dockerTlsPinned", cls: "live", detail: `${t("dockerTlsFingerprint")}: ${prettyFingerprint(agent.tls_fingerprint_sha256)}` };
+    if (pinned) return { key: "dockerTlsPinned", cls: state?.ok ? "live" : "", detail: `${t("dockerTlsFingerprint")}: ${prettyFingerprint(agent.tls_fingerprint_sha256)}` };
     if (state?.ok) return { key: "dockerTlsPublicCa", cls: "live", detail: t("dockerTlsPublicCaHelp") };
     return { key: "dockerTlsPublicCa", cls: "", detail: t("dockerTlsPublicCaHelp") };
   }
@@ -326,7 +327,10 @@
       const state = obs(agent.id), box = el("article", undefined, "card docker-agent-card"); box.dataset.agentId = agent.id; box.dataset.searchText = `${agent.id} ${agent.name || ""} ${agent.base_domain || ""}`.toLowerCase(); const head = el("div", undefined, "card-heading"), left = el("div"); left.append(el("span", agent.id, "small-label"), el("h2", agent.name));
       const badges = el("div", undefined, "entity-actions"), connection = el("span", state?.ok ? t("dockerConnected") : state ? t("dockerError") : t("dockerWaiting"), `pill ${state?.ok ? "live" : ""}`), sec = securityInfo(agent, state); badges.append(el("span", t(sec.key), `pill ${sec.cls}`.trim()), connection); head.append(left, badges); box.append(head);
       if (!agent.enabled) { box.append(el("p", t("dockerAgentDisabled"), "fine")); target.append(box); continue; }
-      if (!state?.ok) { const error = el("div", undefined, "docker-agent-error"); error.append(el("b", t("dockerAgentConnectionFailed")), el("p", state?.error || t("dockerNoObservation"), "fine"), el("small", sec.detail, "fine")); box.append(error); }
+      // No observation is the normal state while the first background poll is in flight.
+      // A configured TLS fingerprint alone is not proof that an agent was contacted.
+      if (!state) box.append(el("p", t("dockerNoObservation"), "fine"));
+      else if (!state.ok) { const error = el("div", undefined, "docker-agent-error"); error.append(el("b", t("dockerAgentConnectionFailed")), el("p", state.error || t("dockerUnknownPollError"), "fine")); box.append(error); }
       if (!state?.inventory) { const rows = el("div", undefined, "docker-service-list"); for (const item of agent.assignments || []) rows.append(assignmentRow(agent, null, null, item, true)); if (!rows.children.length) rows.append(el("p", t("dockerNoPublishedPorts"), "empty")); box.append(rows); target.append(box); continue; }
       const inv = state.inventory, defaultIp = agent.default_target_ip || agent.target_ip_override || t("dockerTargetAuto"), serviceCount = (inv.services || []).length, overview = el("div", undefined, "docker-agent-overview"); box.dataset.searchText += ` ${inv.hostname || ""}`.toLowerCase();
       overview.append(el("span", `${t("dockerHost")}: ${inv.hostname}`), el("span", `${t("dockerServices")}: ${serviceCount}`), el("span", `${t("dockerLastChecked")}: ${checkedAgo(state.checked_at_unix_ms)}`), el("span", `*.${agent.base_domain}`)); box.append(overview);
@@ -406,8 +410,10 @@
   $("docker-agents-form")?.addEventListener("submit", async event => { event.preventDefault(); const form = event.currentTarget; if (!envelope || busy) return; try { await withFormSubmitState(form, event.submitter, async () => { if (await saveSection("docker-agents", collectSettings())) { setSettingsDirty("docker-agents-form", false); await refresh(true); } }); } catch (error) { toast(error.message, true); } });
   rustProxyRefresh.register("docker", {
     interval: () => 5,
-    active: () => currentPanel === "docker-vhosts" && liveEnabled() && canLiveRender(),
+    // Even with local Live view off, observe the first startup result.
+    // Once every enabled agent has a first result, stop unless Live is enabled.
+    active: () => currentPanel === "docker-vhosts" && canLiveRender() && (liveEnabled() || hasUnobservedAgent()),
     run: async context => refresh(false, context)
   });
-  window.rustProxyDocker = { render() { syncLiveSwitch(); renderSettings(); renderDiscovery(); }, refresh, applyPreferences, reset() { observations = []; pools = []; poolRoutes = []; poolIndex = new Map(); showHidden = false; listPrefs = { sort: "service", descending: false }; hiddenVhosts = loadHidden(); if ($("docker-search")) $("docker-search").value = ""; if ($("docker-vhost-sort")) $("docker-vhost-sort").value = listPrefs.sort; syncSortDirection(); $("docker-discovery-list")?.replaceChildren(); $("docker-agent-settings-list")?.replaceChildren(); syncLiveSwitch(); applyViewFilters(); } };
+  window.rustProxyDocker = { render() { syncLiveSwitch(); renderSettings(); renderDiscovery(); if (currentPanel === "docker-vhosts" && authenticated) { rustProxyRefresh.sync(); void rustProxyRefresh.manual("docker"); } }, refresh, applyPreferences, reset() { observations = []; pools = []; poolRoutes = []; poolIndex = new Map(); showHidden = false; listPrefs = { sort: "service", descending: false }; hiddenVhosts = loadHidden(); if ($("docker-search")) $("docker-search").value = ""; if ($("docker-vhost-sort")) $("docker-vhost-sort").value = listPrefs.sort; syncSortDirection(); $("docker-discovery-list")?.replaceChildren(); $("docker-agent-settings-list")?.replaceChildren(); syncLiveSwitch(); applyViewFilters(); } };
 })();

src/admin/web/error_400.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>400 - Bad request - RustProxy</title>
+    <style>
+        body {
+            margin: 12vh auto;
+            padding: 24px;
+            max-width: 620px;
+            background: #131615;
+            color: #e5e9e6;
+            font: 15px/1.6 system-ui, sans-serif
+        }
+
+        h1 {
+            font-size: 24px;
+            margin: 0 0 8px
+        }
+
+        p {
+            margin: 0;
+            color: #b9c3bc
+        }
+    </style>
+</head>
+
+<body>
+    <main>
+        <h1>400 - Bad request</h1>
+        <p>The request could not be processed because it is invalid.</p>
+    </main>
+</body>
+
+</html>

src/admin/web/error_408.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>408 - Request timeout - RustProxy</title>
+    <style>
+        body {
+            margin: 12vh auto;
+            padding: 24px;
+            max-width: 620px;
+            background: #131615;
+            color: #e5e9e6;
+            font: 15px/1.6 system-ui, sans-serif
+        }
+
+        h1 {
+            font-size: 24px;
+            margin: 0 0 8px
+        }
+
+        p {
+            margin: 0;
+            color: #b9c3bc
+        }
+    </style>
+</head>
+
+<body>
+    <main>
+        <h1>408 - Request timeout</h1>
+        <p>The request was not completed in time. Please try again.</p>
+    </main>
+</body>
+
+</html>

src/admin/web/error_410.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>410 - Gone - RustProxy</title>
+    <style>
+        body {
+            margin: 12vh auto;
+            padding: 24px;
+            max-width: 620px;
+            background: #131615;
+            color: #e5e9e6;
+            font: 15px/1.6 system-ui, sans-serif
+        }
+
+        h1 {
+            font-size: 24px;
+            margin: 0 0 8px
+        }
+
+        p {
+            margin: 0;
+            color: #b9c3bc
+        }
+    </style>
+</head>
+
+<body>
+    <main>
+        <h1>410 - Gone</h1>
+        <p>The requested resource is no longer available.</p>
+    </main>
+</body>
+
+</html>

src/admin/web/error_413.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>413 - Payload too large - RustProxy</title>
+    <style>
+        body {
+            margin: 12vh auto;
+            padding: 24px;
+            max-width: 620px;
+            background: #131615;
+            color: #e5e9e6;
+            font: 15px/1.6 system-ui, sans-serif
+        }
+
+        h1 {
+            font-size: 24px;
+            margin: 0 0 8px
+        }
+
+        p {
+            margin: 0;
+            color: #b9c3bc
+        }
+    </style>
+</head>
+
+<body>
+    <main>
+        <h1>413 - Payload too large</h1>
+        <p>The request body exceeds the allowed size.</p>
+    </main>
+</body>
+
+</html>

src/admin/web/error_500.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>500 - Internal server error - RustProxy</title>
+    <style>
+        body {
+            margin: 12vh auto;
+            padding: 24px;
+            max-width: 620px;
+            background: #131615;
+            color: #e5e9e6;
+            font: 15px/1.6 system-ui, sans-serif
+        }
+
+        h1 {
+            font-size: 24px;
+            margin: 0 0 8px
+        }
+
+        p {
+            margin: 0;
+            color: #b9c3bc
+        }
+    </style>
+</head>
+
+<body>
+    <main>
+        <h1>500 - Internal server error</h1>
+        <p>The server encountered an unexpected error.</p>
+    </main>
+</body>
+
+</html>

src/admin/web/error_502.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>502 - Bad gateway - RustProxy</title>
+    <style>
+        body {
+            margin: 12vh auto;
+            padding: 24px;
+            max-width: 620px;
+            background: #131615;
+            color: #e5e9e6;
+            font: 15px/1.6 system-ui, sans-serif
+        }
+
+        h1 {
+            font-size: 24px;
+            margin: 0 0 8px
+        }
+
+        p {
+            margin: 0;
+            color: #b9c3bc
+        }
+    </style>
+</head>
+
+<body>
+    <main>
+        <h1>502 - Bad gateway</h1>
+        <p>The upstream service returned an invalid response.</p>
+    </main>
+</body>
+
+</html>

src/admin/web/file-logs.js

@@ -11,6 +11,7 @@
     ]);
     let availableColumns = new Set(defaultColumnIds);
     let visibleColumns = new Set(defaultColumnIds);
+    let sortBy = "time", sortDescending = true, pendingRefresh = false;
 
 
     const CONSOLIDATION_STORAGE_KEY = "rp-file-logs-consolidate-vhosts";
@@ -146,8 +147,22 @@
     function syncHeaders() {
         const row = $("file-logs-table-head").querySelector("tr");
         const headers = orderedColumns().filter(id => visibleColumns.has(id)).map(id => {
-            const header = el("th", columnLabel(id)); header.dataset.fileLogColumn = id;
-            const key = specialLabels.get(id); if (key) header.dataset.i18n = key;
+            const header = el("th"); header.dataset.fileLogColumn = id;
+            header.setAttribute("aria-sort", sortBy === id ? (sortDescending ? "descending" : "ascending") : "none");
+            const button = el("button", undefined, "file-log-sort-button"); button.type = "button";
+            const caption = el("span", columnLabel(id));
+            const key = specialLabels.get(id); if (key) caption.dataset.i18n = key;
+            const arrow = el("span", sortBy === id ? (sortDescending ? "↓" : "↑") : "↕", "file-log-sort-indicator");
+            arrow.setAttribute("aria-hidden", "true");
+            const willDescend = sortBy === id ? !sortDescending : false;
+            button.title = `${t(willDescend ? "fileLogsSortDescending" : "fileLogsSortAscending")}: ${columnLabel(id)}`;
+            button.setAttribute("aria-label", button.title);
+            button.addEventListener("click", () => {
+                sortDescending = sortBy === id ? !sortDescending : false;
+                sortBy = id; selectedIndex = null; offset = 0;
+                syncHeaders(); void savePreferences(); void refresh(true);
+            });
+            button.append(caption, arrow); header.append(button);
             return header;
         });
         row.replaceChildren(...headers);
@@ -172,6 +187,8 @@
             ? preferences.file_log_columns.filter(id => typeof id === "string" && id.length <= 128)
             : [];
         visibleColumns = new Set(selected.length ? selected : defaultColumnIds);
+        sortBy = typeof preferences?.file_log_sort === "string" && /^[a-z0-9_.-]{1,128}$/i.test(preferences.file_log_sort) ? preferences.file_log_sort : "time";
+        sortDescending = preferences?.file_log_descending !== false;
         for (const id of visibleColumns) availableColumns.add(id);
         preferencesLoaded = true;
         syncColumnPicker(); syncHeaders(); renderRows();
@@ -184,7 +201,7 @@
             do {
                 preferenceSaveQueued = false;
                 const selected = orderedColumns().filter(id => visibleColumns.has(id));
-                const preferences = await window.rustProxyPreferences.update({ file_log_columns: selected });
+                const preferences = await window.rustProxyPreferences.update({ file_log_columns: selected, file_log_sort: sortBy, file_log_descending: sortDescending });
                 if (!preferenceSaveQueued) applyPreferences(preferences);
             } while (preferenceSaveQueued);
         } catch (error) { toast(error.message, true); }
@@ -267,12 +284,14 @@
             params.set("aggregate_min_count", String(Math.max(2, Number($("file-log-aggregate-min")?.value) || 2)));
             params.set("aggregate_limit", String(Math.max(1, Number($("file-log-aggregate-limit")?.value) || 50)));
         }
+        params.set("sort_by", sortBy); params.set("sort_descending", String(sortDescending));
         params.set("offset", String(offset)); params.set("limit", String(currentLimit()));
         return params.toString();
     }
     async function refresh(reset = false) {
-        if (!authenticated || busy) return;
+        if (!authenticated) return;
         if (reset) offset = 0;
+        if (busy) { pendingRefresh = true; return; }
         busy = true; $("file-logs-refresh").disabled = true;
         try {
             if (!inventory) await loadInventory();
@@ -289,10 +308,11 @@
             $("file-logs-prev").disabled = offset === 0;
             $("file-logs-next").disabled = offset + currentLimit() >= lastTotal;
         } catch (error) { toast(error.message, true); }
-        finally { busy = false; $("file-logs-refresh").disabled = false; }
+        finally { busy = false; $("file-logs-refresh").disabled = false; if (pendingRefresh) { pendingRefresh = false; void refresh(); } }
     }
     function reset() {
         inventory = null; offset = 0; lastTotal = 0; currentEntries = []; selectedIndex = null; aggregateField = "";
+        sortBy = "time"; sortDescending = true; pendingRefresh = false;
         preferencesLoaded = false; preferenceSaveRunning = false; preferenceSaveQueued = false;
         availableColumns = new Set(defaultColumnIds); visibleColumns = new Set(defaultColumnIds);
         sourceSelect().replaceChildren(Object.assign(el("option", t("fileLogsAllSources")), { value: "all" }));

src/admin/web/status_200.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>200 - OK - RustProxy</title>
+    <style>
+        body {
+            margin: 12vh auto;
+            padding: 24px;
+            max-width: 620px;
+            background: #131615;
+            color: #e5e9e6;
+            font: 15px/1.6 system-ui, sans-serif
+        }
+
+        h1 {
+            font-size: 24px;
+            margin: 0 0 8px
+        }
+
+        p {
+            margin: 0;
+            color: #b9c3bc
+        }
+    </style>
+</head>
+
+<body>
+    <main>
+        <h1>200 - OK</h1>
+        <p>The request completed successfully.</p>
+    </main>
+</body>
+
+</html>

src/admin/web/style.css

@@ -8692,6 +8692,25 @@ button.config-history-day.is-selected {
     box-shadow: 0 1px 0 var(--line);
 }
 
+/* Stored Logs sorting is performed by the bounded server scan before pagination. */
+.file-logs-table th .file-log-sort-button {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 3px 2px;
+    font: inherit;
+    font-weight: inherit;
+    color: inherit;
+    border: 0;
+    background: transparent;
+    cursor: pointer;
+    text-align: left;
+}
+.file-logs-table th .file-log-sort-button:hover { color: var(--accent); }
+.file-logs-table th[aria-sort="ascending"] .file-log-sort-button,
+.file-logs-table th[aria-sort="descending"] .file-log-sort-button { color: var(--accent); }
+.file-logs-table .file-log-sort-indicator { font-size: 11px; opacity: .8; }
+
 .file-logs-table tbody tr:not(.file-log-detail-row) {
     cursor: pointer;
 }

src/balance/tests.rs

@@ -1,4 +1,643 @@
 mod tests {
-    include!("tests/part_01.rs");
-    include!("tests/part_02.rs");
+use super::*;
+fn settings(mode: HealthMode) -> HealthCheck {
+    HealthCheck {
+        mode,
+        fall: 2,
+        rise: 2,
+        ..Default::default()
+    }
+}
+fn pool(algorithm: Algorithm, sticky: StickyMode) -> Arc<Pool> {
+    let cfg = serde_json::from_value(serde_json::json!({
+            "listeners":{"endpoints":[{"id":"http","binding":{"address":"127.0.0.1:8080"}}]},
+            "vhosts":[{
+            "id":"app","frontend":{"hosts":["app.localhost"],"listener_ids":["http"]},
+            "backends":[{"id":"a","url":"http://127.0.0.1:9000","allow_private":true,"weight":3},
+                {"id":"b","url":"http://127.0.0.1:9001","allow_private":true,"weight":1}],
+            "load_balancing":{"algorithm":algorithm,"sticky":{"mode":sticky},"slow_start_seconds":0,"health_check":{"mode":"off"}}
+        }]})).unwrap();
+    let policy = crate::config::ValidationPolicy {
+        proxy_addr: "127.0.0.1:8080".parse().unwrap(),
+        admin_addr: "127.0.0.1:9090".parse().unwrap(),
+        tls_addr: None,
+        cert_dir: None,
+        data_dir: None,
+    };
+    crate::config::compile(cfg, 0, &policy).unwrap().pools[0].clone()
+}
+fn capacity_pool(limit: u32, queue_timeout_ms: u64) -> Arc<Pool> {
+    let cfg = serde_json::from_value(serde_json::json!({
+        "listeners":{"endpoints":[{"id":"http","binding":{"address":"127.0.0.1:8080"}}]},
+        "vhosts":[{
+            "id":"limited","frontend":{"hosts":["limited.localhost"],"listener_ids":["http"]},
+            "backends":[{
+                "id":"only","url":"http://127.0.0.1:9000","allow_private":true,
+                "max_concurrent_requests":limit,"queue_timeout_ms":queue_timeout_ms
+            }],
+            "load_balancing":{"health_check":{"mode":"off"}}
+        }]
+    }))
+    .unwrap();
+    let policy = crate::config::ValidationPolicy {
+        proxy_addr: "127.0.0.1:8080".parse().unwrap(),
+        admin_addr: "127.0.0.1:9090".parse().unwrap(),
+        tls_addr: None,
+        cert_dir: None,
+        data_dir: None,
+    };
+    crate::config::compile(cfg, 0, &policy).unwrap().pools[0].clone()
+}
+fn select(pool: &Pool) -> Selection {
+    pool.select("127.0.0.1".parse().unwrap(), &HeaderMap::new(), false)
+        .unwrap()
+}
+#[test]
+fn per_backend_monitoring_can_be_disabled_or_overridden() {
+    let mut defaults: crate::vhost::PoolMember = serde_json::from_value(serde_json::json!({
+        "id": "error_404", "url": "http://127.0.0.1:8282", "pool_eligible": false
+    })).unwrap();
+    let mut settings = Settings::default();
+    settings.passive_health.enabled = true;
+    assert!(defaults.health_check_enabled);
+    assert_eq!(settings.health_for(&defaults).mode, HealthMode::Tcp);
+    assert!(settings.passive_for(&defaults).enabled);
+    defaults.health_check_enabled = false;
+    assert_eq!(settings.health_for(&defaults).mode, HealthMode::Off);
+    assert!(!settings.passive_for(&defaults).enabled);
+    assert!(!defaults.pool_eligible); // routing intent is independent
+    defaults.health_check_enabled = true;
+    defaults.health_check = Some(HealthCheck { mode: HealthMode::Http, path: "/healthz".into(), ..Default::default() });
+    let effective = settings.health_for(&defaults);
+    assert_eq!(effective.mode, HealthMode::Http);
+    assert_eq!(effective.path, "/healthz");
+    assert_eq!(effective.host, settings.health_check.host);
+    let restored: crate::vhost::PoolMember = serde_json::from_str(&serde_json::to_string(&defaults).unwrap()).unwrap();
+    assert_eq!(settings.health_for(&restored).path, "/healthz");
+}
+#[test]
+fn default_health_check_uses_tcp() {
+    assert_eq!(HealthMode::default(), HealthMode::Tcp);
+    assert_eq!(HealthCheck::default().mode, HealthMode::Tcp);
+}
+#[test]
+fn legacy_settings_without_passive_health_default_to_off() {
+    let parsed: Settings = serde_json::from_value(serde_json::json!({
+        "health_check": { "mode": "off" }
+    }))
+    .unwrap();
+    assert!(!parsed.passive_health.enabled);
+    assert!(parsed.passive_health.count_connect_errors);
+    assert!(parsed.passive_health.count_timeouts);
+    assert!(parsed.passive_health.count_io_errors);
+    assert!(parsed.passive_health.count_http_5xx);
+    assert!(!parsed.passive_health.count_slow_responses);
+    assert_eq!(parsed.retry.max_retries, 1);
+    assert!(parsed.retry.retry_connect_errors);
+    assert!(parsed.retry.retry_timeouts);
+    assert_eq!(parsed.retry.retry_statuses, vec![502, 503, 504]);
+    assert_eq!(parsed.keepalive.pool_recycle_requests, 25_000);
+    assert_eq!(parsed.keepalive.pool_recycle_seconds, 3_600);
+    assert_eq!(parsed.keepalive.http1_max_buffer_bytes, 131_072);
+}
+
+#[test]
+fn upstream_pool_recycle_limits_are_bounded_and_can_be_disabled() {
+    let mut settings = Settings::default();
+    assert!(settings.validate().is_ok());
+
+    settings.keepalive.pool_recycle_requests = 0;
+    settings.keepalive.pool_recycle_seconds = 0;
+    assert!(settings.validate().is_ok());
+
+    settings.keepalive.pool_recycle_requests = 999;
+    assert!(settings.validate().is_err());
+    settings.keepalive.pool_recycle_requests = 1_000;
+    settings.keepalive.pool_recycle_seconds = 59;
+    assert!(settings.validate().is_err());
+    settings.keepalive.pool_recycle_seconds = 60;
+    settings.keepalive.http1_max_buffer_bytes = 8_191;
+    assert!(settings.validate().is_err());
+    settings.keepalive.http1_max_buffer_bytes = 8_192;
+    assert!(settings.validate().is_ok());
+}
+
+#[test]
+fn compatible_pool_rebuild_reuses_upstream_clients() {
+    let previous = pool(Algorithm::LeastConnections, StickyMode::Off);
+    let mut rebuilt = pool(Algorithm::LeastConnections, StickyMode::Off);
+    let rebuilt_mut = Arc::get_mut(&mut rebuilt).expect("fresh pool must be uniquely owned");
+
+    assert!(!Arc::ptr_eq(
+        &rebuilt_mut.members[0].backend,
+        &previous.members[0].backend
+    ));
+    rebuilt_mut.reuse_observations(&previous);
+    assert!(Arc::ptr_eq(
+        &rebuilt_mut.members[0].backend,
+        &previous.members[0].backend
+    ));
+}
+
+#[test]
+fn retry_policy_rejects_unbounded_or_non_5xx_configuration() {
+    let mut settings = Settings::default();
+    settings.retry.max_retries = 4;
+    assert!(settings.validate().is_err());
+    settings.retry.max_retries = 1;
+    settings.retry.retry_statuses = vec![429];
+    assert!(settings.validate().is_err());
+}
+
+#[test]
+fn traffic_rate_drops_to_zero_after_an_idle_sample_window() {
+    let state = BackendState::new(HealthMode::Off);
+    state
+        .bytes_out
+        .store(2048, std::sync::atomic::Ordering::Relaxed);
+    lock(&state.traffic).at = std::time::Instant::now() - std::time::Duration::from_secs(2);
+    state.sample_traffic();
+    assert!(state.traffic_rate() > 0.0);
+    lock(&state.traffic).at = std::time::Instant::now() - std::time::Duration::from_secs(2);
+    state.sample_traffic();
+    assert_eq!(state.traffic_rate(), 0.0);
+}
+#[test]
+fn active_failures_are_independent_from_passive_user_traffic() {
+    let state = BackendState::new(HealthMode::Http);
+    let settings = settings(HealthMode::Http);
+    let passive = PassiveHealth::default();
+    let fast = Duration::from_millis(5);
+    assert!(!state.healthy());
+    state.observe_active(&settings, "ok", fast);
+    assert!(!state.healthy());
+    state.observe_active(&settings, "ok", fast);
+    assert!(state.healthy());
+    state.observe_active(&settings, "status", fast);
+    state.observe_passive(&settings, &passive, "ok", fast);
+    state.observe_active(&settings, "status", fast);
+    assert!(!state.healthy());
+    state.observe_passive(&settings, &passive, "http_5xx", fast);
+    assert!(!state.healthy());
+    state.observe_active(&settings, "ok", fast);
+    assert!(!state.healthy());
+    state.observe_active(&settings, "ok", fast);
+    assert!(state.healthy());
+}
+
+#[test]
+fn passive_health_is_opt_in_and_uses_separate_thresholds() {
+    let state = BackendState::new(HealthMode::Off);
+    let active = settings(HealthMode::Off);
+    let fast = Duration::from_millis(5);
+    for _ in 0..10 {
+        state.observe_passive(&active, &PassiveHealth::default(), "http_5xx", fast);
+    }
+    assert!(state.healthy());
+    assert_eq!(state.http_5xx_total.load(Ordering::Relaxed), 10);
+    assert_eq!(
+        state.passive_health_failures_total.load(Ordering::Relaxed),
+        0
+    );
+
+    let passive = PassiveHealth {
+        enabled: true,
+        fall: Some(2),
+        rise: Some(2),
+        ..Default::default()
+    };
+    state.observe_passive(&active, &passive, "http_5xx", fast);
+    assert!(state.healthy());
+    state.observe_passive(&active, &passive, "http_5xx", fast);
+    assert!(!state.healthy());
+    state.observe_passive(&active, &passive, "ok", fast);
+    assert!(!state.healthy());
+    state.observe_passive(&active, &passive, "ok", fast);
+    assert!(state.healthy());
+}
+#[test]
+fn passive_http_5xx_can_be_explicitly_ignored_when_passive_health_is_on() {
+    let state = BackendState::new(HealthMode::Off);
+    let active = settings(HealthMode::Off);
+    let passive = PassiveHealth {
+        enabled: true,
+        count_http_5xx: false,
+        fall: Some(1),
+        ..Default::default()
+    };
+    for _ in 0..100 {
+        state.observe_passive(&active, &passive, "http_5xx", Duration::from_millis(5));
+    }
+    assert!(state.healthy());
+    assert_eq!(state.http_5xx_total.load(Ordering::Relaxed), 100);
+    assert_eq!(
+        state.passive_health_failures_total.load(Ordering::Relaxed),
+        0
+    );
+}
+
+#[test]
+fn passive_connect_errors_use_the_explicit_fall_threshold() {
+    let state = BackendState::new(HealthMode::Off);
+    let active = settings(HealthMode::Off);
+    let passive = PassiveHealth {
+        enabled: true,
+        count_connect_errors: true,
+        fall: Some(3),
+        ..Default::default()
+    };
+    for _ in 0..2 {
+        state.observe_passive(&active, &passive, "connect_error", Duration::from_millis(5));
+        assert!(state.healthy());
+    }
+    state.observe_passive(&active, &passive, "connect_error", Duration::from_millis(5));
+    assert!(!state.healthy());
+    assert_eq!(state.connect_errors_total.load(Ordering::Relaxed), 3);
+    assert_eq!(
+        state.passive_health_failures_total.load(Ordering::Relaxed),
+        3
+    );
+}
+
+#[test]
+fn active_health_can_stay_healthy_while_passive_health_is_off() {
+    let state = BackendState::new(HealthMode::Tcp);
+    let active = settings(HealthMode::Tcp);
+    let passive = PassiveHealth::default();
+    let fast = Duration::from_millis(5);
+    state.observe_active(&active, "ok", fast);
+    state.observe_active(&active, "ok", fast);
+    assert!(state.healthy());
+    for _ in 0..20 {
+        state.observe_passive(&active, &passive, "http_5xx", fast);
+    }
+    assert!(state.healthy());
+    assert_eq!(state.http_5xx_total.load(Ordering::Relaxed), 20);
+    assert_eq!(
+        state.passive_health_failures_total.load(Ordering::Relaxed),
+        0
+    );
+}
+
+#[test]
+fn unhealthy_source_hands_off_when_the_original_health_domain_recovers() {
+    let state = BackendState::new(HealthMode::Tcp);
+    let active = HealthCheck {
+        fall: 1,
+        rise: 1,
+        ..settings(HealthMode::Tcp)
+    };
+    let passive = PassiveHealth {
+        enabled: true,
+        count_http_5xx: true,
+        fall: Some(1),
+        rise: Some(1),
+        ..Default::default()
+    };
+    let fast = Duration::from_millis(5);
+
+    state.observe_active(&active, "ok", fast);
+    state.observe_active(&active, "connect_error", fast);
+    {
+        let health = lock(&state.health);
+        assert_eq!(health.unhealthy_source, "active_tcp");
+    }
+    state.observe_passive(&active, &passive, "http_5xx", fast);
+    state.observe_active(&active, "ok", fast);
+    {
+        let health = lock(&state.health);
+        assert!(!health.healthy);
+        assert_eq!(health.unhealthy_source, "passive_http_5xx");
+        assert_eq!(health.unhealthy_reason, "http_5xx");
+    }
+    state.observe_passive(&active, &passive, "ok", fast);
+    assert!(state.healthy());
+}
+
+#[test]
+fn disabled_checks_never_quarantine_and_probes_are_single_flight() {
+    let off = BackendState::new(HealthMode::Off);
+    let settings = settings(HealthMode::Off);
+    for _ in 0..5 {
+        off.observe_passive(
+            &settings,
+            &PassiveHealth::default(),
+            "connect_error",
+            Duration::ZERO,
+        );
+    }
+    assert!(off.healthy());
+    assert!(!off.claim_probe(&settings));
+    let on = BackendState::new(HealthMode::Http);
+    let settings = super::tests::settings(HealthMode::Http);
+    assert!(on.claim_probe(&settings));
+    assert!(!on.claim_probe(&settings));
+    on.observe_active(&settings, "ok", Duration::ZERO);
+    assert!(!on.claim_probe(&settings));
+}
+#[tokio::test]
+async fn weighted_round_robin_distributes_three_to_one_without_body_collection() {
+    let pool = pool(Algorithm::RoundRobin, StickyMode::Off);
+    let mut counts = [0, 0];
+    for _ in 0..40 {
+        let selection = select(&pool);
+        counts[usize::from(selection.lease.member.definition.id == "b")] += 1;
+    }
+    assert_eq!(counts, [30, 10]);
+    assert_eq!(pool.members[0].state.active.load(Ordering::Relaxed), 0);
+    assert_eq!(pool.members[0].state.requests.load(Ordering::Relaxed), 0); // Mere cache selection isn't origin traffic.
+}
+#[tokio::test]
+async fn least_connections_counts_a_lease_until_its_last_owner_drops() {
+    let pool = pool(Algorithm::LeastConnections, StickyMode::Off);
+    let mut held = Vec::new();
+    for _ in 0..3 {
+        let selection = select(&pool);
+        assert_eq!(selection.lease.member.definition.id, "a");
+        held.push(selection.lease);
+    }
+    let other = select(&pool);
+    assert_eq!(other.lease.member.definition.id, "b");
+    let clone = held[0].clone();
+    held.clear();
+    assert_eq!(pool.members[0].state.active.load(Ordering::Relaxed), 1);
+    drop(clone);
+    assert_eq!(pool.members[0].state.active.load(Ordering::Relaxed), 0);
+}
+#[tokio::test]
+async fn failover_selection_never_reuses_an_attempted_backend() {
+    let pool = pool(Algorithm::LeastConnections, StickyMode::Off);
+    let first = select(&pool);
+    let first_id = first.lease.member.definition.id.clone();
+    drop(first);
+    let retry = pool
+        .select_retry(
+            "127.0.0.1".parse().unwrap(),
+            &HeaderMap::new(),
+            false,
+            std::slice::from_ref(&first_id),
+        )
+        .unwrap();
+    assert_ne!(retry.lease.member.definition.id, first_id);
+}
+#[tokio::test]
+async fn backend_concurrency_limit_queues_then_rejects_and_recovers() {
+    let pool = capacity_pool(1, 10);
+    let first = select(&pool);
+    let headers = HeaderMap::new();
+    let saturated = pool
+        .select_wait("127.0.0.1".parse().unwrap(), &headers, false)
+        .await;
+    assert!(matches!(saturated, Err(SelectionFailure::Capacity)));
+    let view = pool.view();
+    let member = &view["members"][0];
+    assert_eq!(member["capacity_rejections_total"], 1);
+    assert_eq!(member["queue_timeouts_total"], 1);
+    assert_eq!(member["active"], 1);
+    drop(first);
+    assert!(pool
+        .select_wait("127.0.0.1".parse().unwrap(), &headers, false)
+        .await
+        .is_ok());
+}
+
+#[tokio::test]
+async fn zero_capacity_queue_timeout_rejects_without_counting_a_queue_timeout() {
+    let pool = capacity_pool(1, 0);
+    let first = select(&pool);
+    let headers = HeaderMap::new();
+    let saturated = pool
+        .select_wait("127.0.0.1".parse().unwrap(), &headers, false)
+        .await;
+    assert!(matches!(saturated, Err(SelectionFailure::Capacity)));
+    let view = pool.view();
+    let member = &view["members"][0];
+    assert_eq!(member["capacity_rejections_total"], 1);
+    assert_eq!(member["queue_timeouts_total"], 0);
+    drop(first);
+}
+
+#[test]
+fn detailed_backend_failures_are_exposed_without_losing_aggregate_counters() {
+    let pool = capacity_pool(0, 0);
+    let selection = select(&pool);
+    selection.lease.error_detail(
+        "dns",
+        "lookup backend.example failed",
+        Duration::from_millis(7),
+    );
+    let view = pool.view();
+    let member = &view["members"][0];
+    assert_eq!(member["dns_errors_total"], 1);
+    assert_eq!(member["connect_errors_total"], 1);
+    assert_eq!(member["last_failure_class"], "dns");
+    assert_eq!(
+        member["last_failure_detail"],
+        "lookup backend.example failed"
+    );
+    assert!(member["last_failure_at_ms"].as_u64().unwrap_or_default() > 0);
+}
+#[tokio::test]
+async fn traffic_and_adaptive_selection_use_observed_cost_and_weight() {
+    for algorithm in [Algorithm::LeastTraffic, Algorithm::Adaptive] {
+        let pool = pool(algorithm, StickyMode::Off);
+        lock(&pool.members[0].state.traffic).rate = 50_000_000.0;
+        lock(&pool.members[0].state.health).ewma_us = 1_000_000;
+        assert_eq!(select(&pool).lease.member.definition.id, "b");
+    }
+}
+#[tokio::test]
+async fn ip_hash_is_stable_and_cannot_be_spoofed_with_forwarded_headers() {
+    let pool = pool(Algorithm::IpHash, StickyMode::Off);
+    let original = select(&pool).lease.member.definition.id.clone();
+    let mut headers = HeaderMap::new();
+    headers.insert("x-forwarded-for", "10.0.0.99".parse().unwrap());
+    for ip in ["127.0.0.1", "::ffff:127.0.0.1"] {
+        for _ in 0..8 {
+            assert_eq!(
+                pool.select(ip.parse().unwrap(), &headers, false)
+                    .unwrap()
+                    .lease
+                    .member
+                    .definition
+                    .id,
+                original
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn opaque_cookie_is_removed_from_origin_requests_and_protected_on_responses() {
+    let pool = pool(Algorithm::RoundRobin, StickyMode::Cookie);
+    let first = select(&pool);
+    let cookie = first.cookie.unwrap().to_str().unwrap().to_owned();
+    assert!(
+        cookie.contains("HttpOnly")
+            && cookie.contains("SameSite=Lax")
+            && !cookie.contains("Secure")
+    );
+    let cookie = cookie.split(';').next().unwrap();
+    let mut headers = HeaderMap::new();
+    headers.insert("cookie", format!("{cookie}; app=ok").parse().unwrap());
+    let next = pool
+        .select("10.0.0.1".parse().unwrap(), &headers, false)
+        .unwrap();
+    assert_eq!(
+        next.lease.member.definition.id,
+        first.lease.member.definition.id
+    );
+    assert!(next.cookie.is_none());
+    pool.strip_affinity(&mut headers);
+    assert_eq!(headers["cookie"], "app=ok");
+    headers.append(
+        "set-cookie",
+        format!("{}=origin-spoof", pool.cookie_name)
+            .parse()
+            .unwrap(),
+    );
+    headers.append("set-cookie", "app=ok".parse().unwrap());
+    pool.strip_affinity_response(&mut headers);
+    assert_eq!(headers.get_all("set-cookie").iter().count(), 1);
+    assert_eq!(headers["set-cookie"], "app=ok");
+    let secure = pool
+        .select("127.0.0.1".parse().unwrap(), &HeaderMap::new(), true)
+        .unwrap();
+    assert!(secure
+        .cookie
+        .unwrap()
+        .to_str()
+        .unwrap()
+        .contains("; Secure"));
+}
+#[tokio::test]
+async fn failed_sticky_member_is_replaced_and_duplicate_cookies_are_ignored() {
+    let pool = pool(Algorithm::RoundRobin, StickyMode::Cookie);
+    let first = select(&pool);
+    let cookie = first
+        .cookie
+        .unwrap()
+        .to_str()
+        .unwrap()
+        .split(';')
+        .next()
+        .unwrap()
+        .to_owned();
+    let mut headers = HeaderMap::new();
+    headers.insert("cookie", format!("{cookie}; {cookie}").parse().unwrap());
+    assert!(pool.affinity(&headers).is_none());
+    headers.insert("cookie", cookie.parse().unwrap());
+    lock(&first.lease.member.state.health).healthy = false;
+    let next = pool
+        .select("127.0.0.1".parse().unwrap(), &headers, false)
+        .unwrap();
+    assert_ne!(
+        next.lease.member.definition.id,
+        first.lease.member.definition.id
+    );
+    assert!(next.cookie.is_some());
+    lock(&next.lease.member.state.health).healthy = false;
+    assert!(pool
+        .select("127.0.0.1".parse().unwrap(), &headers, false)
+        .is_none());
+}
+#[tokio::test]
+async fn slow_start_ramps_weight_and_error_is_counted_once_per_exchange() {
+    let pool = pool(Algorithm::LeastConnections, StickyMode::Off);
+    let selected = select(&pool);
+    let state = &selected.lease.member.state;
+    assert!(state.weight(100, 100) < 100.0);
+    assert_eq!(state.weight(100, 0), 100.0);
+    selected.lease.started();
+    selected.lease.bytes(50, true);
+    selected.lease.bytes(100, false);
+    selected.lease.error("timeout", Duration::from_secs(1));
+    selected.lease.error("body", Duration::from_secs(2));
+    selected.lease.retry_attempted();
+    selected.lease.retry_succeeded();
+    assert_eq!(state.requests.load(Ordering::Relaxed), 1);
+    assert_eq!(state.errors.load(Ordering::Relaxed), 1);
+    assert_eq!(state.timeouts_total.load(Ordering::Relaxed), 1);
+    assert_eq!(state.io_errors_total.load(Ordering::Relaxed), 1);
+    assert_eq!(state.bytes_in.load(Ordering::Relaxed), 50);
+    assert_eq!(state.bytes_out.load(Ordering::Relaxed), 100);
+    assert_eq!(state.retry_attempts_total.load(Ordering::Relaxed), 1);
+    assert_eq!(state.retry_successes_total.load(Ordering::Relaxed), 1);
+    assert!(pool
+        .prometheus()
+        .contains("rust_proxy_backend_requests_total{vhost=\"app\",backend=\"a\"} 1"));
+    assert!(pool
+        .prometheus()
+        .contains("rust_proxy_backend_retry_attempts_total{vhost=\"app\",backend=\"a\"} 1"));
+}
+#[tokio::test]
+async fn slow_5xx_counts_both_observability_classes_when_passive_is_off() {
+    let pool = pool(Algorithm::LeastConnections, StickyMode::Off);
+    let selected = select(&pool);
+    selected.lease.response(500, Duration::from_secs(20), true);
+    let state = &selected.lease.member.state;
+    assert_eq!(state.http_5xx_total.load(Ordering::Relaxed), 1);
+    assert_eq!(state.slow_responses_total.load(Ordering::Relaxed), 1);
+    assert_eq!(
+        state.passive_health_failures_total.load(Ordering::Relaxed),
+        0
+    );
+    assert!(state.healthy());
+}
+
+#[tokio::test]
+async fn client_upload_duration_does_not_trigger_passive_slow_failure() {
+    let pool = pool(Algorithm::LeastConnections, StickyMode::Off);
+    let upload = select(&pool);
+    upload.lease.response(200, Duration::from_secs(20), false);
+    assert_eq!(upload.lease.member.state.errors.load(Ordering::Relaxed), 0);
+    let read = select(&pool);
+    read.lease.response(200, Duration::from_secs(20), true);
+    assert_eq!(read.lease.member.state.errors.load(Ordering::Relaxed), 1);
+}
+#[tokio::test]
+async fn backup_is_only_new_assignment_when_no_primary_is_eligible() {
+    let mut pool = pool(Algorithm::RoundRobin, StickyMode::Off);
+    Arc::get_mut(&mut Arc::get_mut(&mut pool).unwrap().members[1])
+        .unwrap()
+        .definition
+        .backup = true;
+    for _ in 0..8 {
+        assert_eq!(select(&pool).lease.member.definition.id, "a");
+    }
+    lock(&pool.members[0].state.health).healthy = false;
+    assert_eq!(select(&pool).lease.member.definition.id, "b");
+    lock(&pool.members[0].state.health).healthy = true;
+    assert_eq!(select(&pool).lease.member.definition.id, "a");
+}
+#[tokio::test]
+async fn drain_rejects_new_sessions_but_preserves_valid_existing_affinity() {
+    let mut pool = pool(Algorithm::RoundRobin, StickyMode::Cookie);
+    Arc::get_mut(&mut Arc::get_mut(&mut pool).unwrap().members[0])
+        .unwrap()
+        .definition
+        .drain = true;
+    assert_eq!(select(&pool).lease.member.definition.id, "b");
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        "cookie",
+        format!("{}={}", pool.cookie_name, pool.members[0].token)
+            .parse()
+            .unwrap(),
+    );
+    let existing = pool
+        .select("127.0.0.1".parse().unwrap(), &headers, false)
+        .unwrap();
+    assert_eq!(existing.lease.member.definition.id, "a");
+    lock(&pool.members[0].state.health).healthy = false;
+    assert_eq!(
+        pool.select("127.0.0.1".parse().unwrap(), &headers, false)
+            .unwrap()
+            .lease
+            .member
+            .definition
+            .id,
+        "b"
+    );
+}
 }

src/cache/fill.rs

@@ -63,6 +63,10 @@ struct Candidate {
     plan: Plan,
     headers: HeaderMap,
     data: Vec<u8>,
+    // A transformed response with one uniquely owned Bytes frame can share its
+    // allocation with the downstream response, avoiding an extra Vec copy.
+    shared: Option<Bytes>,
+    shared_allocated: usize,
     fill_gauge: FillGauge,
     settings: Settings,
     skip_compression: bool,
@@ -77,7 +81,7 @@ impl Candidate {
         if self
             .plan
             .expected_length
-            .is_some_and(|length| self.data.len() != length)
+            .is_some_and(|length| self.shared.as_ref().map_or(self.data.len(), Bytes::len) != length)
         {
             let reason = if self.transformed {
                 "transform_length_mismatch"
@@ -112,8 +116,12 @@ impl Candidate {
         // Keep the actual backing capacity as the HOT charge. Vec::reserve_exact
         // avoids geometric multi-MiB overshoot while Bytes::from(Vec) transfers
         // the allocation without copying.
-        let body_allocation = self.data.capacity().max(self.data.len());
-        let body = Bytes::from(std::mem::take(&mut self.data));
+        let (body, body_allocation) = if let Some(body) = self.shared.take() {
+            (body, self.shared_allocated)
+        } else {
+            let allocated = self.data.capacity().max(self.data.len());
+            (Bytes::from(std::mem::take(&mut self.data)), allocated)
+        };
         let scope = self.ticket.scope.clone();
         let scheme = self.ticket.scheme.clone();
         let authority = self.ticket.authority.clone();
@@ -192,8 +200,51 @@ impl HttpBody for FillBody {
         let this = self.get_mut();
         match Pin::new(&mut this.inner).poll_frame(cx) {
             Poll::Ready(Some(Ok(frame))) => {
+                let mut frame = frame;
+                // Only the transformed single-frame case is eligible. Taking
+                // unique ownership lets Bytes reveal its true allocation
+                // capacity; we must never undercharge an arbitrary shared
+                // Bytes slice that could retain a much larger parent buffer.
+                if this.inner.is_end_stream() {
+                    if let Some(candidate) = &mut this.candidate {
+                        let single_frame = candidate.transformed
+                            && candidate.data.is_empty()
+                            && candidate.shared.is_none()
+                            && frame.data_ref().is_some_and(|data| {
+                                candidate.plan.expected_length == Some(data.len())
+                                    && data.len() <= candidate.settings.max_object_bytes
+                            });
+                        if single_frame {
+                            match frame.into_data() {
+                                Ok(bytes) => {
+                                    match bytes.try_into_mut() {
+                                        Ok(mutable) => {
+                                            let allocation = mutable.capacity();
+                                            let bytes = mutable.freeze();
+                                            // A very oversized backing Vec is cheaper to
+                                            // copy into a smaller HOT allocation instead.
+                                            let acceptable_spare = bytes.len().saturating_div(8).min(64 * 1024);
+                                            if allocation <= bytes.len().saturating_add(acceptable_spare)
+                                                && allocation <= candidate.settings.max_object_bytes
+                                                && candidate.fill_gauge.grow(allocation, &candidate.settings)
+                                            {
+                                                candidate.shared = Some(bytes.clone());
+                                                candidate.shared_allocated = allocation;
+                                            }
+                                            frame = Frame::data(bytes);
+                                        }
+                                        Err(bytes) => frame = Frame::data(bytes),
+                                    }
+                                }
+                                Err(original) => frame = original,
+                            }
+                        }
+                    }
+                }
                 if let Some(candidate) = &mut this.candidate {
-                    if let Some(data) = frame.data_ref() {
+                    if candidate.shared.is_some() {
+                        // The cache now owns the very same backing allocation.
+                    } else if let Some(data) = frame.data_ref() {
                         let needed = candidate.data.len().saturating_add(data.len());
                         if needed <= candidate.settings.max_object_bytes {
                             let before = candidate.data.capacity();

src/cache/lookup/tiered.rs

@@ -170,7 +170,10 @@ impl Cache {
             Some(validators) => validators.last_modified.clone(),
             None => headers.get("last-modified").cloned(),
         };
-        let initial_capacity = fill_size.min(64 * 1024);
+        let transformed = parts.extensions.get::<crate::transform::Applied>().is_some();
+        // A transformed, fully buffered body normally arrives as one owned
+        // frame. Do not allocate a second fill buffer before inspecting it.
+        let initial_capacity = if transformed { 0 } else { fill_size.min(64 * 1024) };
         let Some(mut fill_gauge) = FillGauge::new(self.clone(), initial_capacity, settings) else {
             self.counters.rejected_fills.fetch_add(1, Ordering::Relaxed);
             self.record_reason(&ticket.scope, &ticket.domain, "hot_memory_pressure");
@@ -191,15 +194,14 @@ impl Cache {
             plan,
             headers,
             data,
+            shared: None,
+            shared_allocated: 0,
             fill_gauge,
             settings: settings.clone(),
             skip_compression: parts.extensions.get::<crate::compression::Skip>().is_some(),
             origin_etag,
             origin_last_modified,
-            transformed: parts
-                .extensions
-                .get::<crate::transform::Applied>()
-                .is_some(),
+            transformed,
             _permit: permit,
             _fill_leader: fill_leader,
         };

src/cache/tests/cold_tier_tests.rs

@@ -1,4 +1,746 @@
 mod cold_tier_tests {
-    include!("cold_tier_tests/part_01.rs");
-    include!("cold_tier_tests/part_02.rs");
+use super::*;
+use http_body_util::BodyExt;
+
+fn cold_settings() -> Settings {
+    Settings {
+        enabled: true,
+        max_entries: 1,
+        max_bytes: 256 * 1024,
+        max_object_bytes: 64 * 1024,
+        cold_enabled: true,
+        cold_path: "cache/cold-test".into(),
+        cold_max_bytes: 2 * 1024 * 1024,
+        cold_max_entries: 16,
+        cold_after_seconds: 300,
+        ..Settings::default()
+    }
+}
+
+async fn fill(cache: &Arc<Cache>, settings: &Settings, path: &str, body: &'static str) -> Ticket {
+    let ticket = cache
+        .ticket_scoped(
+            11,
+            "cold-test",
+            "http",
+            "cold.example",
+            "origin@127.0.0.1:8080",
+            path,
+            &HeaderMap::new(),
+        )
+        .unwrap();
+    let mut response = Response::new(Body::from(body));
+    response.headers_mut().insert(
+        "cache-control",
+        HeaderValue::from_static("public, max-age=120"),
+    );
+    response
+        .headers_mut()
+        .insert("etag", HeaderValue::from_static("\"cold-v1\""));
+    let plan = plan(StatusCode::OK, response.headers(), settings, Duration::ZERO).unwrap();
+    cache
+        .wrap(response, ticket.clone(), plan, settings)
+        .into_body()
+        .collect()
+        .await
+        .unwrap();
+    ticket
+}
+
+async fn wait_for_cold(cache: &Cache, expected: usize) {
+    for _ in 0..100 {
+        if cache.view().cold_entries >= expected {
+            return;
+        }
+        tokio::time::sleep(Duration::from_millis(10)).await;
+    }
+    panic!("cold tier did not persist in time");
+}
+
+#[tokio::test]
+async fn selective_purge_removes_matching_cold_object() {
+    let dir = tempfile::tempdir().unwrap();
+    let settings = cold_settings();
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    let first = fill(&cache, &settings, "/one?v=1", "first-payload").await;
+    let _second = fill(&cache, &settings, "/two", "second-payload").await;
+    wait_for_cold(&cache, 1).await;
+    assert_eq!(cache.view().cold_entries, 1);
+    let result = cache
+        .invalidate(InvalidationRequest {
+            operation: InvalidationOperation::Purge,
+            selector: InvalidationSelector::Exact,
+            value: "/one?v=1".into(),
+            host: Some("cold.example".into()),
+            vhost: Some("cold-test".into()),
+            ttl_seconds: None,
+            confirm_wide: false,
+        })
+        .unwrap();
+    assert_eq!(result.affected_entries, 1);
+    assert_eq!(cache.view().cold_entries, 0);
+    assert!(cache.get_tiered(&first, &settings).await.is_none());
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn lru_demotion_persists_and_survives_restart() {
+    let dir = tempfile::tempdir().unwrap();
+    let settings = cold_settings();
+    settings.validate().unwrap();
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    let first = fill(&cache, &settings, "/one", "first-payload").await;
+    let _second = fill(&cache, &settings, "/two", "second-payload").await;
+    wait_for_cold(&cache, 1).await;
+    assert_eq!(cache.view().entries, 1);
+    assert_eq!(cache.view().cold_entries, 1);
+    let cold = cache.dashboard(Some("cold-test"), 0, 50);
+    assert!(cold
+        .objects
+        .iter()
+        .any(|row| row.path == "/one" && row.tier == "cold"));
+
+    shutdown.cancel();
+    drop(cache);
+
+    let restart_shutdown = CancellationToken::new();
+    let restarted = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        restart_shutdown.clone(),
+    );
+    assert_eq!(restarted.view().cold_entries, 1);
+    let hit = restarted
+        .get_tiered(&first, &settings)
+        .await
+        .expect("cold object should be readable after restart");
+    let payload = hit.response.into_body().collect().await.unwrap().to_bytes();
+    assert_eq!(payload, Bytes::from_static(b"first-payload"));
+    assert_eq!(restarted.view().cold_hits, 1);
+    assert_eq!(restarted.view().cold_promotions, 1);
+    restart_shutdown.cancel();
+}
+
+#[tokio::test]
+async fn cold_restart_preserves_transformed_validators_stale_metadata_and_no_transform() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.max_entries = 8;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+
+    let transformed_ticket = cache
+        .ticket_scoped(
+            11,
+            "cold-test",
+            "http",
+            "cold.example",
+            "origin@127.0.0.1:8080",
+            "/transformed.json",
+            &HeaderMap::new(),
+        )
+        .unwrap();
+    let mut transformed = Response::new(Body::from(r#"{"a":1}"#));
+    transformed.headers_mut().insert(
+        "cache-control",
+        HeaderValue::from_static(
+            "public, max-age=120, stale-while-revalidate=30, stale-if-error=90",
+        ),
+    );
+    transformed.headers_mut().insert(
+        "etag",
+        HeaderValue::from_static("\"rustproxy-representation\""),
+    );
+    transformed
+        .headers_mut()
+        .insert("content-length", HeaderValue::from_static("7"));
+    transformed
+        .extensions_mut()
+        .insert(crate::transform::OriginValidators {
+            etag: Some(HeaderValue::from_static("\"origin-v1\"")),
+            last_modified: Some(HeaderValue::from_static("Mon, 26 Jan 2026 23:11:40 GMT")),
+        });
+    transformed
+        .extensions_mut()
+        .insert(crate::transform::Applied {
+            kind: crate::transform::Kind::Json,
+            original_bytes: 9,
+            transformed_bytes: 7,
+        });
+    let transformed_plan = plan(
+        StatusCode::OK,
+        transformed.headers(),
+        &settings,
+        Duration::ZERO,
+    )
+    .unwrap();
+    cache
+        .wrap(
+            transformed,
+            transformed_ticket.clone(),
+            transformed_plan,
+            &settings,
+        )
+        .into_body()
+        .collect()
+        .await
+        .unwrap();
+
+    let protected_ticket = cache
+        .ticket_scoped(
+            11,
+            "cold-test",
+            "http",
+            "cold.example",
+            "origin@127.0.0.1:8080",
+            "/protected.css",
+            &HeaderMap::new(),
+        )
+        .unwrap();
+    let original_body = "body { color: red; }";
+    let mut protected = Response::new(Body::from(original_body));
+    protected.headers_mut().insert(
+        "cache-control",
+        HeaderValue::from_static("public, max-age=120, immutable, no-transform"),
+    );
+    protected
+        .headers_mut()
+        .insert("etag", HeaderValue::from_static("\"origin-css\""));
+    protected.extensions_mut().insert(crate::compression::Skip);
+    let protected_plan = plan(
+        StatusCode::OK,
+        protected.headers(),
+        &settings,
+        Duration::ZERO,
+    )
+    .unwrap();
+    cache
+        .wrap(
+            protected,
+            protected_ticket.clone(),
+            protected_plan,
+            &settings,
+        )
+        .into_body()
+        .collect()
+        .await
+        .unwrap();
+
+    assert_eq!(cache.flush_hot_to_cold().await, 2);
+    wait_for_cold(&cache, 2).await;
+    shutdown.cancel();
+    drop(cache);
+
+    let restart_shutdown = CancellationToken::new();
+    let restarted = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        restart_shutdown.clone(),
+    );
+    assert_eq!(restarted.view().cold_entries, 2);
+    // COLD entries intentionally keep validators and headers on disk to bound RAM.
+    // Inspect them through the same verified metadata loader used on COLD hits.
+    let (key, transformed) = {
+        let cold = restarted.cold.lock().unwrap();
+        cold.entries
+            .iter()
+            .find(|(_, entry)| entry.path == "/transformed.json")
+            .map(|(key, entry)| (*key, entry.clone()))
+            .expect("transformed cold entry")
+    };
+    assert_eq!(transformed.stale_while_revalidate, 30);
+    assert_eq!(transformed.stale_if_error, 90);
+    assert!(transformed.has_validator);
+    assert!(transformed.transformed);
+    let metadata = read_cold_metadata(&key, &transformed)
+        .await
+        .expect("persisted transformed metadata");
+    assert_eq!(metadata.origin_etag.as_ref().unwrap(), "\"origin-v1\"");
+    assert_eq!(
+        metadata.origin_last_modified.as_ref().unwrap(),
+        "Mon, 26 Jan 2026 23:11:40 GMT"
+    );
+    assert_eq!(metadata.headers["etag"], "\"rustproxy-representation\"");
+
+    let transformed_hit = restarted
+        .get_tiered(&transformed_ticket, &settings)
+        .await
+        .expect("transformed object after restart");
+    assert_eq!(
+        transformed_hit.response.headers()["etag"],
+        "\"rustproxy-representation\""
+    );
+    assert!(transformed_hit.transformed);
+    assert!(transformed_hit
+        .response
+        .extensions()
+        .get::<crate::transform::CachedTransformed>()
+        .is_some());
+    assert_eq!(
+        transformed_hit
+            .response
+            .into_body()
+            .collect()
+            .await
+            .unwrap()
+            .to_bytes(),
+        Bytes::from_static(br#"{"a":1}"#)
+    );
+
+    let protected_hit = restarted
+        .get_tiered(&protected_ticket, &settings)
+        .await
+        .expect("no-transform object after restart");
+    assert_eq!(protected_hit.response.headers()["etag"], "\"origin-css\"");
+    assert!(crate::transform::no_transform(
+        protected_hit.response.headers()
+    ));
+    assert!(protected_hit
+        .response
+        .extensions()
+        .get::<crate::compression::Skip>()
+        .is_some());
+    assert_eq!(
+        protected_hit
+            .response
+            .into_body()
+            .collect()
+            .await
+            .unwrap()
+            .to_bytes(),
+        Bytes::from_static(b"body { color: red; }")
+    );
+    restart_shutdown.cancel();
+}
+
+#[tokio::test]
+async fn cold_policy_can_disable_lru_demotion() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.cold_on_lru = false;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/one", "first-payload").await;
+    fill(&cache, &settings, "/two", "second-payload").await;
+    tokio::time::sleep(Duration::from_millis(30)).await;
+    let view = cache.view();
+    assert_eq!(view.entries, 1);
+    assert_eq!(view.cold_entries, 0);
+    assert_eq!(view.evictions, 1);
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn cold_policy_can_disable_idle_demotion() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.max_entries = 8;
+    settings.cold_on_idle = false;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/idle", "idle-payload").await;
+    {
+        let mut store = cache.store.lock().unwrap();
+        for entry in store.entries.values_mut() {
+            entry.last_access = Instant::now() - Duration::from_secs(600);
+        }
+    }
+    cache.demote_idle();
+    assert_eq!(cache.view().entries, 1);
+    assert_eq!(cache.view().cold_entries, 0);
+
+    settings.cold_on_idle = true;
+    cache.configure(settings.clone());
+    cache.demote_idle();
+    wait_for_cold(&cache, 1).await;
+    assert_eq!(cache.view().entries, 0);
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn cold_policy_can_demote_by_total_hot_residency_age() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.max_entries = 8;
+    settings.cold_on_idle = false;
+    settings.cold_on_age = true;
+    settings.cold_max_hot_seconds = 5;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/aged", "aged-payload").await;
+    {
+        let mut store = cache.store.lock().unwrap();
+        for entry in store.entries.values_mut() {
+            entry.resident_since = Instant::now() - Duration::from_secs(60);
+            entry.last_access = Instant::now();
+        }
+    }
+    cache.demote_idle();
+    wait_for_cold(&cache, 1).await;
+    assert_eq!(cache.view().entries, 0);
+    assert_eq!(cache.view().cold_entries, 1);
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn graceful_shutdown_flush_moves_hot_objects_and_releases_resident_bytes() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.max_entries = 8;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/one", "first-payload").await;
+    fill(&cache, &settings, "/two", "second-payload").await;
+    assert_eq!(cache.view().entries, 2);
+    assert!(cache.view().resident_bytes > 0);
+    assert_eq!(cache.view().cold_entries, 0);
+
+    assert_eq!(cache.flush_hot_to_cold().await, 2);
+    let view = cache.view();
+    assert_eq!(view.entries, 0);
+    assert_eq!(view.resident_bytes, 0);
+    assert_eq!(view.hot_logical_bytes, 0);
+    assert_eq!(
+        view.transient_bytes, 0,
+        "persisted ColdEntry must not retain the body allocation"
+    );
+    assert_eq!(view.cold_entries, 2);
+    shutdown.cancel();
+
+    let restart_shutdown = CancellationToken::new();
+    let restarted = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        restart_shutdown.clone(),
+    );
+    assert_eq!(restarted.view().cold_entries, 2);
+    restart_shutdown.cancel();
+}
+
+#[tokio::test]
+async fn managed_update_flush_ignores_shutdown_toggle_when_cold_tier_is_enabled() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.max_entries = 8;
+    settings.cold_on_shutdown = false;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/update", "update-payload").await;
+    assert_eq!(cache.flush_hot_to_cold().await, 0);
+    assert_eq!(cache.view().entries, 1);
+    assert_eq!(cache.flush_hot_to_cold_for_update().await, 1);
+    let view = cache.view();
+    assert_eq!(view.entries, 0);
+    assert_eq!(view.resident_bytes, 0);
+    assert_eq!(view.cold_entries, 1);
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn graceful_shutdown_flush_can_be_disabled() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.max_entries = 8;
+    settings.cold_on_shutdown = false;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/one", "first-payload").await;
+    assert_eq!(cache.flush_hot_to_cold().await, 0);
+    assert_eq!(cache.view().entries, 1);
+    assert_eq!(cache.view().cold_entries, 0);
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn cold_cache_uses_two_hex_character_shards() {
+    let dir = tempfile::tempdir().unwrap();
+    let settings = cold_settings();
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/one", "first-payload").await;
+    fill(&cache, &settings, "/two", "second-payload").await;
+    wait_for_cold(&cache, 1).await;
+    let root = dir.path().join(&settings.cold_path);
+    let mut shards = Vec::new();
+    for item in std::fs::read_dir(&root).unwrap() {
+        let item = item.unwrap();
+        let name = item.file_name().to_string_lossy().to_string();
+        assert!(
+            item.path().is_dir(),
+            "cold root must contain shard directories only"
+        );
+        assert_eq!(name.len(), 2);
+        assert!(name.bytes().all(|b| b.is_ascii_hexdigit()));
+        shards.push(item.path());
+    }
+    assert!(!shards.is_empty());
+    assert!(shards.iter().any(|shard| {
+        std::fs::read_dir(shard)
+            .unwrap()
+            .filter_map(|entry| entry.ok())
+            .any(|entry| {
+                let name = entry.file_name().to_string_lossy().to_string();
+                name.ends_with(".json") || name.ends_with(".body")
+            })
+    }));
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn legacy_flat_cold_cache_is_not_migrated() {
+    let dir = tempfile::tempdir().unwrap();
+    let settings = cold_settings();
+    let root = dir.path().join(&settings.cold_path);
+    std::fs::create_dir_all(&root).unwrap();
+    std::fs::write(root.join("legacy.body"), b"old").unwrap();
+    std::fs::write(root.join("legacy.json"), b"{}").unwrap();
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings,
+        shutdown.clone(),
+    );
+    assert_eq!(cache.view().cold_entries, 0);
+    assert!(!root.join("legacy.body").exists());
+    assert!(!root.join("legacy.json").exists());
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn manual_cold_cleanup_reports_removed_objects_and_freed_bytes() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.max_entries = 1;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/one", "first-payload").await;
+    fill(&cache, &settings, "/two", "second-payload").await;
+    fill(&cache, &settings, "/three", "third-payload").await;
+    wait_for_cold(&cache, 2).await;
+    let job = cache
+        .start_cold_cleanup(ColdCleanupRequest {
+            unused_for_seconds: None,
+            oldest: Some(1),
+            hits_zero: false,
+        })
+        .unwrap();
+    for _ in 0..100 {
+        let current = cache.cold_cleanup_job(job.id).unwrap();
+        if current.status == "done" {
+            assert_eq!(current.removed_entries, 1);
+            assert!(current.freed_bytes > 0);
+            assert_eq!(cache.view().cold_entries, 1);
+            shutdown.cancel();
+            return;
+        }
+        tokio::time::sleep(Duration::from_millis(10)).await;
+    }
+    panic!("cold cleanup did not finish");
+}
+
+#[tokio::test]
+async fn manual_cold_cleanup_is_single_flight() {
+    let dir = tempfile::tempdir().unwrap();
+    let settings = cold_settings();
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings,
+        shutdown.clone(),
+    );
+    let _held = cache.cleanup_slots.clone().try_acquire_owned().unwrap();
+    let result = cache.start_cold_cleanup(ColdCleanupRequest {
+        unused_for_seconds: None,
+        oldest: Some(1),
+        hits_zero: false,
+    });
+    assert!(result.is_err());
+    shutdown.cancel();
+}
+
+#[tokio::test]
+async fn cold_cleanup_skips_an_entry_while_a_read_is_pinned() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut settings = cold_settings();
+    settings.max_entries = 1;
+    let shutdown = CancellationToken::new();
+    let cache = Cache::start(
+        11,
+        Some(dir.path().to_path_buf()),
+        settings.clone(),
+        shutdown.clone(),
+    );
+    fill(&cache, &settings, "/one", "first-payload").await;
+    fill(&cache, &settings, "/two", "second-payload").await;
+    wait_for_cold(&cache, 1).await;
+
+    let key = {
+        let mut cold = cache.cold.lock().unwrap();
+        let key = *cold.entries.keys().next().unwrap();
+        cold.entries.get_mut(&key).unwrap().pinned_reads = 1;
+        key
+    };
+    let request = ColdCleanupRequest {
+        unused_for_seconds: None,
+        oldest: Some(1),
+        hits_zero: false,
+    };
+    let result = cache
+        .remove_cold_candidates(Some(&request), None, None, 1)
+        .await;
+    assert_eq!(result.removed_entries, 0);
+    assert!(cache.cold.lock().unwrap().entries.contains_key(&key));
+
+    cache
+        .cold
+        .lock()
+        .unwrap()
+        .entries
+        .get_mut(&key)
+        .unwrap()
+        .pinned_reads = 0;
+    let result = cache
+        .remove_cold_candidates(Some(&request), None, None, 1)
+        .await;
+    assert_eq!(result.removed_entries, 1);
+    assert!(!cache.cold.lock().unwrap().entries.contains_key(&key));
+    shutdown.cancel();
+}
+
+#[test]
+fn old_cold_read_guard_does_not_unpin_a_replacement_with_the_same_key() {
+    let cache = Cache::new(1);
+    let key = [7_u8; 32];
+    let template = ColdEntry {
+        base_key: key,
+        vary: Vec::new(),
+        revision: 1,
+        scope: "app".to_owned(),
+        scheme: "https".to_owned(),
+        authority: "example.test".to_owned(),
+        domain: "example.test".to_owned(),
+        path: "/asset".to_owned(),
+        target: "https://example.test/asset".to_owned(),
+        tags: Vec::new(),
+        created_at: SystemTime::now(),
+        body_path: PathBuf::from("old.body"),
+        meta_path: PathBuf::from("old.json"),
+        body_bytes: 1,
+        body_sha256: [0u8; 32],
+        disk_bytes: 2,
+        stored_at: SystemTime::now(),
+        last_access: SystemTime::now(),
+        age_at_store_seconds: 0,
+        resident_age_at_store_seconds: 0,
+        ttl: 60,
+        stale_while_revalidate: 0,
+        stale_if_error: 0,
+        must_revalidate: false,
+        proxy_revalidate: false,
+        has_validator: false,
+        hits: 0,
+        transformed: false,
+        sequence: 1,
+        generation: 1,
+        skip_compression: false,
+        requires_revalidation: false,
+        pinned_reads: 1,
+    };
+    cache
+        .cold
+        .lock()
+        .unwrap()
+        .entries
+        .insert(key, template.clone());
+    let old_guard = ColdReadGuard {
+        cache: &cache,
+        key,
+        generation: 1,
+    };
+
+    let mut replacement = template;
+    replacement.sequence = 2;
+    replacement.generation = 2;
+    replacement.pinned_reads = 1;
+    cache.cold.lock().unwrap().entries.insert(key, replacement);
+    drop(old_guard);
+
+    let cold = cache.cold.lock().unwrap();
+    let replacement = cold.entries.get(&key).unwrap();
+    assert_eq!(replacement.generation, 2);
+    assert_eq!(replacement.pinned_reads, 1);
+}
+
+#[test]
+fn cold_path_cannot_escape_data_directory() {
+    let mut settings = Settings::default();
+    settings.cold_path = "../outside".into();
+    assert!(settings.validate().is_err());
+    settings.cold_path = "/tmp/outside".into();
+    assert!(settings.validate().is_err());
+    settings.cold_path = "cache/cold".into();
+    assert!(settings.validate().is_ok());
+}
 }

src/cache/tests/v022_cache_tests.rs

@@ -1,4 +1,950 @@
 mod v022_cache_tests {
-    include!("v022_cache_tests/part_01.rs");
-    include!("v022_cache_tests/part_02.rs");
+    use super::*;
+    use http_body_util::BodyExt;
+
+    fn active_settings() -> Settings {
+        Settings {
+            enabled: true,
+            ..Settings::default()
+        }
+    }
+
+    async fn store(
+        cache: &Arc<Cache>,
+        scope: &str,
+        host: &str,
+        target: &str,
+        request_headers: HeaderMap,
+        extra_response_headers: &[(&str, &str)],
+        body: &'static str,
+    ) -> Ticket {
+        let ticket = cache
+            .ticket_scoped(
+                22,
+                scope,
+                "http",
+                host,
+                "origin@127.0.0.1:8080",
+                target,
+                &request_headers,
+            )
+            .unwrap();
+        let settings = active_settings();
+        let mut response = Response::new(Body::from(body));
+        response.headers_mut().insert(
+            "cache-control",
+            HeaderValue::from_static("public, max-age=120, stale-if-error=60"),
+        );
+        for (name, value) in extra_response_headers {
+            response.headers_mut().insert(
+                http::HeaderName::from_bytes(name.as_bytes()).unwrap(),
+                HeaderValue::from_str(value).unwrap(),
+            );
+        }
+        let plan = plan(
+            StatusCode::OK,
+            response.headers(),
+            &settings,
+            Duration::ZERO,
+        )
+        .unwrap();
+        cache
+            .wrap(response, ticket.clone(), plan, &settings)
+            .into_body()
+            .collect()
+            .await
+            .unwrap();
+        ticket
+    }
+
+    fn invalidation(
+        operation: InvalidationOperation,
+        selector: InvalidationSelector,
+        value: &str,
+        host: Option<&str>,
+        vhost: Option<&str>,
+    ) -> InvalidationRequest {
+        InvalidationRequest {
+            operation,
+            selector,
+            value: value.to_owned(),
+            host: host.map(str::to_owned),
+            vhost: vhost.map(str::to_owned),
+            ttl_seconds: None,
+            confirm_wide: false,
+        }
+    }
+
+    #[tokio::test]
+    async fn transformed_fill_retains_identical_content_and_releases_fill_gauge() {
+        for body in [
+            Bytes::from(vec![b'x'; 4096]),
+            Bytes::from_static(b"unchanged static bytes"),
+        ] {
+            let cache = Cache::new(22);
+            let settings = active_settings();
+            let ticket = cache.ticket(22, "http", "example.test", "origin", "/transform.js", &HeaderMap::new()).unwrap();
+            let mut response = Response::new(Body::from(body.clone()));
+            response.headers_mut().insert("cache-control", HeaderValue::from_static("public, max-age=120"));
+            response.headers_mut().insert("content-length", HeaderValue::from_str(&body.len().to_string()).unwrap());
+            response.extensions_mut().insert(crate::transform::Applied {
+                kind: crate::transform::Kind::Javascript,
+                original_bytes: body.len(),
+                transformed_bytes: body.len(),
+            });
+            let policy = plan(StatusCode::OK, response.headers(), &settings, Duration::ZERO).unwrap();
+            assert_eq!(policy.expected_length, Some(body.len()));
+            let downstream = cache.wrap(response, ticket.clone(), policy, &settings)
+                .into_body().collect().await.unwrap().to_bytes();
+            assert_eq!(downstream, body);
+            let cached = cache.get(&ticket).unwrap().response.into_body().collect().await.unwrap().to_bytes();
+            assert_eq!(cached, body);
+            assert_eq!(cache.fill_bytes_active.load(Ordering::Relaxed), 0);
+        }
+    }
+
+    #[tokio::test]
+    async fn uniquely_owned_transformed_frame_is_cached_without_body_copy() {
+        let cache = Cache::new(22);
+        let settings = active_settings();
+        let ticket = cache.ticket(22, "http", "example.test", "origin", "/owned.js", &HeaderMap::new()).unwrap();
+        let payload = Bytes::from(vec![b'z'; 8192]);
+        let original_allocation = payload.as_ptr();
+        let mut response = Response::new(Body::from(payload));
+        response.headers_mut().insert("cache-control", HeaderValue::from_static("public, max-age=120"));
+        response.headers_mut().insert("content-length", HeaderValue::from_static("8192"));
+        response.extensions_mut().insert(crate::transform::Applied {
+            kind: crate::transform::Kind::Javascript,
+            original_bytes: 8192,
+            transformed_bytes: 8192,
+        });
+        let policy = plan(StatusCode::OK, response.headers(), &settings, Duration::ZERO).unwrap();
+        let downstream = cache.wrap(response, ticket.clone(), policy, &settings)
+            .into_body().collect().await.unwrap().to_bytes();
+        assert_eq!(downstream.len(), 8192);
+        assert_eq!(downstream.as_ptr(), original_allocation);
+        let hit = cache.get(&ticket).unwrap();
+        let cached = hit.response.into_body().collect().await.unwrap().to_bytes();
+        assert_eq!(cached, downstream);
+        assert_eq!(cached.as_ptr(), original_allocation, "cache fill copied the transformed body");
+        assert_eq!(cache.fill_bytes_active.load(Ordering::Relaxed), 0);
+    }
+
+    #[tokio::test]
+    async fn cached_single_range_returns_206_and_preserves_validators() {
+        let cache = Cache::new(22);
+        let ticket = store(
+            &cache,
+            "range",
+            "range.example",
+            "/asset.bin",
+            HeaderMap::new(),
+            &[
+                ("etag", "\"asset-v1\""),
+                ("last-modified", "Mon, 26 Jan 2026 23:11:40 GMT"),
+            ],
+            "abcdefghij",
+        )
+        .await;
+        let mut request_headers = HeaderMap::new();
+        request_headers.insert("range", HeaderValue::from_static("bytes=2-5"));
+        let range = match request_range(&Method::GET, &request_headers) {
+            RangeSelection::Single(range) => range,
+            other => panic!("unexpected range selection: {other:?}"),
+        };
+        let hit = cache.get(&ticket).unwrap().apply_range(range, None);
+        assert_eq!(hit.response.status(), StatusCode::PARTIAL_CONTENT);
+        assert_eq!(hit.response.headers()["content-range"], "bytes 2-5/10");
+        assert_eq!(hit.response.headers()["content-length"], "4");
+        assert_eq!(hit.response.headers()["accept-ranges"], "bytes");
+        assert_eq!(hit.response.headers()["etag"], "\"asset-v1\"");
+        assert!(hit.response.headers().contains_key("age"));
+        let body = hit.response.into_body().collect().await.unwrap().to_bytes();
+        assert_eq!(body, Bytes::from_static(b"cdef"));
+    }
+
+    #[tokio::test]
+    async fn cached_range_supports_suffix_open_unsatisfied_and_if_range() {
+        let cache = Cache::new(22);
+        let ticket = store(
+            &cache,
+            "range",
+            "range.example",
+            "/asset.bin",
+            HeaderMap::new(),
+            &[
+                ("etag", "\"asset-v1\""),
+                ("last-modified", "Mon, 26 Jan 2026 23:11:40 GMT"),
+            ],
+            "abcdefghij",
+        )
+        .await;
+        let cases = [
+            (ByteRange { start: None, end: Some(3) }, "hij", "bytes 7-9/10"),
+            (ByteRange { start: Some(7), end: None }, "hij", "bytes 7-9/10"),
+        ];
+        for (range, expected, content_range) in cases {
+            let hit = cache.get(&ticket).unwrap().apply_range(range, None);
+            assert_eq!(hit.response.status(), StatusCode::PARTIAL_CONTENT);
+            assert_eq!(hit.response.headers()["content-range"], content_range);
+            let body = hit.response.into_body().collect().await.unwrap().to_bytes();
+            assert_eq!(body, Bytes::copy_from_slice(expected.as_bytes()));
+        }
+
+        let unsatisfied = cache.get(&ticket).unwrap().apply_range(
+            ByteRange { start: Some(50), end: None },
+            None,
+        );
+        assert_eq!(unsatisfied.response.status(), StatusCode::RANGE_NOT_SATISFIABLE);
+        assert_eq!(unsatisfied.response.headers()["content-range"], "bytes */10");
+        assert_eq!(
+            unsatisfied.response.into_body().collect().await.unwrap().to_bytes().len(),
+            0
+        );
+
+        let mismatch = HeaderValue::from_static("\"asset-v2\"");
+        let full = cache.get(&ticket).unwrap().apply_range(
+            ByteRange { start: Some(0), end: Some(2) },
+            Some(&mismatch),
+        );
+        assert_eq!(full.response.status(), StatusCode::OK);
+        assert!(!full.response.headers().contains_key("content-range"));
+        assert_eq!(
+            full.response.into_body().collect().await.unwrap().to_bytes(),
+            Bytes::from_static(b"abcdefghij")
+        );
+
+        let matched = HeaderValue::from_static("\"asset-v1\"");
+        let partial = cache.get(&ticket).unwrap().apply_range(
+            ByteRange { start: Some(0), end: Some(2) },
+            Some(&matched),
+        );
+        assert_eq!(partial.response.status(), StatusCode::PARTIAL_CONTENT);
+    }
+
+    #[test]
+    fn range_parser_rejects_multipart_and_duplicate_fields_and_if_range_date_allows_older_representation() {
+        let mut multipart = HeaderMap::new();
+        multipart.insert("range", HeaderValue::from_static("bytes=0-1,4-5"));
+        assert_eq!(
+            request_range(&Method::GET, &multipart),
+            RangeSelection::Unsupported
+        );
+
+        let mut duplicate = HeaderMap::new();
+        duplicate.append("range", HeaderValue::from_static("bytes=0-1"));
+        duplicate.append("range", HeaderValue::from_static("bytes=4-5"));
+        assert_eq!(
+            request_range(&Method::GET, &duplicate),
+            RangeSelection::Unsupported
+        );
+
+        let mut response_headers = HeaderMap::new();
+        response_headers.insert(
+            "last-modified",
+            HeaderValue::from_static("Mon, 26 Jan 2026 23:11:40 GMT"),
+        );
+        let newer_if_range = HeaderValue::from_static("Tue, 27 Jan 2026 23:11:40 GMT");
+        assert!(if_range_matches(&response_headers, Some(&newer_if_range)));
+    }
+
+    #[tokio::test]
+    async fn concurrent_miss_single_flight_waits_until_fill_is_published() {
+        let cache = Cache::new(22);
+        let mut settings = active_settings();
+        settings.collapse_wait_timeout_ms = 500;
+        let ticket = cache
+            .ticket_scoped(
+                22,
+                "collapse",
+                "http",
+                "collapse.example",
+                "origin@127.0.0.1:8080",
+                "/same",
+                &HeaderMap::new(),
+            )
+            .unwrap();
+        let leader = match cache.claim_fill(&ticket, &settings).await {
+            FillClaim::Leader(guard) => guard,
+            _ => panic!("first request must become fill leader"),
+        };
+        let follower_cache = cache.clone();
+        let follower_ticket = ticket.clone();
+        let follower_settings = settings.clone();
+        let follower = tokio::spawn(async move {
+            match follower_cache
+                .claim_fill(&follower_ticket, &follower_settings)
+                .await
+            {
+                FillClaim::Waited => follower_cache.get(&follower_ticket).is_some(),
+                _ => false,
+            }
+        });
+        for _ in 0..50 {
+            if cache.view().collapse_waiters == 1 {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(2)).await;
+        }
+        assert_eq!(cache.view().collapse_waiters, 1);
+        assert!(!follower.is_finished());
+
+        let mut response = Response::new(Body::from("collapsed-payload"));
+        response.headers_mut().insert(
+            "cache-control",
+            HeaderValue::from_static("public, max-age=60"),
+        );
+        let plan = plan(
+            StatusCode::OK,
+            response.headers(),
+            &settings,
+            Duration::ZERO,
+        )
+        .unwrap();
+        cache
+            .wrap_with_fill(response, ticket.clone(), plan, &settings, Some(leader))
+            .into_body()
+            .collect()
+            .await
+            .unwrap();
+        assert!(follower.await.unwrap());
+        assert_eq!(cache.view().collapsed_fills, 1);
+        assert_eq!(cache.view().collapse_waiters, 0);
+    }
+
+    #[tokio::test]
+    async fn single_flight_timeout_and_leader_drop_release_the_key() {
+        let cache = Cache::new(22);
+        let mut settings = active_settings();
+        settings.collapse_wait_timeout_ms = 10;
+        let ticket = cache
+            .ticket(22, "http", "collapse.example", "origin", "/timeout", &HeaderMap::new())
+            .unwrap();
+        let leader = match cache.claim_fill(&ticket, &settings).await {
+            FillClaim::Leader(guard) => guard,
+            _ => panic!("missing leader"),
+        };
+        assert!(matches!(cache.claim_fill(&ticket, &settings).await, FillClaim::Timeout));
+        assert_eq!(cache.view().collapse_timeouts, 1);
+        drop(leader);
+        assert!(matches!(
+            cache.claim_fill(&ticket, &settings).await,
+            FillClaim::Leader(_)
+        ));
+    }
+
+    #[tokio::test]
+    async fn cancelled_single_flight_waiter_releases_waiter_metric() {
+        let cache = Cache::new(22);
+        let mut settings = active_settings();
+        settings.collapse_wait_timeout_ms = 5_000;
+        let ticket = cache
+            .ticket(22, "http", "collapse.example", "origin", "/cancel", &HeaderMap::new())
+            .unwrap();
+        let leader = match cache.claim_fill(&ticket, &settings).await {
+            FillClaim::Leader(guard) => guard,
+            _ => panic!("missing leader"),
+        };
+        let follower_cache = cache.clone();
+        let follower_ticket = ticket.clone();
+        let follower_settings = settings.clone();
+        let follower = tokio::spawn(async move {
+            follower_cache
+                .claim_fill(&follower_ticket, &follower_settings)
+                .await
+        });
+        for _ in 0..50 {
+            if cache.view().collapse_waiters == 1 {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(2)).await;
+        }
+        assert_eq!(cache.view().collapse_waiters, 1);
+        follower.abort();
+        let _ = follower.await;
+        tokio::task::yield_now().await;
+        assert_eq!(cache.view().collapse_waiters, 0);
+        drop(leader);
+    }
+
+    #[tokio::test]
+    async fn single_flight_retries_after_another_vary_representation_is_published() {
+        let cache = Cache::new(22);
+        let mut settings = active_settings();
+        settings.collapse_wait_timeout_ms = 500;
+        let mut en_headers = HeaderMap::new();
+        en_headers.insert("accept-language", HeaderValue::from_static("en"));
+        let mut pl_headers = HeaderMap::new();
+        pl_headers.insert("accept-language", HeaderValue::from_static("pl"));
+        let en = cache
+            .ticket(22, "http", "vary-collapse.example", "origin", "/page", &en_headers)
+            .unwrap();
+        let pl = cache
+            .ticket(22, "http", "vary-collapse.example", "origin", "/page", &pl_headers)
+            .unwrap();
+        assert_eq!(en.key, pl.key, "Vary is learned from the response");
+        let leader = match cache.claim_fill(&en, &settings).await {
+            FillClaim::Leader(guard) => guard,
+            _ => panic!("first representation must become leader"),
+        };
+        let follower_cache = cache.clone();
+        let follower_ticket = pl.clone();
+        let follower_settings = settings.clone();
+        let follower = tokio::spawn(async move {
+            assert!(matches!(
+                follower_cache
+                    .claim_fill(&follower_ticket, &follower_settings)
+                    .await,
+                FillClaim::Waited
+            ));
+            assert!(follower_cache.get(&follower_ticket).is_none());
+            matches!(
+                follower_cache
+                    .claim_fill(&follower_ticket, &follower_settings)
+                    .await,
+                FillClaim::Leader(_)
+            )
+        });
+        for _ in 0..50 {
+            if cache.view().collapse_waiters == 1 {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(2)).await;
+        }
+
+        let mut response = Response::new(Body::from("hello"));
+        response.headers_mut().insert(
+            "cache-control",
+            HeaderValue::from_static("public, max-age=60"),
+        );
+        response
+            .headers_mut()
+            .insert("vary", HeaderValue::from_static("Accept-Language"));
+        let plan = plan(
+            StatusCode::OK,
+            response.headers(),
+            &settings,
+            Duration::ZERO,
+        )
+        .unwrap();
+        cache
+            .wrap_with_fill(response, en, plan, &settings, Some(leader))
+            .into_body()
+            .collect()
+            .await
+            .unwrap();
+        assert!(follower.await.unwrap());
+    }
+
+    #[test]
+    fn stale_if_error_policy_is_configurable_by_error_class_and_status() {
+        let mut settings = Settings::default();
+        settings.stale_if_error_timeout = false;
+        settings.stale_if_error_dns = false;
+        settings.stale_if_error_statuses = vec![500, 503];
+        assert!(!settings.allows_stale_error_class(StaleErrorClass::Timeout));
+        assert!(!settings.allows_stale_error_class(StaleErrorClass::Dns));
+        assert!(settings.allows_stale_error_class(StaleErrorClass::Connection));
+        assert!(settings.allows_stale_error_class(StaleErrorClass::Tls));
+        assert!(settings.allows_stale_error_status(StatusCode::INTERNAL_SERVER_ERROR));
+        assert!(settings.allows_stale_error_status(StatusCode::SERVICE_UNAVAILABLE));
+        assert!(!settings.allows_stale_error_status(StatusCode::BAD_GATEWAY));
+    }
+
+    #[test]
+    fn proactive_refresh_guards_deduplicate_and_bound_parallel_work() {
+        let cache = Cache::new(22);
+        let ticket = cache
+            .ticket(22, "http", "refresh.example", "origin", "/asset", &HeaderMap::new())
+            .unwrap();
+        let mut settings = active_settings();
+        settings.proactive_refresh_enabled = true;
+        settings.proactive_refresh_percent = 100;
+        settings.proactive_refresh_max_inflight = 1;
+        let scheduled = cache
+            .begin_proactive_schedule(&ticket, &settings)
+            .expect("first schedule");
+        assert!(cache.begin_proactive_schedule(&ticket, &settings).is_none());
+        let running = cache
+            .try_begin_proactive_refresh(&settings)
+            .expect("first inflight refresh");
+        assert!(cache.try_begin_proactive_refresh(&settings).is_none());
+        assert_eq!(cache.view().proactive_inflight, 1);
+        drop(running);
+        drop(scheduled);
+        assert!(cache.begin_proactive_schedule(&ticket, &settings).is_some());
+        assert_eq!(cache.view().proactive_inflight, 0);
+    }
+
+    #[test]
+    fn proactive_refresh_pending_tasks_are_bounded() {
+        let cache = Cache::new(22);
+        let mut settings = active_settings();
+        settings.proactive_refresh_enabled = true;
+        settings.proactive_refresh_percent = 100;
+        settings.proactive_refresh_max_inflight = 1;
+        let mut guards = Vec::new();
+        for index in 0..64 {
+            let ticket = cache
+                .ticket(
+                    22,
+                    "http",
+                    "refresh.example",
+                    "origin",
+                    &format!("/asset-{index}"),
+                    &HeaderMap::new(),
+                )
+                .unwrap();
+            guards.push(
+                cache
+                    .begin_proactive_schedule(&ticket, &settings)
+                    .expect("schedule below pending limit"),
+            );
+        }
+        let overflow = cache
+            .ticket(
+                22,
+                "http",
+                "refresh.example",
+                "origin",
+                "/overflow",
+                &HeaderMap::new(),
+            )
+            .unwrap();
+        assert!(cache.begin_proactive_schedule(&overflow, &settings).is_none());
+        assert!(cache.view().proactive_skipped > 0);
+        drop(guards);
+    }
+
+    #[test]
+    fn background_revalidation_set_has_a_hard_limit() {
+        let cache = Cache::new(22);
+        let base = Revalidation {
+            headers: HeaderMap::new(),
+            body: Bytes::new(),
+            body_allocated: 0,
+            _transient_leases: Vec::new(),
+            hits: 0,
+            transformed: false,
+            storage_key: [0; 32],
+            resident_age_at_lookup: Duration::ZERO,
+            skip_compression: false,
+            reusable_without_validation: false,
+            age: 0,
+            ttl: 0,
+            stale_if_error: 0,
+            must_revalidate: false,
+            proxy_revalidate: false,
+            origin_etag: None,
+            origin_last_modified: None,
+        };
+        let mut guards = Vec::new();
+        for index in 0..BACKGROUND_REVALIDATION_LIMIT {
+            let mut cached = base.clone();
+            cached.storage_key[0..8].copy_from_slice(&(index as u64).to_be_bytes());
+            guards.push(
+                cache
+                    .begin_background_revalidation(&cached)
+                    .expect("revalidation below hard limit"),
+            );
+        }
+        let mut overflow = base;
+        overflow.storage_key = [0xff; 32];
+        assert!(cache.begin_background_revalidation(&overflow).is_none());
+        drop(guards);
+    }
+
+    #[tokio::test]
+    async fn selective_purge_exact_prefix_tag_cache_key_and_query_are_precise() {
+        let cache = Cache::new(22);
+        let one = store(
+            &cache,
+            "app",
+            "purge.example",
+            "/asset.js?v=1",
+            HeaderMap::new(),
+            &[("cache-tag", "release:one")],
+            "one",
+        )
+        .await;
+        let two = store(
+            &cache,
+            "app",
+            "purge.example",
+            "/asset.js?v=2",
+            HeaderMap::new(),
+            &[("cache-tag", "release:two")],
+            "two",
+        )
+        .await;
+        let result = cache
+            .invalidate(invalidation(
+                InvalidationOperation::Purge,
+                InvalidationSelector::Exact,
+                "/asset.js?v=1",
+                Some("purge.example"),
+                Some("app"),
+            ))
+            .unwrap();
+        assert_eq!(result.affected_entries, 1);
+        assert!(cache.get(&one).is_none());
+        assert!(cache.get(&two).is_some());
+
+        let three = store(
+            &cache,
+            "app",
+            "purge.example",
+            "/assets/a.css",
+            HeaderMap::new(),
+            &[("cache-tag", "release:three")],
+            "three",
+        )
+        .await;
+        let four = store(
+            &cache,
+            "app",
+            "purge.example",
+            "/assets/b.css",
+            HeaderMap::new(),
+            &[("cache-tag", "release:four")],
+            "four",
+        )
+        .await;
+        assert_eq!(
+            cache
+                .invalidate(invalidation(
+                    InvalidationOperation::Purge,
+                    InvalidationSelector::Prefix,
+                    "/assets/",
+                    Some("purge.example"),
+                    Some("app"),
+                ))
+                .unwrap()
+                .affected_entries,
+            2
+        );
+        assert!(cache.get(&three).is_none());
+        assert!(cache.get(&four).is_none());
+
+        let tagged = store(
+            &cache,
+            "app",
+            "purge.example",
+            "/tagged",
+            HeaderMap::new(),
+            &[("cache-tag", "release:tagged")],
+            "tagged",
+        )
+        .await;
+        assert_eq!(
+            cache
+                .invalidate(invalidation(
+                    InvalidationOperation::Purge,
+                    InvalidationSelector::Tag,
+                    "release:tagged",
+                    Some("purge.example"),
+                    Some("app"),
+                ))
+                .unwrap()
+                .affected_entries,
+            1
+        );
+        assert!(cache.get(&tagged).is_none());
+
+        let keyed = store(
+            &cache,
+            "app",
+            "purge.example",
+            "/by-key",
+            HeaderMap::new(),
+            &[],
+            "keyed",
+        )
+        .await;
+        let key = key_hex(&keyed.key);
+        assert_eq!(
+            cache
+                .invalidate(invalidation(
+                    InvalidationOperation::Purge,
+                    InvalidationSelector::CacheKey,
+                    &key,
+                    Some("purge.example"),
+                    Some("app"),
+                ))
+                .unwrap()
+                .affected_entries,
+            1
+        );
+        assert!(cache.get(&keyed).is_none());
+    }
+
+    #[tokio::test]
+    async fn selective_purge_is_a_barrier_for_a_fill_started_before_the_purge() {
+        let cache = Cache::new(22);
+        let settings = active_settings();
+        let old_ticket = cache
+            .ticket_scoped(
+                22,
+                "app",
+                "http",
+                "purge.example",
+                "origin@127.0.0.1:8080",
+                "/late",
+                &HeaderMap::new(),
+            )
+            .unwrap();
+        let result = cache
+            .invalidate(invalidation(
+                InvalidationOperation::Purge,
+                InvalidationSelector::Tag,
+                "release:late",
+                Some("purge.example"),
+                Some("app"),
+            ))
+            .unwrap();
+        assert_eq!(result.affected_entries, 0);
+
+        let mut response = Response::new(Body::from("old-fill"));
+        response.headers_mut().insert(
+            "cache-control",
+            HeaderValue::from_static("public, max-age=60"),
+        );
+        response
+            .headers_mut()
+            .insert("cache-tag", HeaderValue::from_static("release:late"));
+        let plan = plan(
+            StatusCode::OK,
+            response.headers(),
+            &settings,
+            Duration::ZERO,
+        )
+        .unwrap();
+        cache
+            .wrap(response, old_ticket, plan, &settings)
+            .into_body()
+            .collect()
+            .await
+            .unwrap();
+        assert_eq!(cache.view().entries, 0, "pre-purge fill must not republish");
+
+        let new_ticket = store(
+            &cache,
+            "app",
+            "purge.example",
+            "/late",
+            HeaderMap::new(),
+            &[("cache-tag", "release:late")],
+            "new-fill",
+        )
+        .await;
+        assert!(cache.get(&new_ticket).is_some());
+    }
+
+    #[tokio::test]
+    async fn purge_of_one_vary_variant_removes_the_whole_variant_family() {
+        let cache = Cache::new(22);
+        let mut en_headers = HeaderMap::new();
+        en_headers.insert("accept-language", HeaderValue::from_static("en"));
+        let mut pl_headers = HeaderMap::new();
+        pl_headers.insert("accept-language", HeaderValue::from_static("pl"));
+        let en = store(
+            &cache,
+            "app",
+            "vary.example",
+            "/localized",
+            en_headers,
+            &[("vary", "Accept-Language"), ("cache-tag", "variant:en")],
+            "hello",
+        )
+        .await;
+        let pl = store(
+            &cache,
+            "app",
+            "vary.example",
+            "/localized",
+            pl_headers,
+            &[("vary", "Accept-Language"), ("cache-tag", "variant:pl")],
+            "czesc",
+        )
+        .await;
+        let result = cache
+            .invalidate(invalidation(
+                InvalidationOperation::Purge,
+                InvalidationSelector::Tag,
+                "variant:en",
+                Some("vary.example"),
+                Some("app"),
+            ))
+            .unwrap();
+        assert_eq!(result.affected_entries, 2);
+        assert!(cache.get(&en).is_none());
+        assert!(cache.get(&pl).is_none());
+    }
+
+    #[tokio::test]
+    async fn ban_is_lazy_blocks_old_object_allows_new_fill_and_can_be_removed() {
+        let cache = Cache::new(22);
+        let old = store(
+            &cache,
+            "app",
+            "ban.example",
+            "/page",
+            HeaderMap::new(),
+            &[],
+            "old",
+        )
+        .await;
+        assert_eq!(cache.view().entries, 1);
+        let result = cache
+            .invalidate(invalidation(
+                InvalidationOperation::Ban,
+                InvalidationSelector::Exact,
+                "/page",
+                Some("ban.example"),
+                Some("app"),
+            ))
+            .unwrap();
+        let ban_id = result.ban_id.unwrap();
+        assert_eq!(result.affected_entries, 0);
+        assert_eq!(cache.view().entries, 1, "BAN must not scan storage eagerly");
+        assert!(cache.get(&old).is_none());
+        assert_eq!(cache.view().entries, 0);
+
+        tokio::time::sleep(Duration::from_millis(2)).await;
+        let fresh = store(
+            &cache,
+            "app",
+            "ban.example",
+            "/page",
+            HeaderMap::new(),
+            &[],
+            "fresh",
+        )
+        .await;
+        assert!(cache.get(&fresh).is_some(), "old BAN must not reject newer objects");
+        assert_eq!(cache.bans().len(), 1);
+        assert!(cache.remove_ban(ban_id));
+        assert!(cache.bans().is_empty());
+        assert!(!cache.remove_ban(ban_id));
+    }
+
+    #[tokio::test]
+    async fn regex_and_root_prefix_require_explicit_wide_confirmation() {
+        let cache = Cache::new(22);
+        store(
+            &cache,
+            "app",
+            "wide.example",
+            "/one",
+            HeaderMap::new(),
+            &[],
+            "one",
+        )
+        .await;
+        let regex = invalidation(
+            InvalidationOperation::Purge,
+            InvalidationSelector::Regex,
+            ".*",
+            None,
+            None,
+        );
+        assert!(cache.invalidate(regex.clone()).is_err());
+        let scoped_regex = invalidation(
+            InvalidationOperation::Purge,
+            InvalidationSelector::Regex,
+            "^/one$",
+            Some("wide.example"),
+            Some("app"),
+        );
+        assert!(cache.invalidate(scoped_regex).is_err());
+        let mut confirmed = regex;
+        confirmed.confirm_wide = true;
+        assert_eq!(cache.invalidate(confirmed).unwrap().affected_entries, 1);
+
+        let prefix = invalidation(
+            InvalidationOperation::Ban,
+            InvalidationSelector::Prefix,
+            "/",
+            Some("wide.example"),
+            Some("app"),
+        );
+        assert!(cache.invalidate(prefix.clone()).is_err());
+        let mut confirmed_prefix = prefix;
+        confirmed_prefix.confirm_wide = true;
+        assert!(cache.invalidate(confirmed_prefix).unwrap().ban_id.is_some());
+    }
+
+    #[tokio::test]
+    async fn many_distinct_selective_purges_do_not_retain_tombstones_forever() {
+        let cache = Cache::new(22);
+        store(
+            &cache,
+            "app",
+            "memory.example",
+            "/stable",
+            HeaderMap::new(),
+            &[],
+            "unchanged",
+        )
+        .await;
+        // A production cache may see an unbounded stream of PURGEs for URLs
+        // that will never be cached again. The invalidated-key index must
+        // not remember all of those removed objects indefinitely.
+        for index in 0..512 {
+            let target = format!("/unique-{index}");
+            let old = store(
+                &cache,
+                "app",
+                "memory.example",
+                &target,
+                HeaderMap::new(),
+                &[],
+                "x",
+            )
+            .await;
+            assert!(cache.ticket_current(&old));
+            let result = cache
+                .invalidate(invalidation(
+                    InvalidationOperation::Purge,
+                    InvalidationSelector::Exact,
+                    &target,
+                    Some("memory.example"),
+                    Some("app"),
+                ))
+                .unwrap();
+            assert_eq!(result.affected_entries, 1);
+            assert!(!cache.ticket_current(&old), "pre-purge ticket must remain stale");
+            let state = cache.store.lock().unwrap_or_else(|e| e.into_inner());
+            assert!(
+                state.key_generations.len() <= 1,
+                "key generations must not accumulate for already purged URLs"
+            );
+        }
+        // A new ticket after the invalidation barrier is valid and can fill
+        // the same URL again, preserving ordinary cache behavior.
+        let new = store(
+            &cache,
+            "app",
+            "memory.example",
+            "/unique-0",
+            HeaderMap::new(),
+            &[],
+            "new",
+        )
+        .await;
+        assert!(cache.ticket_current(&new));
+        assert!(cache.get(&new).is_some());
+        let stable = cache
+            .ticket_scoped(
+                22,
+                "app",
+                "http",
+                "memory.example",
+                "origin@127.0.0.1:8080",
+                "/stable",
+                &HeaderMap::new(),
+            )
+            .unwrap();
+        assert!(cache.get(&stable).is_some(), "unrelated entries must survive");
+    }
 }

src/config/tests.rs

@@ -1,5 +1,907 @@
 mod tests {
-    include!("tests/part_01.rs");
-    include!("tests/part_02.rs");
-    include!("tests/part_03.rs");
+use super::*;
+fn policy() -> ValidationPolicy {
+    ValidationPolicy {
+        tls_addr: None,
+        cert_dir: None,
+        data_dir: None,
+        proxy_addr: "127.0.0.1:8080".parse().unwrap(),
+        admin_addr: "127.0.0.1:9090".parse().unwrap(),
+    }
+}
+#[test]
+fn missing_http2_settings_use_release_defaults() {
+    let config: Config = serde_json::from_value(serde_json::json!({})).unwrap();
+    assert_eq!(config.http2, crate::settings::Http2Connections::default());
+    config.http2.validate().unwrap();
+}
+
+#[test]
+fn normalized_unicode_prefix_survives_serialization_and_recompile() {
+    let mut config = demo_config("127.0.0.1:9000".parse().unwrap());
+    config.vhosts[0].routes[0].path_prefix = "/caf%C3%A9".into();
+    let first = compile(config, 0, &policy()).unwrap();
+    let saved = serde_json::to_string(&first.envelope.config).unwrap();
+    let second = compile(serde_json::from_str(&saved).unwrap(), 1, &policy()).unwrap();
+    assert!(second.select("localhost", "/caf\u{e9}/hello").is_some());
+}
+#[test]
+fn web_server_main_source_needs_no_backend_pool() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    std::fs::write(tmp.path().join("index.html"), b"hello").unwrap();
+    let mut config = demo_config("127.0.0.1:9000".parse().unwrap());
+    config.web_services.push(crate::web_server::Service {
+        id: "site".into(),
+        name: "Site".into(),
+        document_root: tmp.path().to_path_buf(),
+        index: vec!["index.html".into()],
+        directory_listing: false,
+        ..Default::default()
+    });
+    config.vhosts[0].source = crate::vhost::Source::WebServer {
+        web_service_id: "site".into(),
+    };
+    config.vhosts[0].backends.clear();
+    config.vhosts[0].routes.clear();
+    let snapshot = compile(config, 1, &policy()).unwrap();
+    let route = snapshot.select("localhost", "/").unwrap();
+    assert!(matches!(&route.source, CompiledSource::WebServer(_)));
+    assert!(route.pool.is_none());
+    assert!(route.backend.is_none());
+    assert!(snapshot.pools.is_empty());
+}
+
+#[test]
+fn web_server_and_reverse_proxy_can_share_one_vhost() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    std::fs::write(tmp.path().join("index.html"), b"hello").unwrap();
+    let mut config = demo_config("127.0.0.1:9000".parse().unwrap());
+    config.web_services.push(crate::web_server::Service {
+        id: "site".into(),
+        name: "Site".into(),
+        document_root: tmp.path().to_path_buf(),
+        index: vec!["index.html".into()],
+        directory_listing: false,
+        ..Default::default()
+    });
+    let host = &mut config.vhosts[0];
+    host.source = crate::vhost::Source::WebServer {
+        web_service_id: "site".into(),
+    };
+    host.routes = vec![crate::vhost::PathRoute {
+        id: "api".into(),
+        path_prefix: "/api".into(),
+        source: crate::vhost::Source::ReverseProxy,
+        ..Default::default()
+    }];
+    let snapshot = compile(config, 1, &policy()).unwrap();
+    let root = snapshot.select("localhost", "/").unwrap();
+    let api = snapshot.select("localhost", "/api/test").unwrap();
+    assert!(matches!(&root.source, CompiledSource::WebServer(_)));
+    assert!(matches!(&api.source, CompiledSource::ReverseProxy));
+    assert!(api.pool.is_some());
+    assert!(api.backend.is_some());
+}
+
+#[test]
+fn one_web_service_can_be_reused_by_multiple_vhosts() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    std::fs::write(tmp.path().join("index.html"), b"shared").unwrap();
+    let mut config = demo_config("127.0.0.1:9000".parse().unwrap());
+    config.web_services.push(crate::web_server::Service {
+        id: "shared-site".into(),
+        name: "Shared site".into(),
+        document_root: tmp.path().to_path_buf(),
+        index: vec!["index.html".into()],
+        directory_listing: false,
+        ..Default::default()
+    });
+    let first = &mut config.vhosts[0];
+    first.source = crate::vhost::Source::WebServer {
+        web_service_id: "shared-site".into(),
+    };
+    first.backends.clear();
+    first.routes.clear();
+
+    let mut second = first.clone();
+    second.id = "shared-second".into();
+    second.frontend.hosts = vec!["second.localhost".into()];
+    config.vhosts.push(second);
+
+    let snapshot = compile(config, 1, &policy()).unwrap();
+    let first_route = snapshot.select("localhost", "/").unwrap();
+    let second_route = snapshot.select("second.localhost", "/").unwrap();
+    assert!(
+        matches!(&first_route.source, CompiledSource::WebServer(service) if service.id == "shared-site")
+    );
+    assert!(
+        matches!(&second_route.source, CompiledSource::WebServer(service) if service.id == "shared-site")
+    );
+}
+
+#[test]
+fn unknown_web_service_reference_is_rejected() {
+    let mut config = demo_config("127.0.0.1:9000".parse().unwrap());
+    config.vhosts[0].source = crate::vhost::Source::WebServer {
+        web_service_id: "missing".into(),
+    };
+    let error = compile(config, 1, &policy()).unwrap_err().to_string();
+    assert!(error.contains("unknown Web Service"), "{error}");
+}
+
+#[test]
+fn missing_source_fields_remain_reverse_proxy_for_old_configs() {
+    let source: crate::vhost::Source =
+        serde_json::from_value(serde_json::json!({"type":"reverse_proxy"})).unwrap();
+    assert_eq!(source, crate::vhost::Source::ReverseProxy);
+    let route: crate::vhost::PathRoute =
+        serde_json::from_value(serde_json::json!({"id":"legacy"})).unwrap();
+    assert_eq!(route.source, crate::vhost::Source::ReverseProxy);
+}
+
+#[test]
+fn host_normalization() {
+    assert_eq!(request_host("EXAMPLE.com.:8080").unwrap(), "example.com");
+    for invalid in [
+        "",
+        "a..b",
+        "*.test",
+        "a/b",
+        "user@host",
+        "-bad.test",
+        "a:99999",
+    ] {
+        assert!(request_host(invalid).is_err(), "{invalid}");
+    }
+}
+#[test]
+fn wildcard_host_patterns_are_normalized_and_exact_hosts_win() {
+    assert_eq!(
+        normalize_host_pattern("*.Example.TEST.").unwrap(),
+        "*.example.test"
+    );
+    for invalid in ["*", "foo.*.test", "*.com", "*.*.example.test"] {
+        assert!(normalize_host_pattern(invalid).is_err(), "{invalid}");
+    }
+
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].id = "wildcard".into();
+    c.vhosts[0].frontend.hosts = vec!["*.example.test".into()];
+    let mut exact = c.vhosts[0].clone();
+    exact.id = "exact".into();
+    exact.frontend.hosts = vec!["api.example.test".into()];
+    c.vhosts.push(exact);
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    let local: SocketAddr = "127.0.0.1:8080".parse().unwrap();
+    assert_eq!(
+        snapshot
+            .select_on("api.example.test", "/", local, false)
+            .unwrap()
+            .id,
+        "exact/main"
+    );
+    assert_eq!(
+        snapshot
+            .select_on("www.example.test", "/", local, false)
+            .unwrap()
+            .id,
+        "wildcard/main"
+    );
+}
+#[test]
+fn logging_vhost_resolution_reuses_router_host_precedence() {
+    let mut config = demo_config("127.0.0.1:9000".parse().unwrap());
+    config.vhosts[0].id = "wildcard".into();
+    config.vhosts[0].frontend.hosts = vec!["*.example.test".into()];
+    let mut exact = config.vhosts[0].clone();
+    exact.id = "exact".into();
+    exact.frontend.hosts = vec!["api.example.test".into()];
+    config.vhosts.push(exact);
+    let snapshot = compile(config, 1, &policy()).unwrap();
+    let local: SocketAddr = "127.0.0.1:8080".parse().unwrap();
+
+    let routed = snapshot
+        .resolve_logging_vhost(
+            local,
+            false,
+            Some("wildcard"),
+            Some("api.example.test"),
+            None,
+            None,
+        )
+        .unwrap();
+    assert_eq!(routed.vhost, "wildcard");
+    assert_eq!(routed.matched_by, "router");
+
+    let exact = snapshot
+        .resolve_logging_vhost(local, false, None, Some("API.EXAMPLE.TEST:8080"), None, None)
+        .unwrap();
+    assert_eq!(exact.vhost, "exact");
+    assert_eq!(exact.matched_by, "authority");
+
+    let wildcard = snapshot
+        .resolve_logging_vhost(local, false, None, None, Some("www.example.test:8080"), None)
+        .unwrap();
+    assert_eq!(wildcard.vhost, "wildcard");
+    assert_eq!(wildcard.matched_by, "host");
+
+    let sni = snapshot
+        .resolve_logging_vhost(local, false, None, None, None, Some("api.example.test"))
+        .unwrap();
+    assert_eq!(sni.vhost, "exact");
+    assert_eq!(sni.matched_by, "sni");
+
+    assert!(snapshot
+        .resolve_logging_vhost(local, false, None, None, None, Some("unknown.test"))
+        .is_none());
+    assert!(snapshot
+        .resolve_logging_vhost(local, false, None, None, None, None)
+        .is_none());
+}
+
+#[test]
+fn reusable_acl_profile_reference_is_compiled_and_unknown_reference_fails() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.acl_profiles = serde_json::from_value(serde_json::json!([{
+        "id":"office", "name":"Office",
+        "acl":{"default":"deny","rules":[{"network":"10.0.0.0/8","action":"allow"}]},
+        "country_access":{"mode":"block","countries":["RU"]}
+    }]))
+    .unwrap();
+    c.vhosts[0].acl_profile_id = Some("office".into());
+    let snapshot = compile(c.clone(), 1, &policy()).unwrap();
+    let local: SocketAddr = "127.0.0.1:8080".parse().unwrap();
+    let frontend = snapshot.frontend("localhost", local, false).unwrap();
+    assert_eq!(frontend.acl_profile_id.as_deref(), Some("office"));
+    assert!(frontend
+        .profile_acl
+        .as_ref()
+        .unwrap()
+        .allows("10.2.3.4".parse().unwrap()));
+    assert!(!frontend
+        .profile_acl
+        .as_ref()
+        .unwrap()
+        .allows("192.0.2.1".parse().unwrap()));
+    assert!(!frontend.profile_country_access.allows(Some("RU")));
+
+    c.vhosts[0].acl_profile_id = Some("missing".into());
+    assert!(compile(c, 2, &policy()).is_err());
+}
+
+#[test]
+fn rfc8441_is_advertised_only_on_opted_in_h2_capable_listener() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].websockets = true;
+    c.vhosts[0].websocket_rfc8441 = true;
+    let error = compile(c.clone(), 1, &policy()).unwrap_err().to_string();
+    assert!(error.contains("HTTP/2-capable listener"), "{error}");
+
+    c.listeners.endpoints[0].binding.h2c = true;
+    let snapshot = compile(c.clone(), 2, &policy()).unwrap();
+    let local: SocketAddr = "127.0.0.1:8080".parse().unwrap();
+    assert!(snapshot.websocket_rfc8441_on(local, false));
+    assert!(!snapshot.websocket_rfc8441_on(local, true));
+
+    c.vhosts[0].websocket_rfc8441 = false;
+    let snapshot = compile(c, 3, &policy()).unwrap();
+    assert!(!snapshot.websocket_rfc8441_on(local, false));
+}
+#[test]
+fn force_ssl_requires_plain_http_and_chooses_https_target() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].force_ssl = true;
+    let error = compile(c.clone(), 1, &policy()).unwrap_err().to_string();
+    assert!(
+        error.contains("at least one selected TLS listener"),
+        "{error}"
+    );
+
+    c.listeners.endpoints.push(crate::settings::NamedListener {
+        id: "https-a".into(),
+        name: "HTTPS A".into(),
+        scope: crate::settings::ListenerScope::Internal,
+        enabled: true,
+        binding: crate::vhost::Listener {
+            address: "127.0.0.1:8443".parse().unwrap(),
+            tls: true,
+            http2: true,
+            http2_settings: Some(crate::settings::Http2Connections::default()),
+            h2c: false,
+            http3: None,
+        },
+        additional_addresses: vec![],
+    });
+    c.listeners.endpoints.push(crate::settings::NamedListener {
+        id: "https-b".into(),
+        name: "HTTPS B".into(),
+        scope: crate::settings::ListenerScope::Internal,
+        enabled: true,
+        binding: crate::vhost::Listener {
+            address: "127.0.0.1:9443".parse().unwrap(),
+            tls: true,
+            http2: true,
+            http2_settings: Some(crate::settings::Http2Connections::default()),
+            h2c: false,
+            http3: None,
+        },
+        additional_addresses: vec![],
+    });
+    c.vhosts[0].frontend.listener_ids = vec!["http".into(), "https-a".into(), "https-b".into()];
+    let error = compile(c.clone(), 2, &policy()).unwrap_err().to_string();
+    assert!(error.contains("cannot choose an HTTPS target"), "{error}");
+
+    c.listeners
+        .endpoints
+        .iter_mut()
+        .find(|item| item.id == "https-b")
+        .unwrap()
+        .binding
+        .address = "127.0.0.1:443".parse().unwrap();
+    let snapshot = compile(c.clone(), 3, &policy()).unwrap();
+    let frontend = snapshot
+        .frontend("localhost", "127.0.0.1:8080".parse().unwrap(), false)
+        .unwrap();
+    assert_eq!(frontend.https_redirect_port, Some(443));
+
+    c.vhosts[0].frontend.listener_ids = vec!["https-a".into(), "https-b".into()];
+    let error = compile(c, 4, &policy()).unwrap_err().to_string();
+    assert!(error.contains("plain HTTP listener"), "{error}");
+}
+#[test]
+fn backend_tls_server_name_keeps_network_origin_and_changes_verified_request_name() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].backends[0].url = "https://10.87.20.2:443".into();
+    c.vhosts[0].backends[0].allow_private = true;
+    c.vhosts[0].backends[0].tls_server_name = Some("Backend.Unitra.Internal.".into());
+    let s = compile(c, 1, &policy()).unwrap();
+    let backend = &s.pools[0].members[0].backend;
+    assert_eq!(backend.origin, "https://10.87.20.2:443");
+    assert_eq!(
+        backend.request_origin,
+        "https://backend.unitra.internal:443"
+    );
+}
+#[test]
+fn tls_server_name_is_https_dns_only() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].backends[0].tls_server_name = Some("backend.internal".into());
+    assert!(compile(c.clone(), 1, &policy()).is_err());
+    c.vhosts[0].backends[0].url = "https://10.87.20.2:443".into();
+    c.vhosts[0].backends[0].tls_server_name = Some("10.87.20.2".into());
+    assert!(compile(c, 1, &policy()).is_err());
+}
+#[test]
+fn backend_tls_verification_defaults_off_and_can_be_enabled_explicitly() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    assert!(!c.vhosts[0].backends[0].tls_verify);
+    assert!(compile(c.clone(), 1, &policy()).is_ok());
+
+    c.vhosts[0].backends[0].url = "https://10.87.20.2:443".into();
+    c.vhosts[0].backends[0].allow_private = true;
+    c.vhosts[0].backends[0].tls_ca_pem = Some("not a certificate".into());
+    assert!(compile(c.clone(), 1, &policy()).is_ok());
+
+    c.vhosts[0].backends[0].tls_verify = true;
+    assert!(compile(c, 1, &policy()).is_err());
+}
+#[test]
+fn redirect_hosts_share_listener_routing_without_opening_vhost_routes() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.redirects = serde_json::from_value(serde_json::json!([{
+            "id":"legacy","name":"Legacy","frontend":{"hosts":["old.localhost"],"listener_ids":["http"]},
+            "rules":[{"id":"root","target":"https://new.localhost/","status_code":308}]
+        }])).unwrap();
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    let local: SocketAddr = "127.0.0.1:8080".parse().unwrap();
+    let (_host, rule) = snapshot
+        .redirect_on("old.localhost", "/a", local, false)
+        .unwrap();
+    assert_eq!(rule.id, "root");
+    assert!(snapshot
+        .select_on("old.localhost", "/a", local, false)
+        .is_none());
+}
+
+#[test]
+fn custom_locations_override_but_main_vhost_remains_fallback() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    // The demo document still contains the pre-0.16 synthetic root route.
+    // Validation must normalize it away and keep the main backend internally.
+    let mut custom = c.vhosts[0].routes[0].clone();
+    custom.id = "test".into();
+    custom.path_prefix = "/test".into();
+    custom.response = Some(crate::vhost::LocationResponse {
+        status: 200,
+        content_type: "text/plain".into(),
+        body: "ok".into(),
+    });
+    c.vhosts[0].routes.push(custom);
+    let snapshot = compile(c, 1, &policy()).unwrap();
+
+    assert_eq!(
+        snapshot.select("localhost", "/test").unwrap().id,
+        "demo/test"
+    );
+    assert_eq!(
+        snapshot.select("localhost", "/test/a").unwrap().id,
+        "demo/test"
+    );
+    assert_eq!(snapshot.select("localhost", "/").unwrap().id, "demo/main");
+    assert_eq!(
+        snapshot.select("localhost", "/abc").unwrap().id,
+        "demo/main"
+    );
+    assert_eq!(
+        snapshot.select("localhost", "/static/a.js").unwrap().id,
+        "demo/main"
+    );
+    assert!(snapshot.envelope.config.vhosts[0]
+        .routes
+        .iter()
+        .all(|route| !route.is_legacy_main_fallback()));
+}
+
+#[test]
+fn deliberate_root_custom_location_can_override_main_fallback() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    let root = &mut c.vhosts[0].routes[0];
+    root.response = Some(crate::vhost::LocationResponse {
+        status: 204,
+        content_type: "text/plain".into(),
+        body: String::new(),
+    });
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    assert_eq!(
+        snapshot.select("localhost", "/anything").unwrap().id,
+        "demo/root"
+    );
+}
+
+#[test]
+fn direct_admin_listener_backend_is_marked_for_guarded_control_plane_use() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.administration.listen = Some("0.0.0.0:9090".parse().unwrap());
+    c.administration.tls = true;
+    c.vhosts[0].backends[0].url = "https://127.0.0.1:9090".into();
+    c.vhosts[0].backends[0].allow_private = true;
+    c.vhosts[0].backends[0].accept_local_listener_risk = true;
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    assert!(snapshot.pools[0].members[0].backend.targets_admin_listener);
+}
+
+#[test]
+fn backend_diagnostic_flags_compile_to_frontend() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].backend_header = true;
+    c.vhosts[0].backend_timing_header = true;
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    let local: SocketAddr = "127.0.0.1:8080".parse().unwrap();
+    let frontend = snapshot.frontend("localhost", local, false).unwrap();
+    assert!(frontend.backend_header);
+    assert!(frontend.backend_timing_header);
+}
+
+
+#[test]
+fn path_boundaries() {
+    assert!(prefix_matches("/api", "/api"));
+    assert!(prefix_matches("/api", "/api/users"));
+    assert!(!prefix_matches("/api", "/apix"));
+    assert!(prefix_matches("/", "/anything"));
+}
+#[test]
+fn invalid_per_backend_health_policy_rejected_without_global_override() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].backends[0].health_check = Some(crate::balance::HealthCheck {
+        mode: crate::balance::HealthMode::Http,
+        interval_ms: 300,
+        timeout_ms: 400,
+        ..Default::default()
+    });
+    assert!(compile(c.clone(), 1, &policy()).is_err());
+    c.vhosts[0].backends[0].health_check.as_mut().unwrap().timeout_ms = 200;
+    assert!(compile(c, 1, &policy()).is_ok());
+}
+#[test]
+fn private_requires_opt_in_and_metadata_always_denied() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    assert!(compile(c.clone(), 1, &policy()).is_ok());
+    c.vhosts[0].backends[0].allow_private = false;
+    assert!(compile(c.clone(), 1, &policy()).is_err());
+    c.vhosts[0].backends[0].allow_private = true;
+    for target in [
+        "http://169.254.169.254",
+        "http://100.100.100.200",
+        "http://0.0.0.0",
+        "http://127.0.0.1:9090",
+        "http://[::ffff:169.254.169.254]",
+        "http://[fe80::1]",
+        "http://user:pass@127.0.0.1:9000",
+    ] {
+        c.vhosts[0].backends[0].url = target.into();
+        assert!(compile(c.clone(), 1, &policy()).is_err(), "{target}");
+    }
+    c.vhosts[0].backends[0].url = "http://127.0.0.1:9090".into();
+    c.vhosts[0].backends[0].accept_local_listener_risk = true;
+    assert!(compile(c.clone(), 1, &policy()).is_ok());
+    c.vhosts[0].backends[0].allow_private = false;
+    assert!(compile(c, 1, &policy()).is_err());
+}
+#[test]
+fn longest_prefix_and_aliases() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    let mut specific = c.vhosts[0].routes[0].clone();
+    specific.id = "api".into();
+    specific.path_prefix = "/api".into();
+    c.vhosts[0].routes.push(specific);
+    let s = compile(c, 7, &policy()).unwrap();
+    assert_eq!(s.select("localhost", "/api/x").unwrap().id, "demo/api");
+    assert_eq!(s.select("demo.localhost", "/apix").unwrap().id, "demo/main");
+    assert!(s.select("unknown", "/").is_none());
+    assert_eq!(s.envelope.revision, 7);
+}
+#[test]
+fn nginx_style_location_precedence_exact_priority_regex_prefix() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].routes[0].id = "root".into();
+
+    let mut prefix = c.vhosts[0].routes[0].clone();
+    prefix.id = "api-prefix".into();
+    prefix.path_prefix = "/api".into();
+
+    let mut regex = c.vhosts[0].routes[0].clone();
+    regex.id = "api-regex".into();
+    regex.match_type = crate::vhost::PathMatch::Regex;
+    regex.path_prefix = r"^/api/v[0-9]+/".into();
+
+    let mut exact = c.vhosts[0].routes[0].clone();
+    exact.id = "api-exact".into();
+    exact.match_type = crate::vhost::PathMatch::Exact;
+    exact.path_prefix = "/api/v1/fixed".into();
+
+    let mut trailing_exact = c.vhosts[0].routes[0].clone();
+    trailing_exact.id = "trailing-exact".into();
+    trailing_exact.match_type = crate::vhost::PathMatch::Exact;
+    trailing_exact.path_prefix = "/trailing/".into();
+
+    c.vhosts[0]
+        .routes
+        .extend([prefix.clone(), regex, exact, trailing_exact]);
+    let snapshot = compile(c.clone(), 1, &policy()).unwrap();
+    assert_eq!(
+        snapshot.select("localhost", "/api/v1/fixed").unwrap().id,
+        "demo/api-exact"
+    );
+    assert_eq!(
+        snapshot.select("localhost", "/api/v2/users").unwrap().id,
+        "demo/api-regex"
+    );
+    assert_eq!(
+        snapshot.select("localhost", "/api/plain").unwrap().id,
+        "demo/api-prefix"
+    );
+    assert_eq!(
+        snapshot.select("localhost", "/trailing/").unwrap().id,
+        "demo/trailing-exact"
+    );
+    assert_eq!(
+        snapshot.select("localhost", "/trailing").unwrap().id,
+        "demo/main"
+    );
+
+    c.vhosts[0].routes.retain(|route| route.id != "api-prefix");
+    prefix.match_type = crate::vhost::PathMatch::PrefixPriority;
+    prefix.id = "api-priority".into();
+    c.vhosts[0].routes.push(prefix);
+    let snapshot = compile(c, 2, &policy()).unwrap();
+    assert_eq!(
+        snapshot.select("localhost", "/api/v2/users").unwrap().id,
+        "demo/api-priority"
+    );
+}
+#[test]
+fn location_rewrites_are_normalized_and_regex_captures_expand() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    let route = &mut c.vhosts[0].routes[0];
+    route.match_type = crate::vhost::PathMatch::Regex;
+    route.path_prefix = r"^/api/v([0-9]+)(/.*)$".into();
+    route.rewrite = crate::vhost::PathRewrite {
+        mode: crate::vhost::RewriteMode::Regex,
+        value: "/service/${1}${2}".into(),
+    };
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    let selected = snapshot.select("localhost", "/api/v42/items").unwrap();
+    assert_eq!(
+        selected
+            .rewritten_path("/api/v42/items")
+            .unwrap()
+            .as_deref(),
+        Some("/service/42/items")
+    );
+    assert_eq!(
+        selected
+            .rewritten_path("/api/v42/Ubuntu 14.04 LTS")
+            .unwrap()
+            .as_deref(),
+        Some("/service/42/Ubuntu 14.04 LTS")
+    );
+}
+#[test]
+fn custom_location_response_is_validated() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].routes[0].response = Some(crate::vhost::LocationResponse {
+        status: 200,
+        content_type: "application/json".into(),
+        body: r#"{"ok":true}"#.into(),
+    });
+    assert!(compile(c.clone(), 1, &policy()).is_ok());
+    c.vhosts[0].routes[0].response.as_mut().unwrap().status = 199;
+    assert!(compile(c.clone(), 1, &policy()).is_err());
+    c.vhosts[0].routes[0].response.as_mut().unwrap().status = 200;
+    c.vhosts[0].routes[0]
+        .response
+        .as_mut()
+        .unwrap()
+        .content_type = "text/plain\r\nx-bad: 1".into();
+    assert!(compile(c, 1, &policy()).is_err());
+}
+#[test]
+fn local_response_hosts_reserve_frontends_and_do_not_require_backends() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.not_found_hosts = serde_json::from_value(serde_json::json!([{
+        "id":"missing",
+        "name":"Missing site",
+        "frontend":{"hosts":["missing.localhost"],"listener_ids":["http"]},
+        "page":{"kind":"html","status":404,"html":"<h1>Not found</h1>"}
+    }]))
+    .unwrap();
+    let snapshot = compile(c.clone(), 1, &policy()).unwrap();
+    let local: SocketAddr = "127.0.0.1:8080".parse().unwrap();
+    let host = snapshot
+        .not_found_host_on("missing.localhost", local, false)
+        .unwrap();
+    assert_eq!(host.id, "missing");
+    assert_eq!(host.page.status, Some(404));
+
+    c.not_found_hosts[0].frontend.hosts = vec!["localhost".into()];
+    assert!(compile(c, 2, &policy()).is_err());
+}
+
+#[test]
+fn conflicts_are_rejected() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    let mut duplicate = c.vhosts[0].routes[0].clone();
+    duplicate.id = "other".into();
+    c.vhosts[0].routes.push(duplicate);
+    assert!(compile(c, 0, &policy()).is_err());
+}
+#[test]
+fn tls12_only_vhost_override_is_valid_without_http3_listener() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].tls_policy = Some(crate::tls::ProtocolPolicy {
+        tls12: true,
+        tls13: false,
+        cipher_suites: vec![],
+    });
+    assert!(compile(c, 1, &policy()).is_ok());
+}
+
+#[test]
+fn persisted_remote_administration_requires_tls() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.administration.listen = Some("192.0.2.10:9090".parse().unwrap());
+    assert!(compile(c.clone(), 1, &policy()).is_err());
+    c.administration.tls = true;
+    assert!(compile(c, 1, &policy()).is_ok());
+}
+#[test]
+fn legacy_startup_remote_administration_is_left_to_cli_risk_gate() {
+    let mut p = policy();
+    p.admin_addr = "0.0.0.0:9090".parse().unwrap();
+    let c = demo_config("127.0.0.1:9000".parse().unwrap());
+    assert!(c.administration.listen.is_none());
+    assert!(compile(c, 1, &p).is_ok());
+}
+
+#[test]
+fn www_redirect_claims_companion_hostname_and_keeps_first_host_canonical() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].frontend.hosts = vec!["example.test".into()];
+    c.vhosts[0].www_redirect = true;
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    assert!(snapshot.select("www.example.test", "/path").is_some());
+    let frontend = snapshot
+        .frontend("www.example.test", "127.0.0.1:8080".parse().unwrap(), false)
+        .unwrap();
+    assert_eq!(
+        frontend.www_redirect.as_ref(),
+        Some(&("www.example.test".into(), "example.test".into()))
+    );
+}
+
+#[test]
+fn multiple_domains_share_vhost_and_selected_canonical_redirect() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].frontend.hosts = vec![
+        "suba.local".into(), "subb.local".into(), "site.test".into(),
+    ];
+    c.vhosts[0].www_redirect = true;
+    c.vhosts[0].www_redirect_target = Some("site.test".into());
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    for hostname in ["suba.local", "subb.local", "site.test", "www.site.test"] {
+        assert!(snapshot.select(hostname, "/same").is_some(), "{hostname}");
+    }
+    for hostname in ["suba.local", "subb.local", "www.site.test"] {
+        let frontend = snapshot.frontend(hostname, "127.0.0.1:8080".parse().unwrap(), false).unwrap();
+        assert_eq!(frontend.www_redirect.as_ref(),
+            Some(&("www.site.test".into(), "site.test".into())));
+    }
+}
+
+#[test]
+fn implicit_www_target_is_claimed_and_other_domain_stays_independent() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].frontend.hosts = vec!["suba.local".into(), "subb.local".into()];
+    c.vhosts[0].www_redirect = true;
+    c.vhosts[0].www_redirect_target = Some("www.subb.local".into());
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    for host in ["suba.local", "subb.local", "www.subb.local"] {
+        assert!(snapshot.select(host, "/path").is_some(), "{host}");
+    }
+    assert!(snapshot.select("www.suba.local", "/path").is_none());
+    let frontend = snapshot.frontend("subb.local", "127.0.0.1:8080".parse().unwrap(), false).unwrap();
+    assert_eq!(frontend.www_redirect.as_ref(),
+        Some(&(String::from("subb.local"), String::from("www.subb.local"))));
+}
+
+#[test]
+fn selected_www_redirect_target_must_belong_to_vhost() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].frontend.hosts = vec!["suba.local".into()];
+    c.vhosts[0].www_redirect = true;
+    c.vhosts[0].www_redirect_target = Some("elsewhere.local".into());
+    assert!(compile(c, 1, &policy()).is_err());
+}
+
+#[test]
+fn http_health_check_defaults_host_to_first_exact_vhost_dns_name() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].frontend.hosts = vec!["app.example.test".into()];
+    c.vhosts[0].load_balancing.health_check.mode = crate::balance::HealthMode::Http;
+    c.vhosts[0].load_balancing.health_check.host = None;
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    assert_eq!(
+        snapshot.pools[0].settings.health_check.host.as_deref(),
+        Some("app.example.test")
+    );
+}
+
+#[test]
+fn per_member_http_health_inherits_vhost_dns_even_when_global_health_is_tcp() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].frontend.hosts = vec!["app.example.test".into()];
+    assert_eq!(c.vhosts[0].load_balancing.health_check.mode, crate::balance::HealthMode::Tcp);
+    c.vhosts[0].backends[0].health_check = Some(crate::balance::HealthCheck {
+        mode: crate::balance::HealthMode::Http, path: "/healthz".into(), ..Default::default()
+    });
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    let pool = &snapshot.pools[0];
+    assert_eq!(pool.settings.health_for(&pool.members[0].definition).host.as_deref(), Some("app.example.test"));
+}
+#[test]
+fn explicit_http_health_check_host_override_wins_over_vhost_hostname() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].frontend.hosts = vec!["app.example.test".into()];
+    c.vhosts[0].load_balancing.health_check.mode = crate::balance::HealthMode::Http;
+    c.vhosts[0].load_balancing.health_check.host = Some("health.example.test".into());
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    assert_eq!(
+        snapshot.pools[0].settings.health_check.host.as_deref(),
+        Some("health.example.test")
+    );
+}
+
+#[test]
+fn custom_location_redirect_supports_separate_capture_regex_and_query() {
+    let mut c = demo_config("127.0.0.1:9000".parse().unwrap());
+    c.vhosts[0].routes = vec![crate::vhost::PathRoute {
+        id: "archives".into(),
+        path_prefix: r"\.(?:tar\.gz|zip?)$".into(),
+        match_type: crate::vhost::PathMatch::RegexInsensitive,
+        response: None,
+        redirect: Some(crate::vhost::LocationRedirect {
+            status: 301,
+            target: "https://storage.example.test/o/$1".into(),
+            rewrite_pattern: Some(r"^/(.*)$".into()),
+            preserve_query: true,
+        }),
+        ..Default::default()
+    }];
+    let snapshot = compile(c, 1, &policy()).unwrap();
+    let route = snapshot.select("localhost", "/repo/file.tar.gz").unwrap();
+    let uri: http::Uri = "/repo/file.tar.gz?download=1".parse().unwrap();
+    let location = route
+        .redirect_location("/repo/file.tar.gz", &uri)
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        location,
+        "https://storage.example.test/o/repo/file.tar.gz?download=1"
+    );
+}
+
+#[test]
+fn shared_php_fpm_profile_is_reused_and_detach_restores_local_configuration() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    std::fs::write(tmp.path().join("index.php"), b"<?php echo 'ok';").unwrap();
+    let mut config = demo_config("127.0.0.1:9000".parse().unwrap());
+    config.php_fpm_profiles.push(crate::web_server::PhpFpmProfile {
+        id: "php-default".into(),
+        name: "Default PHP pool".into(),
+        php: crate::web_server::Php {
+            enabled: true,
+            endpoint: "tcp:127.0.0.1:9000".into(),
+            ..Default::default()
+        },
+    });
+    let service = crate::web_server::Service {
+        id: "site-one".into(),
+        name: "Site One".into(),
+        document_root: tmp.path().to_path_buf(),
+        php_profile_id: Some("php-default".into()),
+        // Standalone settings remain distinct and disabled.
+        php: crate::web_server::Php::default(),
+        ..Default::default()
+    };
+    let mut second = service.clone();
+    second.id = "site-two".into();
+    second.name = "Site Two".into();
+    config.web_services.extend([service, second]);
+    config.vhosts[0].source = crate::vhost::Source::WebServer {
+        web_service_id: "site-one".into(),
+    };
+    config.vhosts[0].routes.clear();
+    config.vhosts[0].backends.clear();
+
+    let snapshot = compile(config, 1, &policy()).unwrap();
+    for id in ["site-one", "site-two"] {
+        let compiled = snapshot.web_php_services.get(id).unwrap();
+        assert!(compiled.php.is_some(), "{id} must use the shared FPM profile");
+    }
+    assert_eq!(snapshot.envelope.config.php_fpm_profiles.len(), 1);
+    assert!(!snapshot.envelope.config.web_services[0].php.enabled);
+    assert!(!snapshot.envelope.config.web_services[1].php.enabled);
+
+    let serialized = serde_json::to_string(&snapshot.envelope.config).unwrap();
+    let mut detached: Config = serde_json::from_str(&serialized).unwrap();
+    detached.web_services[0].php_profile_id = None;
+    let snapshot = compile(detached, 2, &policy()).unwrap();
+    assert!(snapshot.web_php_services.get("site-one").unwrap().php.is_none());
+    assert!(snapshot.web_php_services.get("site-two").unwrap().php.is_some());
+}
+
+#[test]
+fn shared_php_fpm_profile_reference_and_duplicate_ids_are_rejected() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    let mut config = demo_config("127.0.0.1:9000".parse().unwrap());
+    config.web_services.push(crate::web_server::Service {
+        id: "site".into(),
+        name: "Site".into(),
+        document_root: tmp.path().to_path_buf(),
+        php_profile_id: Some("missing".into()),
+        ..Default::default()
+    });
+    let err = compile(config.clone(), 1, &policy()).unwrap_err().to_string();
+    assert!(err.contains("unknown PHP-FPM profile"), "{err}");
+    config.web_services[0].php_profile_id = None;
+    let profile = crate::web_server::PhpFpmProfile {
+        id: "duplicate".into(),
+        name: "Duplicate".into(),
+        php: Default::default(),
+    };
+    config.php_fpm_profiles = vec![profile.clone(), profile];
+    let err = compile(config, 1, &policy()).unwrap_err().to_string();
+    assert!(err.contains("duplicate PHP-FPM profile"), "{err}");
+}
 }

src/geoip.rs

@@ -29,8 +29,10 @@ struct V4Range {
 }
 #[derive(Debug, Clone, Copy)]
 struct V6Range {
-    start: u128,
-    end: u128,
+    // Network byte order preserves the numeric ordering of IPv6 addresses
+    // without the 16-byte alignment/padding of u128 fields.
+    start: [u8; 16],
+    end: [u8; 16],
     country: [u8; 2],
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -48,7 +50,7 @@ impl Default for DatabaseFormat {
 
 #[derive(Debug)]
 enum Backend {
-    Csv { ipv4: Vec<V4Range>, ipv6: Vec<V6Range> },
+    Csv { ipv4: Box<[V4Range]>, ipv6: Box<[V6Range]> },
     Mmdb(mmdb::Database),
 }
 
@@ -66,7 +68,7 @@ pub struct View {
 }
 impl Database {
     pub fn empty() -> Self {
-        Self { backend: Backend::Csv { ipv4: Vec::new(), ipv6: Vec::new() } }
+        Self { backend: Backend::Csv { ipv4: Box::new([]), ipv6: Box::new([]) } }
     }
     pub fn load(directory: &Path) -> Result<Self> {
         if directory.join("country.mmdb").is_file() {
@@ -81,7 +83,9 @@ impl Database {
                 let ipv4 = parse_v4(&directory.join("user-country-ipv4.csv"))?;
                 let ipv6 = parse_v6(&directory.join("user-country-ipv6.csv"))?;
                 ensure!(!ipv4.is_empty() && !ipv6.is_empty(), "GeoIP country database is empty");
-                Ok(Self { backend: Backend::Csv { ipv4, ipv6 } })
+                // Convert to exactly sized immutable slices: the CSV parser may have
+                // doubled Vec capacity many times during loading.
+                Ok(Self { backend: Backend::Csv { ipv4: ipv4.into_boxed_slice(), ipv6: ipv6.into_boxed_slice() } })
             }
             DatabaseFormat::Mmdb => Ok(Self {
                 backend: Backend::Mmdb(mmdb::Database::load(&directory.join("country.mmdb"), MAX_FILE_BYTES)?),
@@ -118,7 +122,7 @@ impl Database {
             Backend::Csv { ipv4, ipv6 } => {
                 let code = match ip {
                     IpAddr::V4(ip) => find_v4(ipv4, u32::from(ip)),
-                    IpAddr::V6(ip) => find_v6(ipv6, u128::from(ip)),
+                    IpAddr::V6(ip) => find_v6(ipv6, u128::from(ip).to_be_bytes()),
                 }?;
                 Some(String::from_utf8_lossy(&code).into_owned())
             }
@@ -227,8 +231,8 @@ fn parse_v6(path: &Path) -> Result<Vec<V6Range>> {
         previous_end = Some(end);
         if let Some(country) = normalize_country_code(country) {
             result.push(V6Range {
-                start,
-                end,
+                start: start.to_be_bytes(),
+                end: end.to_be_bytes(),
                 country,
             });
             ensure!(result.len() <= MAX_RANGES, "too many GeoIP IPv6 ranges");
@@ -243,7 +247,7 @@ fn find_v4(ranges: &[V4Range], ip: u32) -> Option<[u8; 2]> {
     let item = ranges.get(index)?;
     (ip <= item.end).then_some(item.country)
 }
-fn find_v6(ranges: &[V6Range], ip: u128) -> Option<[u8; 2]> {
+fn find_v6(ranges: &[V6Range], ip: [u8; 16]) -> Option<[u8; 2]> {
     let index = ranges
         .partition_point(|item| item.start <= ip)
         .checked_sub(1)?;

src/geoip/tests.rs

@@ -1,6 +1,24 @@
 mod tests {
     use super::*;
 
+    #[test]
+    fn compact_ipv6_ranges_preserve_numeric_order() {
+        assert_eq!(std::mem::size_of::<V6Range>(), 34);
+        assert_eq!(std::mem::size_of::<V4Range>(), 12);
+        let ranges = [
+            V6Range { start: 0u128.to_be_bytes(), end: 127u128.to_be_bytes(), country: *b"PL" },
+            V6Range { start: 256u128.to_be_bytes(), end: 65535u128.to_be_bytes(), country: *b"DE" },
+            V6Range { start: (1u128 << 120).to_be_bytes(), end: u128::MAX.to_be_bytes(), country: *b"US" },
+        ];
+        for (address, expected) in [
+            (0, Some(*b"PL")), (127, Some(*b"PL")), (128, None),
+            (255, None), (256, Some(*b"DE")), (65535, Some(*b"DE")),
+            (65536, None), (1u128 << 120, Some(*b"US")), (u128::MAX, Some(*b"US")),
+        ] {
+            assert_eq!(find_v6(&ranges, address.to_be_bytes()), expected);
+        }
+    }
+
     #[test]
     fn range_lookup_handles_gaps() {
         let directory = tempfile::tempdir().unwrap();

src/pages.rs

@@ -8,26 +8,58 @@ use std::collections::BTreeMap;
 
 pub const MAX_HTML_BYTES: usize = 32 * 1024;
 pub const ERROR_CODES: [u16; 11] = [400, 401, 403, 404, 408, 413, 429, 500, 502, 503, 504];
-pub const BUILTIN_ERROR_CODES: [u16; 6] = [401, 403, 404, 429, 503, 504];
+pub const BUILTIN_ERROR_CODES: [u16; 12] = [400, 401, 403, 404, 408, 410, 413, 429, 500, 502, 503, 504];
 
 /// Built-in operational gateway pages. They are deliberately not marked as
 /// `PageServed`, so an administrator-configured vhost/global error page can
 /// still replace them in the normal response policy pass.
 pub fn builtin_gateway_error(status: StatusCode) -> Option<&'static str> {
     match status {
+        StatusCode::BAD_REQUEST => Some(include_str!("admin/web/error_400.html")),
         StatusCode::UNAUTHORIZED => Some(include_str!("admin/web/error_401.html")),
         StatusCode::FORBIDDEN => Some(include_str!("admin/web/error_403.html")),
         StatusCode::NOT_FOUND => Some(include_str!("admin/web/error_404.html")),
+        StatusCode::REQUEST_TIMEOUT => Some(include_str!("admin/web/error_408.html")),
+        StatusCode::GONE => Some(include_str!("admin/web/error_410.html")),
+        StatusCode::PAYLOAD_TOO_LARGE => Some(include_str!("admin/web/error_413.html")),
         StatusCode::TOO_MANY_REQUESTS => Some(include_str!("admin/web/error_429.html")),
+        StatusCode::INTERNAL_SERVER_ERROR => Some(include_str!("admin/web/error_500.html")),
+        StatusCode::BAD_GATEWAY => Some(include_str!("admin/web/error_502.html")),
         StatusCode::SERVICE_UNAVAILABLE => Some(include_str!("admin/web/error_503.html")),
         StatusCode::GATEWAY_TIMEOUT => Some(include_str!("admin/web/error_504.html")),
         _ => None,
     }
 }
 fn builtin_application_page(status: StatusCode) -> String {
-    if let Some(page) = builtin_gateway_error(status) { return page.to_owned(); }
-    let reason = status.canonical_reason().unwrap_or("Application response");
-    format!(r#"<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>{code} {reason}</title><style>body{{font-family:system-ui,sans-serif;max-width:42rem;margin:12vh auto;padding:0 1.5rem;color:#1f2937}}h1{{font-size:4rem;margin:0}}p{{font-size:1.1rem;color:#4b5563}}</style></head><body><h1>{code}</h1><p>{reason}</p><p>RustProxy</p></body></html>"#, code=status.as_u16(), reason=reason)
+    if status == StatusCode::OK {
+        return include_str!("admin/web/status_200.html").to_owned();
+    }
+    if let Some(page) = builtin_gateway_error(status) {
+        return page.to_owned();
+    }
+    // A deliberately generic status still uses the *same* visual language
+    // as the packaged pages, rather than the former bright bare 200/4xx page.
+    // Code and canonical reason originate from http::StatusCode, never a request.
+    let reason = status.canonical_reason().unwrap_or("Response");
+    format!(r#"<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>{code} - {reason} - RustProxy</title>
+    <style>
+        body {{ margin: 12vh auto; padding: 24px; max-width: 620px; background: #131615; color: #e5e9e6; font: 15px/1.6 system-ui, sans-serif }}
+        h1 {{ font-size: 24px; margin: 0 0 8px }}
+        p {{ margin: 0; color: #b9c3bc }}
+    </style>
+</head>
+<body>
+    <main>
+        <h1>{code} - {reason}</h1>
+        <p>RustProxy generated this response.</p>
+    </main>
+</body>
+</html>"#, code = status.as_u16(), reason = reason)
 }
 
 #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]

src/pages/tests.rs

@@ -77,7 +77,21 @@ mod tests {
         assert!(builtin_gateway_error(StatusCode::GATEWAY_TIMEOUT)
             .unwrap()
             .contains("504 - Gateway timeout"));
-        assert!(builtin_gateway_error(StatusCode::BAD_GATEWAY).is_none());
+        for (code, label) in [
+            (StatusCode::BAD_REQUEST, "400 - Bad request"),
+            (StatusCode::REQUEST_TIMEOUT, "408 - Request timeout"),
+            (StatusCode::GONE, "410 - Gone"),
+            (StatusCode::PAYLOAD_TOO_LARGE, "413 - Payload too large"),
+            (StatusCode::INTERNAL_SERVER_ERROR, "500 - Internal server error"),
+            (StatusCode::BAD_GATEWAY, "502 - Bad gateway"),
+        ] {
+            let page = builtin_gateway_error(code).unwrap();
+            assert!(page.contains(label));
+            assert!(page.contains("background: #131615"));
+        }
+        assert!(builtin_gateway_error(StatusCode::OK).is_none());
+        assert!(builtin_application_page(StatusCode::OK).contains("200 - OK"));
+        assert!(builtin_application_page(StatusCode::CREATED).contains("background: #131615"));
     }
     #[test]
     fn validated_bounded_pages_and_ip_detection() {