v0.34.0_4

docs/PROXY_1KB_COUNTERS_DEV_0.34.0.md

@@ -130,3 +130,18 @@ backend connects and all log/traffic drop counters. Test concurrent global
 purges and per-vhost purges during traffic and verify the stats reset behavior
 and cache HIT/MISS/BYPASS/reason distribution. Run long soaks and both cold/HOT
 cache tests. The 100k RPS / nginx 80% goal is still **OPEN**.
+
+## Build fix after first compiler feedback (OPT2-FIX1)
+
+The first user build of OPT2 failed with six Rust `E0753` diagnostics because
+`src/cache/stats.rs` starts with `//!` *inner module* documentation but is
+injected via `include!("stats.rs")` after other items in `src/cache/mod.rs`.
+The six documentation lines are now ordinary `//` comments; there is no
+behavior change. Three unnecessary `mut` bindings in
+`src/cache/dashboard.rs` were also removed (warnings only). Version remains
+0.34.0; no performance or feature semantics have changed in this fix.
+
+The compiler-enabled host should rerun `./dev.sh check`,
+`CARGO_INCREMENTAL=0 ./dev.sh test` and an optimized release build, then
+performance benchmarks. This editing environment still lacks `cargo` and
+`rustc`, so the fix has been statically checked, **not compiled** here.

docs/PROXY_1KB_OPT3_DEV_0.34.0.md

@@ -0,0 +1,88 @@
+# RustProxy 0.34.0 DEV — 1,040-byte response, OPT3
+
+## Scope
+
+Primary: uncached reverse proxy, HTTP/1.1 keep-alive, 1,040-byte body,
+no compression, ACL/security/logging/analytics/counters fully operational.
+Goal: ~100,000 RPS and >=80% of nginx on the **same isolated host**.
+Secondary: local Web Server/static files, measured independently.
+**Version remains exactly 0.34.0**; existing configuration and defaults are
+unchanged; no functions, checks or logs are disabled.
+
+## New code optimizations (relative to OPT2-FIX1)
+
+1. `src/acl.rs` / `src/proxy/cache_helpers.rs`: borrow ordinary validated
+   routing paths using `Cow<str>` during immutable route selection. Calls
+   with escaped (`%xx`) or repeated separators still use the original strict
+   allocator/decoder. Invalid control bytes, dot segments, UTF-8 and ambiguous
+   encodings remain rejected; the original wire path is not rewritten.
+2. `src/proxy/forward_entry.rs` plus cache/Web Service call sites: retain the
+   original `http::Uri` value so normal paths can remain borrowed during the
+   entire mutable forwarding/rewrite operation. Cache-refresh tasks that need
+   ownership still allocate explicitly and hold their own `String`.
+3. `src/forwarding.rs`: a **direct, untrusted** TCP peer now obtains the same
+   seven forwarding headers without allocating hop-chain `Vec` structures.
+   Trust chains and the configured `trust_forwarded_proto` logic use the
+   unchanged full parser. IPv4/IPv6 RFC 7239 formatting and true listener
+   port/scheme are preserved; untrusted spoofed values are still ignored.
+4. `src/proxy/forward_entry.rs`: when effective client IP is identical to
+   the transport peer, reuse the IP stored by observation. No redundant
+   `IpAddr::to_string()` and no per-exchange mutex write. Different/trusted or
+   IPv4-mapped addresses are still stored in canonical form.
+5. `src/proxy/headers.rs`: plain single-valued `Connection: keep-alive`
+   avoids the temporary `Vec<HeaderName>` while all standard hop-by-hop fields
+   are removed; comma-separated, repeated and complex Connection fields keep
+   the original removal parser to prevent nominated-header leaks.
+6. `src/proxy/request_id.rs`: preserve SHA-256, CSPRNG, per-process sequence,
+   unpredictable 64-char hexadecimal IDs and wire headers, but write the hex
+   digits into one preallocated byte buffer before UTF-8 verification.
+7. `src/cache/stats.rs`: select the most frequent `cache_disabled` reason
+   counter directly. The same exact atomic totals, reason labels, 4096-domain
+   limit and reset behavior are retained.
+
+The changes avoid repeated work in common cases; no numerical throughput
+benefit has been measured for this new source. In particular, no cache, log,
+metrics, retry or auth feature was switched off for a synthetic benchmark.
+
+## Evidence and known limits
+
+- Provided newly compiled *OPT2-FIX1* executable SHA-256:
+  `6037e98d059672b716f2e1411976bf305cac927901a6f6662d8b703829ff8196`.
+- PASS **89** HTTP proxy/policy/cache black-box assertions, zero failures,
+  testing that supplied executable, **not** the new OPT3 code.
+- Source checks, migration/upgrade checks and ZIP checks are separate
+  static/offline verification; they are not equivalent to cargo/test/live.
+- A single interrupted diagnostic A/B sample at c=64, 3 s, same idle=64,
+  gave older binary 33,752 RPS and OPT2-FIX1 binary 33,556 RPS, zero failed
+  requests; do **not** infer a true performance difference from one sample.
+- NOT RUN here: `cargo check`, `cargo test`, rebuilt OPT3 integration tests,
+  post-build A/B RPS, long soaking, real TLS/H2/H3 compatibility and 80%-of-nginx
+  acceptance. No Rust toolchain is available in this editing container.
+- Resource/latency trade-offs (including log/analytics drops, RSS/FDs) require
+  the same measured and pinned server/peer/generator CPU sets for before/after.
+
+## Rebuild and measure
+
+From the unpacked `RustProxy/` directory:
+
+```bash
+./dev.sh check
+CARGO_INCREMENTAL=0 ./dev.sh test
+bash dev.sh
+python3 scripts/performance/regression.py \
+  --binary new=/ABSOLUTE/PATH/NEW/rust-proxy --out /tmp/rustproxy-opt3-http
+python3 scripts/performance/ab_1kb_dev.py \
+  --binary before=/ABSOLUTE/PATH/OPT2FIX1/rust-proxy \
+  --binary after=/ABSOLUTE/PATH/OPT3/rust-proxy \
+  --nginx /usr/sbin/nginx --ab /usr/bin/ab \
+  --out /tmp/rustproxy-opt3-1kb --concurrency 16,64 \
+  --duration 5 --repeats 3 --workers 4 --max-idle 64
+```
+
+For an acceptance-grade evaluation, run the `scripts/performance/benchmark.py`
+paired before/after/nginx test with separate pinned CPU sets, a verified origin
+and 30-second runs repeated 7 times. Report median and p95/p99 latency,
+errors, CPU, RSS, file descriptors, dropped log/analytics events, and all HTTP
+status/body hashes. Retest TLS/H2/H3/WebSocket, auth, cache semantics and
+connection/backpressure limits. Compare the **rebuilt** OPT3 binary against
+OPT2-FIX1 at exactly the same listener/backend settings and compiler profile.