v0.31.0

docs/SETTINGS.md

@@ -12,9 +12,25 @@ The Settings page includes a local search field that filters category tabs using
 
 Unfinished Web Server, Vhost, Redirect and Stream forms use a session-only draft dock. Closing a dirty editor minimizes its exact browser state to the bottom-right dock so another editor can be opened independently. The dock follows the square-corner panel styling of the dashboard and intentionally avoids rounded/glass presentation. Drafts are intentionally not written to SQLite because form state can contain credentials or other secrets; they are discarded on logout/session reset.
 
+## Refresh preferences (0.31.0)
+
+**Settings -> Appearance -> Data refresh** saves an additional `refresh` object in the existing `admin_preferences` document for the signed-in account. It does not modify proxy configuration or create any migration. Older documents, including partially populated `refresh` objects, use defaults. Browser and server enforce exact allowed values:
+
+| Preference | Default | Allowed seconds |
+|---|---:|---|
+| `refresh.live_enabled` | `true` | `true`, `false` |
+| `refresh.overview_seconds` | 2 | 1, 2, 5, 10 |
+| `refresh.traffic_seconds` | 5 | 0, 3, 5, 10, 30 |
+| `refresh.cache_seconds` | 5 | 0, 3, 5, 10, 30 |
+| `refresh.system_info_seconds` | 60 | 0, 15, 30, 60, 300 |
+
+`live_enabled=false` disables automatic SSE **and all polling**, including system information. `0` disables only that source's automatic polling. Overview and System information have **Refresh now** buttons; Traffic and Cache retain their own buttons, filters, charts and pagination. The per-view Auto checkboxes for Traffic/Cache/Transform and the Docker live switch remain independent opt-outs, and none changes another administrator's preferences. **Reset section** restores refresh defaults without changing theme or unrelated preferences.
+
+The main `/api/events?interval=N` connection (allowlisted 1/2/5/10, default 2 seconds) carries compact live status plus the existing bounded log snapshot. The server checks the session on every event and retains its heartbeat, viewer cap and normal disconnect cleanup. On an SSE error the browser polls `/api/status?view=live` and `/api/logs` until snapshots resume, not concurrently during healthy streaming. The old full `/api/status` response is kept for API clients and initial diagnostics. The separate authenticated `/api/system-info` reuses cached diagnostics and ACME metadata, never runs diagnostic subprocesses per request, and is fetched automatically only for Overview or the relevant Settings pages. A hidden browser tab pauses the channel and all automatic polling; returning revalidates its session before normal operation. All interval changes take effect immediately, without reloading or changing any server-global cadence.
+
 ## System information (0.30.1)
 
-**Settings -> System information** (`/settings?tab=system-info`) is a read-only view of the authenticated `/api/status` endpoint. It reports the OS name/kernel on Linux when available, executable architecture, logical CPU count, CPU and RAM telemetry, host/process uptime, RustProxy version, process RSS, thread and file-descriptor counts, and the existing statistics source and data/database locations. Values not supported by the host/platform display as unavailable, never as zero.
+**Settings -> System information** (`/settings?tab=system-info`) is a read-only view of the authenticated `/api/system-info` endpoint (and the initial, backwards-compatible full `/api/status` response). It reports the OS name/kernel on Linux when available, executable architecture, logical CPU count, CPU and RAM telemetry, host/process uptime, RustProxy version, process RSS, thread and file-descriptor counts, and the existing statistics source and data/database locations. Values not supported by the host/platform display as unavailable, never as zero.
 
 ACME diagnostics formerly shown in About and under Administration are now on this tab: mode/state, certificate environment path, and the active Python/pip/Certbot versions. Versions are probed by the ACME runtime setup with bounded subprocess output/timeouts and published from stored runtime status. They are not queried at every page refresh or status API request. Failed/unavailable probes leave the version empty. No new persistent settings or permissions are introduced.
 
@@ -98,11 +114,34 @@ accepted only when `administration.tls` is true. Plain remote HTTP remains avail
     "tls": true,
     "certificate_id": "admin-example",
     "allowed_hosts": ["admin.example.com"],
-    "session_days": 30
+    "session_days": 30,
+    "panel_compression": {"zstd": true, "br": true, "gzip": true}
   }
 }
 ```
 
+**Administration → Panel content compression** (next to the admin listener/TLS settings)
+controls Zstd, Brotli and gzip for the authenticated HTML document, JavaScript,
+CSS and language bundles. Each browser request is negotiated using
+`Accept-Encoding` quality values: the highest positive `q` wins, and ties
+prefer **Zstd → Brotli → gzip**. Codecs can be enabled independently; the
+identity representation is returned when none is acceptable or all are off.
+The source is encoded only once per embedded asset and shared across visitors.
+Settings persist in the existing revisioned administration document, without
+additional CLI flags or a separate environment/config variable, and take effect
+without restart. Each compressed response includes `Content-Encoding`,
+`Vary: Accept-Encoding` and the representation-specific `Content-Length`.
+The response compression of proxied websites remains independent; API responses,
+SSE and WebSocket streams are not affected.
+
+**Reverse proxy:** an upstream may remove or replace `Accept-Encoding`. RustProxy
+negotiates from the header it actually receives, not the original browser request.
+A reverse proxy normally passes through already encoded responses instead of
+recompressing them; if the reverse should exclusively manage encoding, configure
+it to strip `Accept-Encoding` on requests upstream, or turn the panel codecs off.
+This provides compatible HTTP negotiation but does not guarantee identical
+compression with every reverse proxy configuration.
+
 `certificate_id: null` uses `data/certs/default.pem` and `default.key`, generated by
 the application. A selected inventory certificate is loaded from the same private
 certificate directory. `session_days` controls the absolute browser-session lifetime
@@ -169,8 +208,13 @@ Version 0.22 adds foreground fill collapsing (`collapse_enabled`,
 (`proactive_refresh_enabled`, `proactive_refresh_before_expiry_seconds`,
 `proactive_refresh_percent`, `proactive_refresh_max_inflight`). Defaults preserve the
 previous stale-if-error behavior; proactive refresh is disabled by default. Selective
-PURGE/BAN is an operational API/panel action rather than persisted configuration. See
+PURGE/BAN is available in the authenticated API/panel, and HTTP BAN/PURGE has an optional, separately stored CIDR allowlist (`cache.http_invalidation_allowed_cidrs`, empty by default). See
 [CACHE.md](CACHE.md) for request-collapse, Range and invalidation semantics.
+The adjacent **info (`i`) popover** in Settings → Cache shows ready-to-copy
+`curl -X PURGE` and `curl -X BAN` examples in English and Polish, including
+the explicit `BAN /` confirmation. These public methods authorize by the
+source IP/CIDR only; they do not accept a browser admin session as a bypass.
+See [0.31.0 security audit](SECURITY_AUDIT_0.31.0.md) for reverse-proxy trust and tests.
 
 ## Static-response transformation