v0.34.3

docs/CONFIGURATION.md

@@ -48,7 +48,7 @@ Read the dedicated guide before enabling advanced options: [Vhosts](VHOSTS.md),
 4. Set the source: HTTP reverse proxy or an existing Web Service. Test DNS, TLS and backend health.
 5. Add HTTP → HTTPS (`308`) or www/non-www redirection if needed. Check routing before turning on caching or restrictions.
 
-Listener bindings set by startup CLI/systemd cannot be removed, disabled or modified through saved configuration. Saved settings may therefore be valid but not active until a service restart. Administration and public frontends use different security boundaries.
+Listener bindings set by startup CLI/systemd cannot be removed, disabled or modified through saved configuration. Saved settings may therefore be valid but not active until a service restart. For H3, the `Alt-Svc` lifetime and reductions in runtime transport limits update for new requests/connections without restart; changed UDP binds, protocol toggles and H3 connection-capacity increases still need restart. See [HTTP transport](TRANSPORT.md). Administration and public frontends use different security boundaries.
 
 ## Backend protocols
 

docs/DASHBOARD.md

@@ -26,6 +26,10 @@ Unfinished editors may be minimized into a draft dock; this is a UI convenience
 
 ## Interpreting charts
 
+- The **Cache hit ratio** donut shows cumulative `HIT / (HIT + MISS)`: BYPASS and requests outside cache are deliberately excluded from its denominator.
+- The **Cache outcomes (recent)** compact horizontal 100% bar is **hidden by default**; enable it in **Settings → Appearance → Dashboard layout** or the Overview layout editor. It compares HIT, MISS, BYPASS and OTHER against all HTTP request counter increments in one contiguous sampling interval. BYPASS includes requests for which the cache path was considered but disabled/skipped (including globally disabled cache). OTHER means requests that generated no cache decision, e.g. early rejected or redirect paths. These are request counts, not response bytes. It shows no value until a second valid sample, after background-tab pauses, after counter resets, or when independently observed cache outcomes briefly exceed the requests delta. Revisit the next interval rather than trusting a forced 100% value.
+
+
 - Live views are process/sampling-based and can show no-data when an integration has not reported yet.
 - Per-backend protocol badges can distinguish configured HTTP mode from the protocol actually observed in connection traffic.
 - Response-header timing excludes the full streamed body duration. HTTP server/client percentages refer to the specified layer.

docs/README.md

@@ -1,6 +1,6 @@
 # RustProxy documentation
 
-Practical guides for **RustProxy 0.34.2**. 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.3**. 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
 
@@ -26,7 +26,7 @@ Practical guides for **RustProxy 0.34.2**. This index and the listed pages are a
 - [Certificates and automatic renewal](ACME_PROVIDERS.md) — PEM, HTTP-01, DNS-01, Certbot and external certificates.
 - [Docker discovery](DOCKER_DISCOVERY.md) — optional Linux agent DEB/RPM or manual installation, TLS/token CLI, networking and generated Vhosts.
 - [Other integrations](INTEGRATIONS.md) — Tinyauth, NPM migration, OPNsense and monitoring tools.
-- [Dashboard](DASHBOARD.md) — metrics panels, presets and configuration history.
+- [Dashboard](DASHBOARD.md) — metrics panels, HIT/MISS/BYPASS/OTHER request mix, presets and configuration history.
 - [Monitoring](MONITORING.md) — Prometheus, full JSON and compact `summary` API, traffic, backend and cache observations.
 - [Logs](LOGS.md) — live logs, stored logs, error logs and searches.
 - [Backups and recovery](BACKUP.md) — encrypted backups, restore and Secret Store.

docs/TRANSPORT.md

@@ -11,6 +11,37 @@ RustProxy distinguishes **frontend** client protocols from the **upstream** prot
 
 Transport settings attach to **named listeners**, and a Vhost must select the appropriate listener IDs. Addresses locked by CLI/systemd startup cannot be rewritten from the panel. Changing a listener bind or startup-owned TLS option may require a restart.
 
