feat: client log with request ids, joined to the server's

The browser now keeps its half of the one event shape logs.py defines: lib/log.ts is a levelled, redacted, bounded (2000 events) in-memory ring with the server's level names and severity numbers. Nothing leaves the browser yet; sending is the consented diagnostics level (S5). - lib/http.ts `send` is the one fetch: every request carries an X-Request-Id and becomes one http.request event. The server echoes the matched route template in X-Route (only for a matched route, so a raw path with a value in it is never sent back); without one the client templates the path itself. req, beacon, the upload XHR, the public watch page and the legal pages all go through it. - Hooks: app start snapshot, uncaught errors and rejections, History push/replace/popstate (a scroll-only replace is not an event; parameter values only at DEBUG, typed search only at TRACE), notifications, the error dialog, the crash boundary, failed queries and mutations (key head only), and the messages socket (lifecycle, frame types at DEBUG). - Redaction is one contract: backend/tests/fixtures/log_redaction_cases.json runs against both redact() implementations. - Lint: fetch, XMLHttpRequest and WebSocket each belong to one logging module, console to none; a contract test proves the rules fire. Fixes a socket takeover: the close of a socket released by the last subscriber cleared the newer socket a quick re-subscribe had opened and scheduled a third, leaving two live sockets that delivered every message twice (measured in Chromium: 3 created / 2 live before, 2 / 1 after).
2026-09-17 01:44:29 +02:00
parent 0517de1f59
commit a210992bfc
24 changed files with 1207 additions and 34 deletions
@@ -391,7 +391,7 @@ async def log_requests(request, call_next):
    What changes versus `uvicorn.access`: the ROUTE TEMPLATE instead of the concrete path (so
    `/api/videos/{video_id}` groups), never the query string (it carried `?account=`, and at TRACE
    the redacted query belongs in attrs, not in the URL), a request id echoed back in
-    `X-Request-Id`, the duration, and the account — read from `request.state`, which the auth
+    `X-Request-Id` (with the template in `X-Route`), the duration, and the account — read from `request.state`, which the auth
    dependency fills, because this middleware sits outside both the session middleware and the
    downstream task's context."""
    incoming = request.headers.get("x-request-id", "")
@@ -446,6 +446,13 @@ async def log_requests(request, call_next):
        },
    )
    response.headers["X-Request-Id"] = rid
+    # The template, so the browser's copy of this line groups the same way (frontend lib/http.ts).
+    # Only a MATCHED route's: a template never carries a path parameter's value (a share token stays
+    # `{token}`), while the raw-path fallback of an unmatched request could — the browser then
+    # templates the path itself.
+    matched = _matched_route(request)
+    if matched:
+        response.headers["X-Route"] = matched
    _request_id.reset(token)
    return response

@@ -471,8 +478,12 @@ def _request_owner(request, level: int) -> dict[str, Any]:
    return {} if _anonymous_lines.allow(client_key(request)) else {PERSIST: False}


+def _matched_route(request) -> str | None:
+    """The matched route's template (`/api/videos/{video_id}`), or None when nothing matched."""
+    return getattr(request.scope.get("route"), "path", None)
+
+
 def _route_template(request) -> str:
