feat(admin): SPA degraded banner + conflict hatching for fan-out (Phase 2-C PR-2) (#687)

bootjp · web-flow · commit edaaa64e6154 · 2026-04-27T22:46:18.000+09:00
## Summary Phase 2-C **PR-2**, per the design doc landed in #685 §6: wire the fan-out `Fanout` / `conflict` shapes shipped by PR #686 into the admin SPA so operators can see when a peer failed and which rows are soft due to a leadership flip. Backend is unchanged. PR #686's `KeyVizMatrix.Fanout` block is currently emitted on every fan-out request but the SPA was discarding it. ## What this PR adds | Piece | Behavior | |---|---| | **Header counter** | `cluster view (N of M nodes)` in the per-matrix metadata strip. Hidden when `fanout` is absent (single-node mode, no behavior change). | | **FanoutBanner** | Degraded-mode card above the heatmap when `responded < expected`. Lists every failed node + error string. Hidden when the cluster is healthy. | | **ConflictOverlay** | SVG hatch over rows whose `conflict === true`. Layered inside the scroll container so the hatch tracks horizontal scroll (same idiom as `TimeAxis`). 4 px diagonal stripes, alpha 0.45, inheriting `currentColor` so it works against both light and dark themes. | | **RowDetail pill** | Hovering a conflicting row reveals a `conflict` pill with a hover-tooltip explaining the leadership-flip semantics. | ## Five-lens self-review 1. **Data loss** — n/a; SPA-only change reading existing fields. 2. **Concurrency / distributed** — n/a; single browser tab consuming an existing API. 3. **Performance** — Banner: zero-cost when healthy (`null` returned). Hatch: SVG with at most 1024 `<rect>` elements (matches `KeyVizRow` budget); empirically negligible. Overlay only renders when at least one row has `conflict === true`. 4. **Data consistency** — UI surfaces existing server signals; semantics come from PR #685 design §4.2 and #686 implementation. Not relitigated here. 5. **Test coverage** — `tsc -b --noEmit` and `vite build` clean. UI behavior (banner visibility, hatch presence, header text) is hard to assert in `tsc` alone; manual verification documented below. ## Test plan - [x] `npm run lint` (`tsc -b --noEmit`) — clean - [x] `npm run build` (Vite) — clean, output writes to `internal/admin/dist` - [ ] Manual: `make run` with `--keyvizEnabled --keyvizFanoutNodes=127.0.0.1:8080`. Open `/keyviz`; header reads `cluster view (1 of 1 nodes)`, no banner, no hatch. - [ ] Manual: configure `--keyvizFanoutNodes=127.0.0.1:8080,127.0.0.1:9999` (port 9999 unused). Header reads `1 of 2 nodes`, the failed-node banner appears with `connection refused` for `127.0.0.1:9999`. - [ ] Manual: smoke a leadership flip mid-window (or fake `conflict=true` server-side via `/admin/api/v1/keyviz/matrix?...`); the affected row renders with diagonal hatch overlay; hovering reveals the `conflict` pill. ## Out of scope - **Per-cell hatching** — Phase 2-C+ once the proto extension lands and `conflict` becomes per-cell instead of per-row. - **Per-node `generated_at` skew indicator** — design §9 Q3, deferred. - **Banner auto-dismiss / sound notification** — out of scope; an operator who has the page open will see the banner. CI alert pages are a separate system. Closes the SPA half of Phase 2-C; the proto extension follows in PR-3.  ## Summary by CodeRabbit * **New Features** * KeyViz now displays cluster fan-out status with node availability and responsiveness counts. * Added visual indicators for rows experiencing conflicts during leadership transitions. * Row details now include conflict status labels with informative tooltips.
diff --git a/web/admin/src/api/client.ts b/web/admin/src/api/client.ts
@@ -231,13 +231,41 @@ export interface KeyVizRow {
   route_ids_truncated?: boolean;
   route_count: number;
   values: number[];
+  // Phase 2-C row-level conflict flag (always present on the wire,
+  // defaults to false). True when ≥2 nodes reported a non-zero
+  // value for the same cell — typically a leadership flip mid-
+  // window. Per design 4.2 / PR-1, this is a row-level signal; it
+  // moves to per-cell when the proto extension lands in 2-C+.
+  conflict?: boolean;
+}
+
+// Per-node entry in the KeyVizMatrix.fanout block. OK=true means
+// the node returned a parseable matrix; OK=false carries the
+// reason (timeout, refused, 5xx body, JSON decode failure). Self
+// always reports ok=true since the local matrix is computed in-
+// process.
+export interface KeyVizFanoutNode {
+  node: string;
+  ok: boolean;
+  error?: string;
+}
+
+// Per-response fan-out summary attached to KeyVizMatrix.fanout
+// when the operator configured --keyvizFanoutNodes. Absent when
+// fan-out is disabled. nodes is ordered self-first, then in
+// --keyvizFanoutNodes order. Responded counts ok=true entries.
+export interface KeyVizFanoutResult {
+  nodes: KeyVizFanoutNode[];
+  responded: number;
+  expected: number;
 }
 
 export interface KeyVizMatrix {
   column_unix_ms: number[];
   rows: KeyVizRow[];
   series: KeyVizSeries;
   generated_at: string;
+  fanout?: KeyVizFanoutResult;
 }
 
 export interface KeyVizParams {
diff --git a/web/admin/src/pages/KeyViz.tsx b/web/admin/src/pages/KeyViz.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useRef, useState } from "react";
-import type { KeyVizMatrix, KeyVizRow, KeyVizSeries } from "../api/client";
+import type { KeyVizFanoutResult, KeyVizMatrix, KeyVizRow, KeyVizSeries } from "../api/client";
 import { api } from "../api/client";
 import { ramp } from "../lib/colorRamp";
 import { formatApiError, useApiQuery } from "../lib/useApi";
@@ -56,6 +56,8 @@ export function KeyVizPage() {
         </div>
       </header>
 
+      {matrix.data?.fanout && <FanoutBanner fanout={matrix.data.fanout} />}
+
       <section className="card">
         {matrix.loading && !matrix.data && (
           <div className="text-sm text-muted">Loading…</div>
@@ -196,6 +198,14 @@ function Heatmap({ matrix }: HeatmapProps) {
           {matrix.rows.length} rows × {matrix.column_unix_ms.length} columns ·
           series <code className="font-mono">{matrix.series}</code> · max ={" "}
           {maxValue.toLocaleString()}
+          {matrix.fanout && (
+            <>
+              {" · "}
+              <span>
+                cluster view ({matrix.fanout.responded} of {matrix.fanout.expected} nodes)
+              </span>
+            </>
+          )}
         </span>
         <span>{new Date(matrix.generated_at).toLocaleString()}</span>
       </div>
@@ -209,13 +219,14 @@ function Heatmap({ matrix }: HeatmapProps) {
         // canvas as the user scrolls horizontally. Putting it outside
         // would freeze the labels under the left edge whenever the
         // canvas overflows.
-        <div className="overflow-auto border border-border rounded">
+        <div className="overflow-auto border border-border rounded relative">
           <canvas
             ref={canvasRef}
             onMouseMove={onMove}
             onMouseLeave={onLeave}
             style={{ display: "block", width, height }}
           />
+          <ConflictOverlay rows={matrix.rows} cellH={cellH} width={width} />
           <TimeAxis columnUnixMs={matrix.column_unix_ms} cellW={cellW} />
         </div>
       )}
@@ -226,6 +237,107 @@ function Heatmap({ matrix }: HeatmapProps) {
   );
 }
 
+// FanoutBanner renders the degraded-mode strip above the heatmap when
+// at least one peer failed to respond. Hidden when responded ===
+// expected so a healthy cluster keeps the page clean. Lists every
+// failed node with its error so operators can debug without checking
+// per-node logs.
+interface FanoutBannerProps {
+  fanout: KeyVizFanoutResult;
+}
+
+function FanoutBanner({ fanout }: FanoutBannerProps) {
+  if (fanout.responded >= fanout.expected) return null;
+  const failed = fanout.nodes.filter((n) => !n.ok);
+  return (
+    <div className="card border-danger/40">
+      <div className="text-sm font-semibold text-danger mb-2">
+        Cluster view degraded — {fanout.responded} of {fanout.expected} nodes responded
+      </div>
+      <ul className="text-xs text-muted space-y-0.5">
+        {failed.map((n) => (
+          <li key={n.node} className="font-mono">
+            <span className="text-danger">×</span> {n.node}
+            {n.error && <span className="text-muted"> — {n.error}</span>}
+          </li>
+        ))}
+      </ul>
+      <p className="text-xs text-muted mt-2">
+        The heatmap reflects the {fanout.responded} responding node{fanout.responded === 1 ? "" : "s"} only;
+        traffic served by the failed peers is not shown until they recover.
+      </p>
+    </div>
+  );
+}
+
+// ConflictOverlay layers a thin striped pattern over rows whose
+// merge produced disagreeing per-node values (Phase 2-C row-level
+// conflict flag). Per design 4.2, this is the SPA's signal that the
+// row's totals are best-effort dedup during a leadership flip and
+// may understate the true window. The overlay is an SVG layered
+// inside the scroll container so it tracks the canvas's scroll
+// position (same idiom as TimeAxis).
+//
+// Patterns rather than colour because the underlying canvas already
+// uses colour for intensity; a hatch communicates "soft data here"
+// without competing with the heatmap signal. SVG sized to (width,
+// rows.length × cellH) mirrors the canvas exactly.
+interface ConflictOverlayProps {
+  rows: KeyVizRow[];
+  cellH: number;
+  width: number;
+}
+
+function ConflictOverlay({ rows, cellH, width }: ConflictOverlayProps) {
+  const conflictRows = useMemo(() => {
+    const out: number[] = [];
+    for (let i = 0; i < rows.length; i++) {
+      if (rows[i].conflict) out.push(i);
+    }
+    return out;
+  }, [rows]);
+  if (conflictRows.length === 0) return null;
+  const totalH = rows.length * cellH;
+  return (
+    <svg
+      width={width}
+      height={totalH}
+      style={{
+        position: "absolute",
+        top: 0,
+        left: 0,
+        pointerEvents: "none",
+      }}
+      aria-hidden="true"
+    >
+      <defs>
+        {/* Diagonal hatch — 4px stride, 1px lines. The stroke uses
+            currentColor so the overlay inherits the text colour and
+            stays visible against both light and dark themes. */}
+        <pattern
+          id="keyviz-conflict-hatch"
+          width={4}
+          height={4}
+          patternUnits="userSpaceOnUse"
+          patternTransform="rotate(45)"
+        >
+          <line x1={0} y1={0} x2={0} y2={4} stroke="currentColor" strokeWidth={1} opacity={0.45} />
+        </pattern>
+      </defs>
+      {conflictRows.map((i) => (
+        <rect
+          key={i}
+          x={0}
+          y={i * cellH}
+          width={width}
+          height={cellH}
+          fill="url(#keyviz-conflict-hatch)"
+        />
+      ))}
+    </svg>
+  );
+}
+
 interface TimeAxisProps {
   columnUnixMs: number[];
   cellW: number;
@@ -284,10 +396,18 @@ function RowDetail({ row, index }: RowDetailProps) {
   const total = row.values.reduce((a, b) => a + b, 0);
   return (
     <div className="card text-sm">
-      <div className="flex items-center gap-2 mb-2">
+      <div className="flex items-center gap-2 mb-2 flex-wrap">
         <span className="text-xs text-muted">Row {index}</span>
         <span className="font-mono">{row.bucket_id}</span>
         {row.aggregate && <span className="pill-muted text-xs">aggregate</span>}
+        {row.conflict && (
+          <span
+            className="pill-muted text-xs"
+            title="Two or more nodes reported a non-zero value for the same cell — typical during a leadership flip mid-window. Displayed totals may understate the true count by up to one leader's pre-transfer slice."
+          >
+            conflict
+          </span>
+        )}
       </div>
       <dl className="grid grid-cols-2 gap-x-4 gap-y-1 text-xs">
         <dt className="text-muted">Start</dt>