+### Saving HTTP/3 settings
+
+- **Immediately after a successful panel save:** H2/H1 TLS responses use the saved `alt_svc_max_age` (`Alt-Svc`), provided a matching UDP listener was actually bound at startup. Origin `Alt-Svc` never passes through. The value `0` publishes `ma=0`.
+- **Disabling H3 on a Vhost or an existing listener:** new H1/H2 responses publish `Alt-Svc: clear` to remove the browser's cached alternative service. A browser may keep an established QUIC connection until it closes; `clear` does not forcibly terminate it.
+- **For new QUIC connections only:** updates to `max_concurrent_bidistream`, `max_concurrent_unistream`, `max_idle_timeout` and reductions to `max_concurrent_connections` are applied without restart. Existing QUIC connections keep their negotiated limits. If no existing UDP socket matches the saved listener address, no H3 is advertised or accepted on the old address.
+- **Restart needed:** UDP listener enable/disable, changing IP/port/TLS properties, UDP socket buffer sizes, changes to H1/H2 listener settings and increasing `max_concurrent_connections` above the startup bound. The live listener status continues to show `restart_required` for these cases. After a restart, the new connection cap can take effect.
+
+
+### QUIC UDP socket buffers (0.34.3)
+
+The HTTP/3 settings of each TLS listener include:
+
+| Parameter | Default | Accepted values | Takes effect |
+|---|---:|---|---|
+| `udp_receive_buffer_bytes` | 4194304 (4 MiB) | `0` (OS default) or 65536–16777216 | On listener restart |
+| `udp_send_buffer_bytes` | 4194304 (4 MiB) | `0` (OS default) or 65536–16777216 | On listener restart |
+
+Use **Settings → HTTP/3** to edit these as whole MiB values (0–16); the JSON API stores bytes. No global `net.core.*_default` adjustment is necessary: RustProxy explicitly sets its own socket options. An OS limit may still clamp the request. Linux doubles `setsockopt(SO_RCVBUF / SO_SNDBUF)` values for bookkeeping; RustProxy targets the final effective size shown as `rb`/`tb` in `ss`.
+
+For a 4 MiB target on Debian/Linux, if the default `net.core.rmem_max` or `net.core.wmem_max` prevents reaching the target, set adequate socket *maxima* after reviewing host memory constraints, for example:
+
+```bash
+sudo sysctl -w net.core.rmem_max=8388608
+sudo sysctl -w net.core.wmem_max=8388608
+sudo systemctl restart rustproxy.service
+sudo ss -uapm | grep -A1 rust-proxy
+```
+
+Read the `HTTP/3 UDP effective socket buffers` startup log message. `ss` should show approximately `rb4194304,tb4194304` (or larger if the OS adjusts values) when the requested size is granted. Changes to the OS maxima alone do not resize an existing socket; the configured buffer size is applied when a QUIC listener starts. High default/maxima for every program are not recommended as a substitute for explicit per-socket configuration. No specific throughput gain is guaranteed; compare H2/H3 at matched traffic before/after.
+
+
 ## Backend protocol selection
 
 | Backend mode | HTTPS origin | Plain HTTP origin |

docs/TROUBLESHOOTING.md

@@ -9,6 +9,7 @@ Start with a reproducible request, its hostname/path and the exact listener. Com
 | Domain returns the wrong site or local 404 | DNS A/AAAA, selected listener ID, exact vs wildcard host precedence, Vhost enabled state, redirect/404 host ownership. |
 | HTTP works, HTTPS does not | Trusted certificate, hostname/SAN coverage, TLS listener, port 443 firewall, certificate assignment and whether restart was needed. |
 | HTTPS/H2 works but H3 fails | UDP firewall/NAT, H3 toggle on TLS listener, browser QUIC support and actual transport negotiation. |
