@kata-sh/pi-symphony-extension 0.1.0

package/src/event-stream.test.ts

@@ -0,0 +1,145 @@
+import { createServer, type Server } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { WebSocketServer } from "ws";
+import { eventStreamUrl, startSymphonyEventStream } from "./event-stream.ts";
+
+let server: Server | undefined;
+let socketServer: WebSocketServer | undefined;
+
+afterEach(async () => {
+  socketServer?.close();
+  socketServer = undefined;
+  if (server) {
+    await new Promise<void>((resolve, reject) => server!.close((error) => (error ? reject(error) : resolve())));
+    server = undefined;
+  }
+});
+
+async function serveWebSocket(): Promise<{ baseUrl: string; socketServer: WebSocketServer }> {
+  server = createServer();
+  socketServer = new WebSocketServer({ server, path: "/api/v1/events" });
+  await new Promise<void>((resolve) => server!.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("expected TCP address");
+  return { baseUrl: `http://127.0.0.1:${address.port}`, socketServer };
+}
+
+describe("event stream", () => {
+  it("converts HTTP API base URLs into WebSocket event URLs", () => {
+    expect(eventStreamUrl("http://127.0.0.1:8080")).toBe("ws://127.0.0.1:8080/api/v1/events");
+    expect(eventStreamUrl("https://example.test/base")).toBe("wss://example.test/base/api/v1/events");
+    expect(eventStreamUrl("wss://example.test/base")).toBe("wss://example.test/base/api/v1/events");
+    expect(() => eventStreamUrl("ftp://example.test/base")).toThrow("Unsupported Symphony base URL protocol: ftp:");
+  });
+
+  it("delivers parsed Symphony event envelopes", async () => {
+    const { baseUrl, socketServer } = await serveWebSocket();
+    socketServer.on("connection", (socket) => {
+      socket.send(JSON.stringify({
+        version: "v1",
+        sequence: 7,
+        timestamp: "2026-05-14T12:00:00Z",
+        kind: "worker",
+        severity: "info",
+        issue: "SIM-123",
+        event: "worker_completed",
+        payload: { summary: "done" },
+      }));
+    });
+    const received = new Promise<unknown>((resolve) => {
+      const handle = startSymphonyEventStream({
+        baseUrl,
+        onEvent: (event) => {
+          handle.close();
+          resolve(event);
+        },
+        onError: (error) => resolve(error),
+      });
+    });
+
+    await expect(received).resolves.toMatchObject({ sequence: 7, kind: "worker", event: "worker_completed" });
+  });
+
+  it("reports malformed event stream messages", async () => {
+    const { baseUrl, socketServer } = await serveWebSocket();
+    const onError = vi.fn();
+    const reported = new Promise<void>((resolve) => {
+      onError.mockImplementation(() => resolve());
+    });
+    socketServer.on("connection", (socket) => {
+      socket.send("not-json");
+    });
+
+    const handle = startSymphonyEventStream({ baseUrl, onEvent: () => undefined, onError });
+
+    await reported;
+    handle.close();
+
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining("invalid Symphony event") }));
+  });
+
+  it("does not report an error when intentionally closed before connecting", async () => {
+    const onError = vi.fn();
+    const handle = startSymphonyEventStream({
+      baseUrl: "http://127.0.0.1:9",
+      onEvent: () => undefined,
+      onError,
+    });
+
+    handle.close();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("reports an error when the server closes the stream", async () => {
+    const { baseUrl, socketServer } = await serveWebSocket();
+    const onError = vi.fn();
+    socketServer.on("connection", (socket) => {
+      socket.close(1000, "server shutdown");
+    });
+
+    const handle = startSymphonyEventStream({ baseUrl, onEvent: () => undefined, onError });
+
+    await expect.poll(() => onError.mock.calls.length, { interval: 10, timeout: 1000 }).toBe(1);
+    handle.close();
+
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining("Symphony event stream closed") }));
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining("server shutdown") }));
+  });
+
+  it("reconnects after an unexpected server close", async () => {
+    const { baseUrl, socketServer } = await serveWebSocket();
+    const onError = vi.fn();
+    let connectionCount = 0;
+    socketServer.on("connection", (socket) => {
+      connectionCount += 1;
+      if (connectionCount === 1) {
+        socket.close(1000, "restart");
+        return;
+      }
+      socket.send(JSON.stringify({
+        version: "v1",
+        sequence: 8,
+        timestamp: "2026-05-14T12:00:00Z",
+        kind: "runtime",
+        severity: "info",
+        event: "poll_completed",
+        payload: { summary: "reconnected" },
+      }));
+    });
+    const received = new Promise<unknown>((resolve) => {
+      const handle = startSymphonyEventStream({
+        baseUrl,
+        onEvent: (event) => {
+          handle.close();
+          resolve(event);
+        },
+        onError,
+      });
+    });
+
+    await expect(received).resolves.toMatchObject({ sequence: 8, event: "poll_completed" });
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining("Symphony event stream closed") }));
+  });
+});

