Merge branch 'pr-159'

Author: mikewheeleer

docs/events-validation.md

@@ -0,0 +1,16 @@
+# Event Log Validation
+
+The event log treats the `/api/v1/events` response as untrusted data before it
+reaches React rendering.
+
+`src/lib/events.ts` validates each record at the UI boundary:
+
+- `id` and `type` must be strings.
+- `ts` must be a finite number.
+- `payload` must be an object.
+- payload previews are stringified with circular-reference protection.
+- oversized payload previews are truncated.
+- at most 200 valid events are rendered, even if the API returns more.
+
+Malformed records are dropped. When the rendered list is capped, the events page
+shows a short note with the rendered count and total valid count.

src/app/events/Client.tsx

@@ -2,21 +2,22 @@
 
 import { useEffect, useState } from "react";
 import { apiGet } from "@/lib/apiClient";
-
-type AppEvent = {
-  id: string;
-  ts: number;
-  type: string;
-  payload: Record<string, unknown>;
-};
+import { parseEventsResponse, type DisplayEvent } from "@/lib/events";
 
 export default function EventsClient() {
-  const [items, setItems] = useState<AppEvent[] | null>(null);
+  const [items, setItems] = useState<DisplayEvent[] | null>(null);
+  const [totalValid, setTotalValid] = useState(0);
+  const [capped, setCapped] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
-    apiGet<{ items: AppEvent[] }>("/api/v1/events?limit=100")
-      .then((b) => setItems(b.items))
+    apiGet<unknown>("/api/v1/events?limit=100")
+      .then((b) => {
+        const parsed = parseEventsResponse(b);
+        setItems(parsed.events);
+        setTotalValid(parsed.totalValid);
+        setCapped(parsed.capped);
+      })
       .catch((e) => setError(e.message));
   }, []);
 
@@ -34,22 +35,29 @@ export default function EventsClient() {
           <p className="text-sm text-neutral-600 dark:text-neutral-400">No events.</p>
         )}
         {items && items.length > 0 && (
-          <ol className="flex flex-col gap-2">
-            {items.map((e) => (
-              <li
-                key={e.id}
-                className="rounded border border-neutral-200 p-3 font-mono text-xs dark:border-neutral-800"
-              >
-                <div className="flex justify-between text-neutral-500">
-                  <span>{e.type}</span>
-                  <span>{new Date(e.ts).toISOString()}</span>
-                </div>
-                <pre className="mt-2 whitespace-pre-wrap break-words">
-                  {JSON.stringify(e.payload, null, 2)}
-                </pre>
-              </li>
-            ))}
-          </ol>
+          <>
+            {capped && (
+              <p className="text-sm text-neutral-600 dark:text-neutral-400">
+                Showing {items.length} of {totalValid} events (capped).
+              </p>
+            )}
+            <ol className="flex flex-col gap-2">
+              {items.map((e) => (
+                <li
+                  key={e.id}
+                  className="rounded border border-neutral-200 p-3 font-mono text-xs dark:border-neutral-800"
+                >
+                  <div className="flex justify-between text-neutral-500">
+                    <span>{e.type}</span>
+                    <span>{new Date(e.ts).toISOString()}</span>
+                  </div>
+                  <pre className="mt-2 whitespace-pre-wrap break-words">
+                    {e.payloadPreview}
+                  </pre>
+                </li>
+              ))}
+            </ol>
+          </>
         )}
       </section>
     </main>

src/app/events/page.test.tsx

@@ -1,5 +1,6 @@
 import { render, screen, waitFor } from "@testing-library/react";
 import EventsPage from "./page";
+import { MAX_RENDERED_EVENTS } from "@/lib/events";
 
 describe("EventsPage", () => {
   let originalFetch: typeof global.fetch;
@@ -68,4 +69,76 @@ describe("EventsPage", () => {
     });
     expect(document.querySelectorAll("[aria-live=polite]")).toHaveLength(1);
   });
