v0.34.12

docs/CACHE.md

@@ -80,6 +80,44 @@ done
 
 Look for cache reason labels including `request_cookie`, `request_authorization`, `response_cache_control`, `route_disabled` and `cache_hit` when diagnostic headers are enabled. A `MISS` alone does not prove the object was admitted to HOT/COLD.
 
+## Cache response headers and upstream diagnostics (0.34.12)
+
+**RFC 9211:** `Cache-Status` is a structured list of cache hops, ordered from the origin-side cache toward the client. RustProxy **does not replace or suppress** an upstream `Cache-Status`. When **Settings → Cache → Expose Cache-Status** is enabled and RustProxy makes a cache decision, it appends its own `RustProxy` member to the existing list; multiple HTTP header fields are an equivalent wire representation of the same list. There is no `backend=hit/miss` parameter: the upstream's own members already describe its cache decisions.
+
+For example, with an upstream HIT and a RustProxy HIT:
+
+```http
+Cache-Status: BackendCache; hit; ttl=500
+Cache-Status: RustProxy; hit; ttl=482; detail="cache_hit"
+X-Cache: HIT
+```
+
+On first fill, RustProxy uses `RustProxy; fwd=miss; detail="cache_miss"` (unless another forwarding reason applies). A cache policy BYPASS uses `fwd=bypass`, and reuse of a stored body following origin `304` validation is reported as `fwd=stale; fwd-status=304`, **not** a fresh unforwarded RFC 9211 HIT. The existing `X-Cache: HIT` for that validation remains for legacy monitoring compatibility. The `ttl` parameter counts remaining seconds for a RustProxy HIT, not the upstream's TTL, and `detail` is a fixed RustProxy reason code. The optional `transformed` extension on RustProxy's member is applied only to its own entry.
+
+**Legacy collisions:** `X-Cache`, `X-Cache-Hits`, `X-Cache-Reason` and `X-Cache-Resident-Age` are non-standard response fields. They do not define interoperable append/list semantics. When RustProxy is configured to emit a particular field, it owns that field and copies all origin values (if any) into `X-Upstream-Cache`, `X-Upstream-Cache-Hits`, `X-Upstream-Cache-Reason`, or `X-Upstream-Cache-Resident-Age` respectively. For example:
+
+```http
+X-Cache: HIT
+X-Upstream-Cache: MISS
+Cache-Status: BackendCache; fwd=miss
+Cache-Status: RustProxy; hit; ttl=482; detail="cache_hit"
+```
+
+Here, the upstream MISS is the **original backend state when RustProxy filled the object**; it is not a fresh backend measurement on every RustProxy HIT. `X-Cache-Status` is forwarded unchanged because RustProxy does not generate that field. The `X-Upstream-*` aliases are a compatibility convenience, **not RFC 9211**; for new integrations use `Cache-Status` instead. Upstream headers are relayed as provided, without verifying the upstream's diagnostic accuracy.
+
+**Display switches:** `Expose cache status`, `Expose cache hits`, `Expose cache resident age`, `Expose Cache-Status` and `Only on HIT` control **only RustProxy-generated headers**, not origin-supplied headers. Even when RustProxy caching is disabled, or a MISS/BYPASS is hidden by the Only on HIT option, backend-provided cache diagnostics remain visible. The `Via` header is governed separately by its configured cache policy. Backend diagnostics persist with eligible cached objects in HOT and COLD; responses which were never cacheable are still forwarded with their upstream fields intact.
+
+To verify on a cacheable URL, use **GET** twice, without forced reload:
+
+```bash
+URL=https://example.com/public.css
+for n in 1 2; do
+  curl -sS -D - -o /dev/null "$URL" | grep -iE '^(HTTP/|age:|cache-status:|x-cache:|x-upstream-cache:|x-cache-hits:|x-upstream-cache-hits:)'
+done
+```
+
+The initial request can show `RustProxy; fwd=miss`; an eligible repeat should show `RustProxy; hit; ttl=...`. If the origin sends no `Cache-Status`, there is no upstream member to display. If RustProxy diagnostic output is off, any visible `Cache-Status` is from upstream; absence of a RustProxy member is expected. The actual cache outcome should also be checked in server request logs.
+
 ## Advanced behavior
 
 - **Budget limits:** HOT RAM capacity, object count/size, transient fill memory and optional COLD byte/object limits. Configure based on real workload and monitor disk/RSS.

docs/DASHBOARD.md

@@ -32,6 +32,16 @@ Unfinished editors may be minimized into a draft dock; this is a UI convenience
 
 **Configuration history** stores retained validated snapshots. Restoring a snapshot creates a new configuration revision. It does not restore every filesystem file, external certificate, Secret Store key or accumulated cache/log history. For disaster recovery, use a full encrypted backup; see [Backup](BACKUP.md).
 
+## Optional X/Y scales
+
+Under **Settings → Appearance → Charts**, turn on **Show X/Y scales on charts**. It is **off by default**, stored per administrator through `chart_axes: true|false` in `/api/preferences`, and can be reset with **Reset section** or **Reset appearance**. No routing or persistent metric collection changes are required. The optional labels cover sampled SVG line charts in Overview (including backend, cache, Web Server, Stream and optional extra panels), Vhosts, Docker Vhosts, Streams, Web Server live metrics, Cache and Transform activity. Donuts, progress meters and categorical breakdowns have no X/Y sample axes.
+
+- **Y:** `0` through the exact range used to plot the series, using suitable units such as `%`, `ms`, `B`, `B/s` or `/s`. Existing auto-ranging, fixed 0–100% scales and adaptive Vhost/Docker percentile scales are **not recalculated or replaced**. If an isolated Vhost peak is clipped, its actual maximum remains in the legend and the scale annotation identifies the clipped range. On HTTP and WebSocket protocol mini charts where each line is independently normalized, separate Y ranges for H1/H2/H3 are shown rather than an incorrect shared axis.
+- **X:** numbers **1 ... N** identify samples in the displayed history, not elapsed seconds or minutes. Sampling can pause and Vhost/Docker/Stream lifetime histories can compact older readings into buckets. The X axis never pretends that sample spacing is uniform time.
+- Labels are HTML overlays/footers rather than SVG text so they remain legible with `preserveAspectRatio="none"`. The original SVG path geometry, visible data, styling and refresh rates are unchanged. Switching axes off unwraps the existing SVGs; charts return to their previous appearance without restarting the panel.
+
+If axis labels look crowded in a small card or on mobile, disable the setting; the default presentation is unchanged.
+
 ## Interpreting charts
 
 - The **Cache hit ratio** donut shows cumulative `HIT / (HIT + MISS)`: BYPASS and requests outside cache are deliberately excluded from its denominator.

docs/README.md

@@ -1,6 +1,6 @@
 # RustProxy documentation
 
-Practical guides for **RustProxy 0.34.11**. This index and the listed pages are also available in the authenticated panel at **`/docs → Reader`**. The adjacent **API** tab provides the embedded OpenAPI reference. Paths below are links to actual files in the source archive.
+Practical guides for **RustProxy 0.34.12**. This index and the listed pages are also available in the authenticated panel at **`/docs → Reader`**. The adjacent **API** tab provides the embedded OpenAPI reference. Paths below are links to actual files in the source archive.
 
 ## Getting started
 
@@ -16,13 +16,13 @@ Practical guides for **RustProxy 0.34.11**. This index and the listed pages are
 - [Access and authentication](ACCESS.md) — ACL, country/DDNS, Basic Auth, Tinyauth and rate limits.
 - [Static Web Server](WEB_SERVER.md) — document roots, generated filesystem permission commands, downloads, rules, built-in error pages and file delivery.
 - [PHP-FPM](PHP_FPM.md) — PHP service profiles, security and application examples.
-- [Cache](CACHE.md) — HOT/COLD storage, privacy, TTL and invalidation.
+- [Cache](CACHE.md) — HOT/COLD storage, privacy, TTL, RFC 9211 `Cache-Status`, origin diagnostic headers and invalidation.
 - [Response delivery](RESPONSE_DELIVERY.md) — compression, static transformations and response headers.
 - [HTTP transport](TRANSPORT.md) — HTTPS/H2/H3, WebSockets, origin protocols and timeouts.
 - [Experimental TLS post-quantum key exchange](TLS_POST_QUANTUM.md) — opt-in X25519MLKEM768, compatibility, rollback and validation.
 - [TCP/UDP Streams](STREAMS.md) — non-HTTP forwarding and its security boundaries.
 
-The Vhosts and Docker discovery guides include the shared adaptive request-rate chart scale introduced in 0.34.11, including how high peaks are displayed without hiding ordinary traffic.
+The Vhosts and Docker discovery guides include the shared adaptive request-rate chart scale introduced in 0.34.11. Version 0.34.12 preserves that adaptive range and adds a disabled-by-default X/Y scale display option under **Settings → Appearance → Charts**. See [Dashboard](DASHBOARD.md).
 
 ## Integrations and operations
 

docs/TLS_POST_QUANTUM.md

@@ -1,7 +1,5 @@
 # Experimental post-quantum TLS key exchange (PQC)
 
-**Version:** introduced in RustProxy 0.34.9; included in the 0.34.11 source candidate. **Default: off.** This is an experimental opt-in feature and not a production compatibility guarantee.
-
 ## What it does
 
 Post-quantum cryptography (PQC) aims to protect key exchange from attackers with future quantum computing capabilities. **X25519MLKEM768** combines a conventional X25519 ephemeral key agreement with post-quantum **ML-KEM-768** in one TLS 1.3 *hybrid key-exchange group*. Both contributions protect the derived traffic secret. This is **not a TLS cipher suite**: AES-GCM or ChaCha20-Poly1305 and ordinary X.509 RSA/ECDSA certificates remain in use. It does not change certificate signatures to post-quantum algorithms, and does not make all parts of TLS quantum-safe.