RustProxy/docs/V0.21.0_AUDIT.md

RustProxy 0.21.0 specification audit

Status vocabulary

• SOURCE-FIXED: a concrete source defect found during this audit was changed and regression coverage was added. Rust execution is still pending in this workspace.
• SOURCE-AUDITED: the required implementation and source-level regression coverage are present; live/runtime acceptance is still pending where applicable.
• DEFERRED: intentionally moved out of the closed 0.21.0 feature scope.
• RUNTIME OPEN: source work is present, but the required compiler/live test cannot be completed in this workspace.

Main TODO audit

#	Requirement	Status	Audit result
1	Transformed response stored in cache	SOURCE-FIXED	Plan::restrict() uses transformed Content-Length; transformed bytes are stored and reused.
2	Full request max-stale semantics	SOURCE-FIXED	Freshness and retention are separated; bounded/unbounded max-stale and revalidation flags have regressions.
3	Request max-age=N	SOURCE-FIXED	Only max-age=0 forces validation unconditionally; other values are checked against cached age.
4	HEAD + transform + cache	SOURCE-FIXED / RUNTIME OPEN	Cacheable HEAD fills through internal GET; cache-disabled empty HEAD keeps origin representation headers. H1/H2/H3 live acceptance remains open.
5	Incomplete body / HEAD cache fill	SOURCE-FIXED	Dropped/error/trailer-incomplete fills are rejected and counted; a later complete fill can succeed.
6	Route cache tri-state	SOURCE-AUDITED	Option<bool> preserves inherit/true/false through model and UI; effective routing diagnostics are logged.
7	Parser-based JavaScript minifier	DEFERRED	0.21.0 keeps the conservative scanner; a parser-backed replacement is deferred rather than changing the resolved dependency graph during release closure.
8	Parser-based CSS minifier	DEFERRED	0.21.0 keeps the conservative scanner; a parser-backed replacement is deferred rather than changing the resolved dependency graph during release closure.
9	HTML minification	SOURCE-AUDITED	Optional/default-off conservative transform preserves whitespace and raw-text elements and removes only safe comments.
10	SVG optimization	SOURCE-AUDITED	Optional/default-off conservative comment cleanup preserves text/tspan whitespace and CDATA; it is not documented as a full optimizer.
11	JSON compacting	SOURCE-AUDITED	JSON is parsed and compact-serialized; malformed JSON fails open; transformed length/ETag/cache behavior is covered.
12	Formal transform pipeline	SOURCE-AUDITED	Proxy flow is origin -> decode -> transform -> canonical cache representation -> client encoding.
13	Content-Encoding	SOURCE-FIXED / RUNTIME OPEN	gzip/br/zstd decoding is implemented and transformed identity responses remove the Accept-Encoding Vary dimension only after canonicalization. Live all-codec acceptance remains open.
14	ETag / Last-Modified validators	SOURCE-FIXED	Origin validators are retained separately; client conditionals use the representation ETag; origin revalidation uses origin validators.
15	Cache-Control: no-transform	SOURCE-AUDITED	Origin policy is captured before response rules; final rules may add protection; cache storage remains allowed and origin representation/validators are retained.
16	stale-if-error	SOURCE-AUDITED	Separate metadata/window and fallback paths for origin errors/timeouts are present; revalidation flags block stale.
17	stale-while-revalidate	SOURCE-AUDITED	Immediate stale delivery, bounded background refresh and exact-variant single-flight are implemented.
18	must-revalidate	SOURCE-AUDITED	Storage remains allowed; stale serving through SWR/SIE/max-stale is blocked.
19	proxy-revalidate	SOURCE-AUDITED	Shared-cache stale behavior mirrors must-revalidate.
20	Cache metadata	SOURCE-AUDITED	TTL/stale windows/revalidation flags/origin validators persist in RAM and Cold Cache metadata.
21	Explicit cache object states	SOURCE-AUDITED	Fresh, StaleButServable, and Expired are explicit decisions rather than a single expiry comparison.
22	s-maxage precedence	SOURCE-AUDITED	Shared-cache parsing keeps s-maxage ahead of max-age and regression coverage exists.
23	immutable	SOURCE-FIXED	Duplicate/argument forms no longer invalidate Cache-Control; freshness is not extended and explicit client validation still works.
24	Cold Cache sharding	SOURCE-AUDITED	00..ff SHA-256 sharding, lazy directories, startup scan and no flat-cache migration are implemented.
25	Cold Cache GC	SOURCE-AUDITED	Async bounded GC uses configured interval, high/low watermarks and shared eviction accounting.
26	Cold read vs GC race	SOURCE-FIXED	Reads are pinned with entry generation; an old read guard cannot unpin a replacement using the same cache key.
27	Manual selective cleanup	SOURCE-AUDITED	Async cleanup reuses GC/eviction selection and reports removed objects/freed bytes.
28	Global transform settings	SOURCE-AUDITED	Global engine/type/extensions/body-limit settings exist.
29	Per-vhost transform opt-in	SOURCE-AUDITED	Per-vhost transform remains disabled by default even when the global engine is enabled.
30	Docker transform opt-in	SOURCE-AUDITED	Docker assignments have separate default-off transform configuration propagated to runtime vhosts.
31	Cache reasons	SOURCE-FIXED	fill_incomplete, transform_length_mismatch, transform_error and other bounded reasons are recorded.
32	Routing / transform diagnostics	SOURCE-FIXED	Access logs carry vhost, route, effective cache/transform state; the admin UI now has a dedicated Transform runtime dashboard, and transformed cache objects are marked in both Cache UI and Cache-Status.
33	Transform + cache integration	SOURCE-FIXED / RUNTIME OPEN	Source regression now exercises MISS -> transform -> store -> HIT for JS/CSS/HTML/SVG/JSON with ETag/length/body checks. Rust execution remains open.
34	Transform + compression	SOURCE-AUDITED / RUNTIME OPEN	Canonical identity cache representation and codec negotiation exist; live identity/gzip/br/zstd end-to-end acceptance remains open.
35	Vary	SOURCE-FIXED	Canonicalized identity drops only Accept-Encoding; custom Vary dimensions are retained and exact-variant SWR locking is preserved.
36	Query string	SOURCE-FIXED	?v=1, ?v=2 and ?F remain distinct cache keys; bypass_query is a request policy and transform does not rewrite the key.
37	Conditional requests	SOURCE-FIXED / RUNTIME OPEN	Representation ETag vs origin validator behavior is covered at source-test level; live integration remains open.
38	Restart	SOURCE-FIXED / RUNTIME OPEN	Cold restart regression preserves transformed ETag, origin validators, stale metadata and no-transform original representation.
39	Rust compiler quality gate	RUNTIME OPEN	cargo, rustc and rustfmt are unavailable here; fmt/check/test/clippy/release build cannot be claimed.
40	Remaining tests	PARTIAL	Source/package/SQLite/upgrade/JS/JSON/OpenAPI/shell and Docker-agent gates can run here; Rust-backed suites remain open.
41	Packaging	SOURCE-AUDITED / RUNTIME OPEN	0.21.0 source packaging is deterministic and the feature scope is closed; compiler/live release-host verification remains open.

Passive Backend Health addendum

The later Passive Backend Health specification is implemented as an opt-in policy:

• ordinary request failures remain observable when passive health is disabled;
• passive_health.enabled defaults to false for normal and Docker-generated vhosts;
• active TCP/HTTP health remains independent;
• connect/timeout/I/O/HTTP-5xx/slow-response classes have individual switches;
• passive fall/rise can override active thresholds;
• active and passive counters/state are separate;
• current unhealthy source/reason hands off correctly when one health domain recovers while the other remains unhealthy;
• Docker assignments persist and reapply the policy across discovery rebuilds;
• OpenAPI documents passive health for both Docker assignments and ordinary vhost load_balancing;
• Prometheus keeps unconditional observation counters and exposes passive-health aliases without making observation itself a health decision.

Deferred follow-up and release-host verification

• Parser-backed JavaScript and CSS minifiers are deferred to a later development cycle; 0.21.0 intentionally retains the conservative implementations and the existing resolved dependency graph.
• The release host must run the complete Rust 1.88+ gate: cargo fmt --check, cargo check --all-targets, cargo test --all-targets, cargo clippy --all-targets -- -D warnings, and cargo build --release.
• The compiled binary must pass the required live H1/H2/H3/cache/compression/restart acceptance tests before deployment.

The 0.21.0 source is feature-complete and packaged as release source; runtime acceptance remains explicitly external to this toolchain-less workspace.