+| H2 runs at link speed but H3 is slower | Compare the same origin and client with browser H3 vs H2, keeping TLS/cache/compression consistent. Inspect QUIC loss/cwnd/MTU and VM UDP offload, not only total CPU. |
 | `502` / `503` / `504` to origin | Backend IP/port, pool eligibility/health, private-address policy, upstream HTTPS verification, protocol `auto`/`h2`, timeout and container/PHP process availability. |
 | WebSocket handshake fails or disconnects | Vhost WebSockets flag, backend Upgrade support, TLS/frontend protocol path, WebSocket idle limits and auth redirect. |
 | `403` / `405` / `429` | Applicable IP/ACL/country policy, HTTP methods, rate limit, GeoIP availability, Basic/Tinyauth permissions. |
@@ -47,6 +48,27 @@ rust-proxy --data-dir /var/lib/rustproxy config validate config.json
 
 Use **Logs → Live Logs** or the `--livelogs` CLI mode to correlate request IDs, Vhost/route/backend and status. Inspect **Stored Logs** for previously saved JSONL and selected low-level protocol failures.
 
+## HTTP/3 throughput and CPU diagnostics (0.34.3 source candidate)
+
+Do not assume that low H3 throughput is a CPU bottleneck from the overall VM percentage alone. A 50% VM reading can mean one saturated vCPU on a 2-vCPU machine. Quinn uses UDP datagrams, per-packet QUIC/TLS, congestion control and OS/virtual NIC offloads; H1/H2 over TCP can behave differently under the same load. Quinn enables UDP GSO by default when the platform supports it, but some VM/network stacks fall back to per-datagram sends.
+
+1. Run **four matched tests** against the same OpenSpeedTest/large streaming endpoint: direct backend H1, proxied HTTPS H2, proxied HTTPS H3 download, proxied H3 upload. Record client speed, per-process CPU, **per-thread** CPU, and whether the problem persists with a larger number of simultaneous clients.
+2. On Linux, inspect the NIC and guest kernel counters before and after an H3 run (replace `eth0` with the actual VM interface):
+
+   ```bash
+   ip -s link show dev eth0
+   ethtool -k eth0 | grep -E 'generic-segmentation-offload|generic-receive-offload|udp-segmentation|rx-udp-gro-forwarding'
+   nstat -az | grep -E 'Udp(InErrors|RcvbufErrors|SndbufErrors)|Ip(InDiscards|OutDiscards)'
+   top -H -p "$(pidof rust-proxy)"
+   ```
+
+3. If available, use `perf top -p "$(pidof rust-proxy)"` briefly during the benchmark, and inspect `%sys` / `%soft` in `mpstat -P ALL 1`. Check whether guest CPU has `aes` instruction support with `lscpu`.
+4. For the 0.34.3 source candidate, set `RUST_LOG=rust_proxy::http3=debug` in a **test** deployment and inspect `HTTP/3 bulk transfer transport snapshot` logs: `quic_lost_packets`, `quic_congestion_events`, `quic_rtt_ms`, `quic_cwnd_bytes`, `quic_path_mtu`, `quic_udp_tx_datagrams` and `quic_udp_tx_ios`. Those Quinn counters are **connection-wide cumulative snapshots**, not stream-specific deltas; compare differences for one isolated connection or across successive samples.
+
+5. Run `ss -uapm | grep -A1 rust-proxy` during a transfer; check `skmem rb`, `tb` and whether dropped-datagram `d` increments. RustProxy 0.34.3 defaults to 4 MiB per direction and logs the actual SO_RCVBUF/SO_SNDBUF effective values on bind. If Linux clamps them, inspect `sysctl net.core.rmem_max net.core.wmem_max`; saving new socket buffer targets in the panel requires a listener restart. See [HTTP transport](TRANSPORT.md#quic-udp-socket-buffers-0343).
+
+A rising loss/retransmission count or shrinking congestion window with low CPU suggests packet pacing, network path, UDP buffer/offload or VM issues. With negligible loss and one saturated worker thread, investigate QUIC encryption, UDP send/receive and application streaming costs using `perf` before changing window sizes. HTTP/3 overhead can also affect large file transfers, uploads and long-lived H3 streams; speedtest is only one way to expose it. No throughput improvement is claimed without a production-equivalent QUIC benchmark.
+
 ## Rollout gate for RustProxy 0.34.0
 
 The latest source optimizations were **not all compiled or performance-tested** in the evidence supplied with this release. Before deploying: