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.