-    """The matched route's template (`/api/videos/{video_id}`), else the raw path for a 404 or a
-    static file. Never the query string."""
-    route = request.scope.get("route")
-    return getattr(route, "path", None) or request.url.path
+    """The matched route's template, else the raw path for a 404 or a static file. Never the query
+    string."""
+    return _matched_route(request) or request.url.path
@@ -0,0 +1,92 @@
+{
+  "_comment": "One redaction contract for both logs: backend/app/logs.py redact() and frontend/src/lib/log.ts redact() must turn every `value` (under `key`) into `expected`. Both test suites run this file (backend tests/test_logs.py, frontend src/lib/log.contract.test.ts), so the two implementations cannot drift apart. Some cases prove a secret goes; others prove ordinary content (a search term, a Plex title, a chat line) is not mangled — what a LEVEL may carry is decided at the call site, not here.",
+  "cases": [
+    {
+      "name": "a password field is dropped whole",
+      "key": "",
+      "value": {
+        "email": "a@b.co",
+        "password": "hunter2",
+        "current_password": "x"
+      },
+      "expected": {
+        "email": "[email]",
+        "password": "[redacted]",
+        "current_password": "[redacted]"
+      }
+    },
+    {
+      "name": "a token under any spelling of the key, nested and in lists",
+      "key": "",
+      "value": {
+        "plex": { "plex_server_token": "abc", "Authorization": "Bearer z" },
+        "items": [{ "access_token": "t1" }, { "id": 3 }]
+      },
+      "expected": {
+        "plex": {
+          "plex_server_token": "[redacted]",
+          "Authorization": "[redacted]"
+        },
+        "items": [{ "access_token": "[redacted]" }, { "id": 3 }]
+      }
+    },
+    {
+      "name": "E2EE material and cookies",
+      "key": "",
+      "value": {
+        "ciphertext": "AAAA",
+        "passphrase": "p",
+        "private_key": "k",
+        "cookies": "SID=1"
+      },
+      "expected": {
+        "ciphertext": "[redacted]",
+        "passphrase": "[redacted]",
+        "private_key": "[redacted]",
+        "cookies": "[redacted]"
+      }
+    },
+    {
+      "name": "a reset link and a verify fragment",
+      "key": "msg",
+      "value": "open https://app.example/#reset=QWErty123 or /?verify=abc&lang=hu",
+      "expected": "open https://app.example/#reset=[redacted] or /?verify=[redacted]&lang=hu"
+    },
+    {
+      "name": "an OAuth callback URL",
+      "key": "url",
+      "value": "/auth/callback?code=4/0Ab-xyz&state=s3cr3t&scope=email",
+      "expected": "/auth/callback?code=[redacted]&state=[redacted]&scope=email"
+    },
+    {
+      "name": "an email address inside a sentence",
+      "key": "message",
+      "value": "Invitation sent to Some.One+tag@mail.example.org.",
+      "expected": "Invitation sent to [email]."
+    },
+    {
+      "name": "a search term is kept (TRACE decides whether it is logged at all)",
+      "key": "q",
+      "value": "lo-fi beats to relax",
+      "expected": "lo-fi beats to relax"
+    },
+    {
+      "name": "a Plex title with an at-sign is not an address",
+      "key": "title",
+      "value": "Live @ Wembley 1986",
+      "expected": "Live @ Wembley 1986"
+    },
+    {
+      "name": "a chat line is text like any other; its only secret part is scrubbed",
+      "key": "body",
+      "value": "see you at 8, my mail is me@home.example",
+      "expected": "see you at 8, my mail is [email]"
+    },
+    {
+      "name": "non-text values pass through",
+      "key": "",
+      "value": { "status": 404, "ok": false, "ratio": 0.5, "none": null },
+      "expected": { "status": 404, "ok": false, "ratio": 0.5, "none": null }
+    }
+  ]
+}
@@ -11,6 +11,7 @@ Pure logic + an in-process ASGI app: no database.

 import json
 import logging
+from pathlib import Path

 import pytest
 from fastapi import FastAPI, Request
@@ -101,6 +102,18 @@ def test_an_email_in_an_attribute_value_is_scrubbed_too():
    assert logs.redact({"to": "a.b+tag@mail.example.org"})["to"] == logs.REDACTED_EMAIL


+# The SAME cases frontend/src/lib/log.redaction.test.ts runs against the browser's copy of redact():
+# the one thing that keeps the two logs' idea of "safe to keep" from drifting apart.
+_REDACTION_CASES = json.loads(
+    (Path(__file__).parent / "fixtures" / "log_redaction_cases.json").read_text(encoding="utf-8")
+)["cases"]
+
+
+@pytest.mark.parametrize("case", _REDACTION_CASES, ids=[c["name"] for c in _REDACTION_CASES])
+def test_the_shared_redaction_cases(case):
+    assert logs.redact(case["value"], key=case["key"]) == case["expected"]
+
+
 def test_redaction_runs_on_the_message_the_attrs_and_the_traceback(sink):
    log = logging.getLogger("siftlode.test")
    try:
@@ -263,6 +276,14 @@ def test_the_request_id_is_echoed_and_shared_by_every_line_of_that_request(sink)
    assert rid and sink.objects()[-1]["request_id"] == rid


+def test_the_route_template_goes_back_to_the_browser_but_never_a_raw_path(sink):
+    # The browser logs its own copy of each request, grouped by this template (frontend lib/http.ts).
+    client = _client()
+    assert client.get("/api/videos/SeCrEt-VaLuE").headers["X-Route"] == "/api/videos/{video_id}"
+    # Unmatched: the only template there is the raw path, which may carry a value — so none is sent.
+    assert "X-Route" not in client.get("/api/share/SeCrEt-VaLuE").headers
+
+
 def test_a_client_supplied_id_is_reused_only_when_it_is_well_formed(sink):
    client = _client()
    good = client.get("/api/videos/x", headers={"X-Request-Id": "web-0123456789ab"})