+
+  it("drops malformed event records instead of throwing during render", async () => {
+    global.fetch = jest.fn().mockResolvedValueOnce({
+      ok: true,
+      text: async () =>
+        JSON.stringify({
+          items: [
+            { id: "evt1", ts: 1_782_460_000_000, type: "pair.registered", payload: {} },
+            { ts: 1_782_460_000_001, type: "missing.id", payload: {} },
+            { id: "evt2", ts: "not-a-number", type: "bad.ts", payload: {} },
+            { id: "evt3", ts: 1_782_460_000_002, payload: {} },
+            { id: "evt4", ts: 1_782_460_000_003, type: "bad.payload" },
+            { id: "evt5", ts: 1_782_460_000_004, type: "string.payload", payload: "nope" },
+          ],
+        }),
+    } as unknown as Response);
+
+    render(<EventsPage />);
+
+    expect(await screen.findByText("pair.registered")).toBeInTheDocument();
+    expect(screen.queryByText("missing.id")).not.toBeInTheDocument();
+    expect(screen.queryByText("bad.ts")).not.toBeInTheDocument();
+    expect(screen.queryByText("bad.payload")).not.toBeInTheDocument();
+    expect(screen.queryByText("string.payload")).not.toBeInTheDocument();
+  });
+
+  it("bounds rendered records and surfaces a capped note", async () => {
+    const events = Array.from({ length: MAX_RENDERED_EVENTS + 3 }, (_, index) => ({
+      id: `evt${index}`,
+      ts: 1_782_460_000_000 + index,
+      type: `event.${index}`,
+      payload: { index },
+    }));
+    global.fetch = jest.fn().mockResolvedValueOnce({
+      ok: true,
+      text: async () => JSON.stringify({ items: events }),
+    } as unknown as Response);
+
+    render(<EventsPage />);
+
+    expect(
+      await screen.findByText(
+        `Showing ${MAX_RENDERED_EVENTS} of ${MAX_RENDERED_EVENTS + 3} events (capped).`,
+      ),
+    ).toBeInTheDocument();
+    expect(screen.getByText("event.0")).toBeInTheDocument();
+    expect(screen.getByText(`event.${MAX_RENDERED_EVENTS - 1}`)).toBeInTheDocument();
+    expect(screen.queryByText(`event.${MAX_RENDERED_EVENTS}`)).not.toBeInTheDocument();
+  });
+
+  it("truncates oversized payload previews", async () => {
+    global.fetch = jest.fn().mockResolvedValueOnce({
+      ok: true,
+      text: async () =>
+        JSON.stringify({
+          items: [
+            {
+              id: "evt-large",
+              ts: 1_782_460_000_000,
+              type: "payload.large",
+              payload: { body: "x".repeat(5000) },
+            },
+          ],
+        }),
+    } as unknown as Response);
+
+    render(<EventsPage />);
+
+    expect(await screen.findByText("payload.large")).toBeInTheDocument();
+    expect(screen.getByText(/truncated/)).toBeInTheDocument();
+  });
+
 });

src/lib/events.test.ts

@@ -0,0 +1,73 @@
+import {
+  MAX_PAYLOAD_PREVIEW_LENGTH,
+  MAX_RENDERED_EVENTS,
+  parseEventsResponse,
+} from "./events";
+
+describe("parseEventsResponse", () => {
+  it("returns an empty safe result for malformed response shapes", () => {
+    expect(parseEventsResponse(null)).toEqual({
+      events: [],
+      totalValid: 0,
+      capped: false,
+    });
+    expect(parseEventsResponse({ items: "not-an-array" })).toEqual({
+      events: [],
+      totalValid: 0,
+      capped: false,
+    });
+  });
+
+  it("renders circular payloads with a safe marker", () => {
+    const circularPayload: Record<string, unknown> = { label: "root" };
+    circularPayload.self = circularPayload;
+
+    const result = parseEventsResponse({
+      items: [
+        {
+          id: "evt-circular",
+          ts: 1_782_460_000_000,
+          type: "payload.circular",
+          payload: circularPayload,
+        },
+      ],
+    });
+
+    expect(result.events).toHaveLength(1);
+    expect(result.events[0].payloadPreview).toContain("[Circular]");
+  });
+
+  it("truncates oversized payload previews", () => {
+    const result = parseEventsResponse({
+      items: [
+        {
+          id: "evt-large",
+          ts: 1_782_460_000_000,
+          type: "payload.large",
+          payload: { body: "x".repeat(MAX_PAYLOAD_PREVIEW_LENGTH + 100) },
+        },
+      ],
+    });
+
+    expect(result.events).toHaveLength(1);
+    expect(result.events[0].payloadPreview.length).toBeLessThan(
+      MAX_PAYLOAD_PREVIEW_LENGTH + 50,
+    );
+    expect(result.events[0].payloadPreview).toContain("truncated");
+  });
+
+  it("caps valid event rows defensively", () => {
+    const result = parseEventsResponse({
+      items: Array.from({ length: MAX_RENDERED_EVENTS + 1 }, (_, index) => ({
+        id: `evt${index}`,
+        ts: 1_782_460_000_000 + index,
+        type: `event.${index}`,
+        payload: { index },
+      })),
+    });
+
+    expect(result.events).toHaveLength(MAX_RENDERED_EVENTS);
+    expect(result.totalValid).toBe(MAX_RENDERED_EVENTS + 1);
+    expect(result.capped).toBe(true);
+  });
+});