package/src/event-stream.ts

@@ -0,0 +1,107 @@
+import { WebSocket } from "ws";
+import type { SymphonyEventEnvelope } from "./http-client.ts";
+
+export interface EventStreamOptions {
+  baseUrl: string;
+  onEvent: (event: SymphonyEventEnvelope) => void;
+  onError: (error: Error) => void;
+}
+
+export interface EventStreamHandle {
+  close: () => void;
+}
+
+export function eventStreamUrl(baseUrl: string): string {
+  const url = new URL(baseUrl);
+  if (url.protocol === "https:" || url.protocol === "wss:") {
+    url.protocol = "wss:";
+  } else if (url.protocol === "http:" || url.protocol === "ws:") {
+    url.protocol = "ws:";
+  } else {
+    throw new Error(`Unsupported Symphony base URL protocol: ${url.protocol}`);
+  }
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/api/v1/events`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+export function startSymphonyEventStream(options: EventStreamOptions): EventStreamHandle {
+  let socket: WebSocket | undefined;
+  let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  let intentionallyClosed = false;
+  let reconnectDelayMs = 100;
+  const maxReconnectDelayMs = 5000;
+
+  const connect = () => {
+    socket = new WebSocket(eventStreamUrl(options.baseUrl));
+
+    socket.on("open", () => {
+      reconnectDelayMs = 100;
+    });
+
+    socket.on("message", (data) => {
+      try {
+        options.onEvent(parseEventEnvelope(data.toString()));
+      } catch (error) {
+        options.onError(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+
+    socket.on("error", (error) => {
+      if (intentionallyClosed) return;
+      options.onError(error instanceof Error ? error : new Error(String(error)));
+    });
+
+    socket.on("close", (code, reason) => {
+      if (intentionallyClosed) return;
+      const suffix = reason.length > 0 ? `: ${reason.toString()}` : ` with code ${code}`;
+      options.onError(new Error(`Symphony event stream closed${suffix}`));
+      reconnectTimer = setTimeout(connect, reconnectDelayMs);
+      reconnectDelayMs = Math.min(reconnectDelayMs * 2, maxReconnectDelayMs);
+    });
+  };
+
+  connect();
+
+  return {
+    close: () => {
+      intentionallyClosed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      socket?.close();
+    },
+  };
+}
+
+function parseEventEnvelope(text: string): SymphonyEventEnvelope {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`invalid Symphony event JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  if (!isRecord(value)) throw new Error("invalid Symphony event: envelope was not an object");
+  if (value.version !== "v1") throw new Error("invalid Symphony event: version was not v1");
+  if (typeof value.sequence !== "number") throw new Error("invalid Symphony event: sequence was not a number");
+  if (typeof value.timestamp !== "string") throw new Error("invalid Symphony event: timestamp was not a string");
+  if (typeof value.kind !== "string") throw new Error("invalid Symphony event: kind was not a string");
+  if (typeof value.severity !== "string") throw new Error("invalid Symphony event: severity was not a string");
+  if (value.issue !== undefined && typeof value.issue !== "string") throw new Error("invalid Symphony event: issue was not a string");
+  if (typeof value.event !== "string") throw new Error("invalid Symphony event: event was not a string");
+
+  return {
+    version: value.version,
+    sequence: value.sequence,
+    timestamp: value.timestamp,
+    kind: value.kind,
+    severity: value.severity,
+    issue: value.issue,
+    event: value.event,
+    payload: value.payload,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}