Surface replay block decode and fetch failures via a frontend diagnostic store

Akarithos · Akarithos · commit 57bc5c8a505d · 2026-05-19T00:33:31.000-07:00
The notification bell only carried backend diagnostics. Replay block decode
failures and HTTP failures of the block loader were visible only in the
browser console — operators saw the result (no replay) but had no notification
explaining why. Adds a frontend-side store that mirrors the backend's
(channel, code, scope) identity model and merges into the existing
notification panel:

- frontend.replay.block_decode_failed when fzstd or JSON.parse rejects a
  block body (singleton entry rolling its message forward across blocks).
- frontend.replay.block_load_failed when the fetch itself fails or returns
  non-2xx.

Wiring lives in loadReplayBlock; the existing error throw path is unchanged
so callers still surface the per-load error on the timeline. Frontend codes
use the `frontend.*` channel namespace so identity collisions with backend
codes are impossible — straight concat-then-sort merge with the existing
backend snapshot.

Store details: TTL-refreshed-by-re-emission (default 30s), defensive cap of
50 entries, monotonic tie-break for same-millisecond emits, lazy expiry on
read. Reactive snapshot via a memoized hook so StatusBar's render path adds
no work between mutations.

Also nudges the README Caddy example to set Content-Type: application/json
on the zstd path (per RFC, Content-Type describes the resource after
decoding); the octet-stream fallback still applies when the client lacks
zstd Accept-Encoding.
diff --git a/README.md b/README.md
@@ -372,6 +372,7 @@ directory behind the reverse proxy and let the proxy serve finalized
 handle_path /api/replay/blocks/* {
 	root * /var/lib/ident/replay/blocks
 	header Content-Type application/octet-stream
+	header @accepts_zstd Content-Type application/json
 	header @accepts_zstd Content-Encoding zstd
 	header Cache-Control "public, max-age=31536000, immutable"
 	file_server
diff --git a/ident/src/data/frontendDiagnostics.test.ts b/ident/src/data/frontendDiagnostics.test.ts
@@ -0,0 +1,224 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  __resetFrontendDiagnosticsForTest,
+  clearFrontendDiagnostic,
+  DEFAULT_FRONTEND_DIAGNOSTIC_TTL_MS,
+  emitFrontendDiagnostic,
+  FRONTEND_DIAGNOSTIC_CAP,
+  snapshotFrontendDiagnostics,
+} from "./frontendDiagnostics";
+
+afterEach(() => {
+  __resetFrontendDiagnosticsForTest();
+});
+
+describe("frontendDiagnostics", () => {
+  it("emit + snapshot returns the entry with seenAtEpochMs set", () => {
+    const before = Date.now();
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.replay",
+      code: "replay.block_decode_failed",
+      message: "Could not decode block /api/replay/blocks/1-2.json.zst",
+    });
+    const after = Date.now();
+
+    const snap = snapshotFrontendDiagnostics();
+    expect(snap).toHaveLength(1);
+    const [entry] = snap;
+    expect(entry).toMatchObject({
+      severity: "warning",
+      channel: "frontend.replay",
+      code: "replay.block_decode_failed",
+      message: "Could not decode block /api/replay/blocks/1-2.json.zst",
+    });
+    expect(entry.seenAtEpochMs).toBeGreaterThanOrEqual(before);
+    expect(entry.seenAtEpochMs).toBeLessThanOrEqual(after);
+  });
+
+  it("re-emitting the same identity replaces mutable fields and refreshes seenAt", () => {
+    emitFrontendDiagnostic({
+      severity: "info",
+      channel: "frontend.network",
+      code: "network.websocket_dropped",
+      message: "first",
+    });
+    const firstSeen = snapshotFrontendDiagnostics()[0].seenAtEpochMs;
+
+    // Tiny delay so seenAt can move forward measurably.
+    const later = firstSeen + 5;
+    emitFrontendDiagnostic({
+      severity: "error",
+      channel: "frontend.network",
+      code: "network.websocket_dropped",
+      message: "second",
+    });
+
+    const snap = snapshotFrontendDiagnostics(later);
+    expect(snap).toHaveLength(1);
+    expect(snap[0].severity).toBe("error");
+    expect(snap[0].message).toBe("second");
+    expect(snap[0].seenAtEpochMs).toBeGreaterThanOrEqual(firstSeen);
+  });
+
+  it("treats different scopes as distinct identities", () => {
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.replay",
+      code: "replay.block_decode_failed",
+      scope: "block-a",
+      message: "a",
+    });
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.replay",
+      code: "replay.block_decode_failed",
+      scope: "block-b",
+      message: "b",
+    });
+
+    const snap = snapshotFrontendDiagnostics();
+    expect(snap).toHaveLength(2);
+    expect(snap.map((d) => d.scope).sort()).toEqual(["block-a", "block-b"]);
+  });
+
+  it("snapshot omits entries whose TTL has elapsed", () => {
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.replay",
+      code: "code.a",
+      message: "stale",
+      ttlMs: 1000,
+    });
+
+    const seenAt = snapshotFrontendDiagnostics()[0].seenAtEpochMs;
+    const expired = snapshotFrontendDiagnostics(seenAt + 1001);
+    expect(expired).toHaveLength(0);
+  });
+
+  it("snapshot still returns entries before TTL elapses", () => {
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.replay",
+      code: "code.a",
+      message: "fresh",
+      ttlMs: 1000,
+    });
+    const seenAt = snapshotFrontendDiagnostics()[0].seenAtEpochMs;
+    expect(snapshotFrontendDiagnostics(seenAt + 999)).toHaveLength(1);
+  });
+
+  it("defaults ttlMs to DEFAULT_FRONTEND_DIAGNOSTIC_TTL_MS when omitted", () => {
+    emitFrontendDiagnostic({
+      severity: "info",
+      channel: "frontend.x",
+      code: "code.a",
+      message: "m",
+    });
+    const seenAt = snapshotFrontendDiagnostics()[0].seenAtEpochMs;
+    // Just under the default cap → still present.
+    expect(
+      snapshotFrontendDiagnostics(
+        seenAt + DEFAULT_FRONTEND_DIAGNOSTIC_TTL_MS - 1,
+      ),
+    ).toHaveLength(1);
+    // Just over → expired.
+    expect(
+      snapshotFrontendDiagnostics(
+        seenAt + DEFAULT_FRONTEND_DIAGNOSTIC_TTL_MS + 1,
+      ),
+    ).toHaveLength(0);
+  });
+
+  it("clear removes an entry by identity", () => {
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.x",
+      code: "code.a",
+      message: "m",
+    });
+    clearFrontendDiagnostic("frontend.x", "code.a");
+    expect(snapshotFrontendDiagnostics()).toHaveLength(0);
+  });
+
+  it("clear is a no-op when nothing matches the identity", () => {
+    expect(() =>
+      clearFrontendDiagnostic("frontend.nope", "code.absent"),
+    ).not.toThrow();
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.x",
+      code: "code.a",
+      message: "m",
+    });
+    clearFrontendDiagnostic("frontend.x", "code.a", "wrong-scope");
+    expect(snapshotFrontendDiagnostics()).toHaveLength(1);
+  });
+
+  it("clear respects scope (matches only the identity with that scope)", () => {
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.x",
+      code: "code.a",
+      scope: "s1",
+      message: "m1",
+    });
+    emitFrontendDiagnostic({
+      severity: "warning",
+      channel: "frontend.x",
+      code: "code.a",
+      scope: "s2",
+      message: "m2",
+    });
+    clearFrontendDiagnostic("frontend.x", "code.a", "s1");
+    const snap = snapshotFrontendDiagnostics();
+    expect(snap).toHaveLength(1);
+    expect(snap[0].scope).toBe("s2");
+  });
+
+  it("evicts the oldest entry when exceeding FRONTEND_DIAGNOSTIC_CAP", () => {
+    // Emit one over the cap; the very first entry must be gone.
+    for (let i = 0; i <= FRONTEND_DIAGNOSTIC_CAP; i++) {
+      emitFrontendDiagnostic({
+        severity: "info",
+        channel: "frontend.x",
+        code: `code.${i}`,
+        message: String(i),
+      });
+    }
+    const snap = snapshotFrontendDiagnostics();
+    expect(snap).toHaveLength(FRONTEND_DIAGNOSTIC_CAP);
+    const codes = new Set(snap.map((d) => d.code));
+    expect(codes.has("code.0")).toBe(false);
+    expect(codes.has(`code.${FRONTEND_DIAGNOSTIC_CAP}`)).toBe(true);
+  });
+
+  it("snapshot returns entries sorted newest-first by seenAtEpochMs", () => {
+    emitFrontendDiagnostic({
+      severity: "info",
+      channel: "frontend.x",
+      code: "code.first",
+      message: "first",
+    });
+    const firstSeen = snapshotFrontendDiagnostics()[0].seenAtEpochMs;
+    emitFrontendDiagnostic({
+      severity: "info",
+      channel: "frontend.x",
+      code: "code.second",
+      message: "second",
+    });
+    const snap = snapshotFrontendDiagnostics(firstSeen + 10);
+    expect(snap.map((d) => d.code)).toEqual(["code.second", "code.first"]);
+  });
+
+  it("omits scope from the snapshot when not provided", () => {
+    emitFrontendDiagnostic({
+      severity: "info",
+      channel: "frontend.x",
+      code: "code.a",
+      message: "m",
+    });
+    const [entry] = snapshotFrontendDiagnostics();
+    expect(entry.scope).toBeUndefined();
+  });
+});
diff --git a/ident/src/data/frontendDiagnostics.ts b/ident/src/data/frontendDiagnostics.ts
diff --git a/ident/src/data/replay.test.ts b/ident/src/data/replay.test.ts
@@ -1,4 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetFrontendDiagnosticsForTest,
+  snapshotFrontendDiagnostics,
+} from "./frontendDiagnostics";
 import {
   blocksForRange,
   ensureReplayRange,
@@ -49,13 +53,15 @@ function resetStore() {
 describe("replay data loading", () => {
   beforeEach(() => {
     resetStore();
+    __resetFrontendDiagnosticsForTest();
     window.history.replaceState(null, "", "/ident/#/");
   });
 
   afterEach(() => {
     globalThis.fetch = originalFetch;
     vi.restoreAllMocks();
     window.history.replaceState(null, "", "/");
+    __resetFrontendDiagnosticsForTest();
   });
 
   it("loads the manifest from the mounted app path", async () => {
@@ -611,6 +617,49 @@ describe("replay data loading", () => {
       ],
     ).toBeTruthy();
   });
+
+  it("surfaces a frontend diagnostic when a replay block fails to decode", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    globalThis.fetch = vi.fn(async (url: string) =>
+      url.includes("manifest")
+        ? responseJson(manifest())
+        : responseJson({ version: 2, frames: null }),
+    ) as never;
+
+    await refreshReplayManifest();
+    await ensureReplayRange(120_000, 180_000, { background: true });
+
+    const snap = snapshotFrontendDiagnostics();
+    const decodeDiag = snap.find(
+      (d) => d.code === "replay.block_decode_failed",
+    );
+    expect(decodeDiag).toBeDefined();
+    expect(decodeDiag?.channel).toBe("frontend.replay");
+    expect(decodeDiag?.severity).toBe("warning");
+    expect(decodeDiag?.message).toContain(
+      "/api/replay/blocks/120000-180000.json.zst",
+    );
+  });
+
+  it("surfaces a frontend diagnostic when a replay block fetch fails", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    globalThis.fetch = vi.fn(async (url: string) => {
+      if (url.includes("manifest")) return responseJson(manifest());
+      return { ok: false, status: 502, json: async () => null } as Response;
+    }) as never;
+
+    await refreshReplayManifest();
+    await ensureReplayRange(120_000, 180_000, { background: true });
+
+    const snap = snapshotFrontendDiagnostics();
+    const loadDiag = snap.find((d) => d.code === "replay.block_load_failed");
+    expect(loadDiag).toBeDefined();
+    expect(loadDiag?.channel).toBe("frontend.replay");
+    expect(loadDiag?.severity).toBe("warning");
+    expect(loadDiag?.message).toContain(
+      "/api/replay/blocks/120000-180000.json.zst",
+    );
+  });
 });
 
 function manifest() {
diff --git a/ident/src/data/replay.ts b/ident/src/data/replay.ts
@@ -1,4 +1,5 @@
 import { appPath } from "./basePath";
+import { emitFrontendDiagnostic } from "./frontendDiagnostics";
 import {
   decodeReplayBlockResponse,
   ReplayBlockBodyError,
@@ -204,15 +205,33 @@ function loadReplayBlock(block: ReplayBlockIndex): Promise<void> | null {
       }
       useIdentStore.getState().setReplayBlock(block.url, body);
     } catch (err) {
-      if (
-        err instanceof ReplayLoadCanceled ||
-        err instanceof ReplayBlockFormatError
-      ) {
+      if (err instanceof ReplayLoadCanceled) {
+        throw err;
+      }
+      if (err instanceof ReplayBlockFormatError) {
+        emitFrontendDiagnostic({
+          severity: "warning",
+          channel: "frontend.replay",
+          code: "replay.block_decode_failed",
+          message: `Could not decode replay block ${block.url}`,
+        });
         throw err;
       }
       if (err instanceof ReplayBlockBodyError) {
+        emitFrontendDiagnostic({
+          severity: "warning",
+          channel: "frontend.replay",
+          code: "replay.block_decode_failed",
+          message: `Could not decode replay block ${block.url}`,
+        });
         throw new ReplayBlockFormatError(block.url);
       }
+      emitFrontendDiagnostic({
+        severity: "warning",
+        channel: "frontend.replay",
+        code: "replay.block_load_failed",
+        message: `Could not load replay block ${block.url}`,
+      });
       throw new ReplayBlockLoadError(block.url, err);
     } finally {
       if (blockLoads.get(block.url)?.promise === load) {
diff --git a/ident/src/statusbar/StatusBar.tsx b/ident/src/statusbar/StatusBar.tsx
@@ -3,10 +3,12 @@ import {
   type CSSProperties,
   type KeyboardEvent,
   useEffect,
+  useMemo,
   useRef,
   useState,
 } from "react";
 import { match, P } from "ts-pattern";
+import { useFrontendDiagnosticsSnapshot } from "../data/frontendDiagnostics";
 import {
   diagnosticIdentity,
   type NotificationSuppression,
@@ -124,7 +126,18 @@ export interface ReceiverDiagnostics {
 export function useReceiverDiagnostics(): ReceiverDiagnostics {
   const identStatus = useIdentStore((s) => s.identStatus);
   const capabilities = useIdentStore((s) => s.capabilities?.capabilities);
-  const diagnostics = useIdentStore((s) => s.diagnostics);
+  const backendDiagnostics = useIdentStore((s) => s.diagnostics);
+  const frontendDiagnostics = useFrontendDiagnosticsSnapshot();
+  // Merge backend + frontend diagnostics into one list sorted newest-first.
+  // Frontend codes live under a `frontend.*` channel namespace so identity
+  // collisions with backend codes are impossible — straight concat is safe.
+  const diagnostics = useMemo(
+    () =>
+      [...backendDiagnostics, ...frontendDiagnostics].sort(
+        (a, b) => b.seenAtEpochMs - a.seenAtEpochMs,
+      ),
+    [backendDiagnostics, frontendDiagnostics],
+  );
 
   const normalizedGain = presentStatusValue(identStatus?.gain)?.db ?? null;
   const gainLabel =