src/lib/events.ts

@@ -0,0 +1,120 @@
+export type AppEvent = {
+  id: string;
+  ts: number;
+  type: string;
+  payload: unknown;
+};
+
+export type DisplayEvent = {
+  id: string;
+  ts: number;
+  type: string;
+  payloadPreview: string;
+};
+
+export const MAX_RENDERED_EVENTS = 200;
+export const MAX_PAYLOAD_PREVIEW_LENGTH = 4_000;
+
+type EventsResponse = {
+  items: unknown[];
+};
+
+/**
+ * Validates the event-log API response at the UI boundary and returns only
+ * render-safe records. Malformed records are dropped instead of throwing.
+ */
+export function parseEventsResponse(raw: unknown): {
+  events: DisplayEvent[];
+  totalValid: number;
+  capped: boolean;
+} {
+  if (!isEventsResponse(raw)) {
+    return { events: [], totalValid: 0, capped: false };
+  }
+
+  const validEvents = raw.items.flatMap((item) => {
+    const event = parseAppEvent(item);
+    return event ? [event] : [];
+  });
+  const capped = validEvents.length > MAX_RENDERED_EVENTS;
+
+  return {
+    events: validEvents.slice(0, MAX_RENDERED_EVENTS),
+    totalValid: validEvents.length,
+    capped,
+  };
+}
+
+function isEventsResponse(raw: unknown): raw is EventsResponse {
+  return (
+    typeof raw === "object" &&
+    raw !== null &&
+    Array.isArray((raw as { items?: unknown }).items)
+  );
+}
+
+function parseAppEvent(raw: unknown): DisplayEvent | null {
+  if (typeof raw !== "object" || raw === null) {
+    return null;
+  }
+
+  const event = raw as Partial<AppEvent>;
+
+  if (
+    typeof event.id !== "string" ||
+    typeof event.ts !== "number" ||
+    !Number.isFinite(event.ts) ||
+    typeof event.type !== "string"
+  ) {
+    return null;
+  }
+
+  if (typeof event.payload !== "object" || event.payload === null) {
+    return null;
+  }
+
+  const payloadPreview = safeStringifyPayload(event.payload);
+
+  if (payloadPreview === null) {
+    return null;
+  }
+
+  return {
+    id: event.id,
+    ts: event.ts,
+    type: event.type,
+    payloadPreview,
+  };
+}
+
+function safeStringifyPayload(payload: unknown): string | null {
+  const seen = new WeakSet<object>();
+
+  try {
+    const serialized = JSON.stringify(
+      payload,
+      (_key, value) => {
+        if (typeof value === "object" && value !== null) {
+          if (seen.has(value)) {
+            return "[Circular]";
+          }
+          seen.add(value);
+        }
+        return value;
+      },
+      2,
+    );
+
+    if (typeof serialized !== "string") {
+      return null;
+    }
+
+    if (serialized.length <= MAX_PAYLOAD_PREVIEW_LENGTH) {
+      return serialized;
+    }
+
+    return `${serialized.slice(0, MAX_PAYLOAD_PREVIEW_LENGTH)}\n… truncated`;
+  } catch {
+    return null;
+  }
+}