v0.26.0

docs/FILE_LOGS.md

@@ -0,0 +1,61 @@
+# Stored log explorer
+
+RustProxy 0.26.0 adds an authenticated, read-only **Logs** workspace at `/logs`. It is a local file-backed explorer for RustProxy logging outputs and is intentionally separate from **Live Logs**.
+
+## Separation from Live Logs
+
+Live Logs uses the bounded in-memory request history and Tokio broadcast channel. It remains available even when file logging is disabled and is optimized for current request activity.
+
+The stored-log explorer does not read that memory ring. It reads only files derived from the active RustProxy logging configuration:
+
+- the combined structured access-log path, or JSONL files directly inside the configured per-vhost directory;
+- the configured optional error-log file.
+
+Existing files remain browsable after their writer is disabled. Disabling file logging therefore stops new persistent access/protocol records but does not remove old files.
+
+## Protocol and malformed-traffic records
+
+Ordinary completed requests use `event: "request"`. RustProxy can also persist low-level records that fail before a normal routed HTTP exchange exists. Those records use:
+
+```json
+{
+  "event": "protocol_error",
+  "protocol_error": "tls_handshake_error",
+  "error_detail": "...",
+  "client_ip": "192.0.2.10",
+  "local_addr": "192.0.2.20:443",
+  "tls_sni": "app.example",
+  "transport": "tls",
+  "http_version": "",
+  "status": 0,
+  "outcome": "protocol_error"
+}
+```
+
+Covered classes include connection-limit rejection, malformed/incomplete HTTP/1 connections, invalid/disabled h2c upgrades, HTTP/2 protocol termination, TLS ClientHello and handshake errors/timeouts, and HTTP/3/QUIC handshake, header, protocol and stream-limit failures.
+
+These low-level records are sent only through the configured persistent structured-log sinks (file, Logstash and/or Loki). They are deliberately **not** inserted into Live Logs, so scanner noise cannot displace the ordinary bounded live request history. For `protocol_error` events, the diagnostic envelope fields shown above are always emitted even when a custom JSON field mapping is active; custom/static fields are retained, but they cannot hide or overwrite the required protocol-diagnostic fields.
+
+Dependency error text is secret-redacted and capped before it enters the persistent record. Raw packets, request bodies and raw malformed request bytes are not captured.
+
+## Browser security model
+
+The browser never supplies a filesystem path. `/api/file-logs` returns opaque source IDs derived from the current configuration, and `/api/file-logs/query` accepts only those IDs or `all`.
+
+The reader is bounded:
+
+- up to 2 MiB scanned from the tail of one source;
+- up to 8 MiB across one query;
+- up to 20,000 lines across the complete query, shared fairly across selected sources;
+- at most 32 sources in an `all` query;
+- page size at most 500 and offset at most 10,000.
+
+File reads run in a blocking worker rather than the async proxy runtime. Only regular files are accepted. On Unix the reader opens with `O_NOFOLLOW`; a symlink is not followed. Per-vhost enumeration also rejects a configured directory that is itself a symlink and only lists direct regular `.jsonl` children.
+
+The endpoints are private administration routes and inherit the existing panel session/Host/Origin access controls. There is no public-proxy route to the file reader.
+
+## Filters
+
+The workspace supports source, case-insensitive text, event class, HTTP status class, client IP and vhost filters. Results are paged from the bounded scanned tail. Selecting a row shows the complete parsed JSON object. RAW error-log lines are wrapped as a record with `event: "error"` and a `raw` field.
+
+The explorer is diagnostic rather than a retention system. RustProxy does not add rollover, indexing or compression; use the existing operating-system log rotation policy for retention.