v0.34.0_7

docs/PROXY_1KB_OPT5_DEV_0.34.0.md

@@ -0,0 +1,93 @@
+# RustProxy 0.34.0 DEV — OPT5, 1,040-byte reverse-proxy optimization
+
+## Acceptance boundary
+
+The source package preserves **0.34.0** and all existing configurable services,
+logs, dashboards, cache/ACL/auth policies, streaming, TLS/H2/H3/WebSocket,
+failover, retry and bounded-resource behavior. OPT5 is a **source-only** candidate:
+no Rust compiler is available in the editing environment. The new code's
+compilation, Rust unit tests, binary throughput and full-protocol interoperability
+are unverified until the developer builds it. The compiled OPT4 executable is
+the known test input, **not** a benchmark of OPT5.
+
+## Compiled OPT4 input verification
+
+Input: `/mnt/data/rust-proxy(4)`, SHA-256
+`1c4c701f11b57b1293020061c8af21d5a9df0c86f03290018a90edc007667b24`.
+
+- The real HTTP regression runner completed **151 passing**, **0 failing** cases;
+  **1 skipped** because Python `zstandard` is not installed. Protocol tests for
+  TLS/H2/H3 are a separate acceptance gate and were **not** passed by this run.
+- Same-host ApacheBench HTTP/1.1 keep-alive, 1,040-byte body verified by exact
+  SHA-256, cache OFF, 4 Tokio workers, 64 idle HTTP1 upstream connections,
+  3-second warm-and-measure samples, two repeats per variant/concurrency:
+
+| RPS, median of 2 samples | 16 clients | 64 clients |
+| --- | ---: | ---: |
+| OPT3 | 37,017 | 40,668 |
+| OPT4 | 39,054 | 36,425 |
+| nginx | 99,808 | 110,783 |
+| OPT4 vs OPT3 | +5.5% | -10.4% |
+| OPT4 / nginx | 39.1% | 32.9% |
+
+There were zero HTTP failures and the response body was verified before/after
+measurements. Shared CPU and only two short samples are diagnostic, NOT a stable
+speedup or production proof. The 100k RPS and 80%-of-nginx goals remain unmet.
+
+## OPT5 changes (8 coherent hot-path optimizations)
+
+1. `src/proxy/request_id.rs`: eliminate per-request SHA-256. Keep the existing
+   OS-seeded/reseeded thread-local CSPRNG and 256-bit ID; XOR a monotonic
+   sequence into the first 8 nonce bytes. Output remains uniformly random,
+   64 lowercase hex characters and the protected `X-Request-ID` correlation
+   remains. Random IDs continue to be unique with overwhelming probability.
+2. `src/forwarding.rs` and `src/proxy/forward_entry.rs`: only construct
+   `Context.original_url` for a frontend with configured Tinyauth. This is the
+   *only* runtime consumer of that absolute URL. Public `context(...)` still
+   constructs it by default. Trusted/untrusted forwarding and all validation
+   still execute identically; IPv4/IPv6 and `x-original-url` for Tinyauth remain.
+3. `src/balance/lease_runtime.rs`: borrow `"ok"` for successful backend health
+   observations instead of allocating a `String`. 5xx failures still record the
+   exact original `status=NNN` detail and slow/passive health counters are kept.
+4. `src/traffic.rs`: receive 64 samples at a time (Tokio `recv_many`) and apply
+   them under a single dashboard-state mutex. Order within the existing bounded
+   2,048-sample queue is preserved; waiting is outside the mutex and producer
+   backpressure and drop accounting are unchanged.
+5. `src/traffic.rs`: reuse map entries with borrowed vhost names. New keys are
+   cloned only when a domain first appears, preserving the max 64-vhost bound.
+6. `src/traffic.rs`: classify status 1xx–5xx using static labels; preserve
+   unknown extension status labels such as `7xx`.
+7. `src/traffic.rs`: replace per-sample lowercase allocation for User-Agent
+   family detection with ASCII-insensitive byte-window comparisons, and avoid
+   copying all TopTable maps when displaying a single vhost.
+8. `src/proxy/upstream_helpers.rs`: skip resolving inherited/vhost/web-service
+   compression settings when no encoding is accepted even under the global
+   codec ceiling (for example `Accept-Encoding: identity`). Existing compression
+   handling is retained for every accepted codec and request method.
+
+The caller's front-end policies remain evaluated on every request. No log,
+metric, access control or authentication feature was disabled or made optional.
+
+## Verification and outstanding gates
+
+Static source, SQL migration and managed-upgrade tests are executed and their
+outcomes supplied in the external evidence archive. New Rust test fixtures cover
+request IDs, forwarding/trusted IPv6, compression, healthy/5xx backend detail,
+analytics batching, top classes, country-independent User-Agent matching,
+reset and the bounded queue.
+
+To verify the new build on the developer's system:
+
+```bash
+./dev.sh check
+CARGO_INCREMENTAL=0 ./dev.sh test
+./dev.sh build
+```
+
+After building, repeat the actual HTTP regression, LB regression and TLS/H2/H3
+transport tests and collect at least seven 30-second CPU-isolated, warmed,
+interleaved OPT4/OPT5/nginx measurements with `wrk`, p95/p99 and CPU/RSS.
+Treat the non-tested binaries, short shared-host tests and simulated Python
+checks as distinct types of evidence. Measure the secondary Web Server path
+separately. Do not alter the version or silently relax cache, auth or timeout
+policies to reach a RPS target.