@cosmicdrift/kumiko-dispatcher-live 0.158.2 → 0.160.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dispatcher-live",
-  "version": "0.158.2",
+  "version": "0.160.0",
   "description": "HTTP-only Dispatcher for Kumiko UIs. Always-online; failures surface immediately. Default client for web admin/cockpit apps.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -24,7 +24,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-headless": "0.158.2"
+    "@cosmicdrift/kumiko-headless": "0.160.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/__tests__/dispatcher-live.test.ts

@@ -299,6 +299,93 @@ describe("createLiveDispatcher", () => {
     expect(disp.pendingFiles()).toEqual([]);
   });
 
+  test("stream: POSTs to /api/stream, yields chunk frames, stops on done", async () => {
+    const sse = [
+      "event: chunk",
+      'data: {"i":0}',
+      "",
+      "event: ping",
+      "data: ",
+      "",
+      "event: chunk",
+      'data: {"i":1}',
+      "",
+      "event: done",
+      "data: ",
+      "",
+    ].join("\n");
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const fetchMock = mock(async (url: string, init: RequestInit) => {
+      calls.push({ url, init });
+      return new Response(sse, {
+        status: 200,
+        headers: { "content-type": "text/event-stream" },
+      });
+    }) as unknown as typeof globalThis.fetch;
+
+    const disp = createLiveDispatcher({ fetch: fetchMock, readCsrf: () => "csrf-s" });
+    const chunks: unknown[] = [];
+    for await (const c of disp.stream("app:stream:x:tail", { n: 2 })) chunks.push(c);
+
+    expect(chunks).toEqual([{ i: 0 }, { i: 1 }]);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.url).toBe("/api/stream");
+    expect(calls[0]?.init.method).toBe("POST");
+    const headers = calls[0]?.init.headers as Record<string, string>;
+    expect(headers["Accept"]).toBe("text/event-stream");
+    expect(headers["X-CSRF-Token"]).toBe("csrf-s");
+    expect(JSON.parse(calls[0]?.init.body as string)).toEqual({
+      type: "app:stream:x:tail",
+      payload: { n: 2 },
+    });
+  });
+
+  test("stream: non-SSE JSON error envelope maps like query failures", async () => {
+    const fetchMock = mock(async () =>
+      Response.json(
+        {
+          error: {
+            code: "csrf_token_mismatch",
+            httpStatus: 403,
+            i18nKey: "errors.csrf",
+            message: "csrf",
+          },
+        },
+        { status: 403 },
+      ),
+    ) as unknown as typeof globalThis.fetch;
+
+    const disp = createLiveDispatcher({ fetch: fetchMock, readCsrf: () => undefined });
+    let thrown: unknown;
+    try {
+      for await (const _ of disp.stream("app:stream:x:tail", {})) {
+        // no chunks
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "csrf_token_mismatch" });
+  });
+
+  test("stream: AbortError on fetch maps to code aborted", async () => {
+    const fetchMock = mock(async (_url: string, init?: RequestInit) => {
+      expect(init?.signal).toBeInstanceOf(AbortSignal);
+      throw new DOMException("The operation was aborted.", "AbortError");
+    }) as unknown as typeof globalThis.fetch;
+
+    const disp = createLiveDispatcher({ fetch: fetchMock, readCsrf: () => "t" });
+    const ctrl = new AbortController();
+    let thrown: unknown;
+    try {
+      for await (const _ of disp.stream("app:stream:x:tail", {}, { signal: ctrl.signal })) {
+        // no chunks
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "aborted" });
+  });
+
   test("subscribeStatus returns unsubscribe handle", async () => {
     const fetch = mock(async () => {
       throw new Error("boom");

package/src/__tests__/sse-stream.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { iterateSseChunks, parseSseFrames } from "../sse-stream";
+
+describe("parseSseFrames", () => {
+  test("parses chunk + done frames from a complete body", () => {
+    const text = [
+      "event: chunk",
+      'data: {"i":0}',
+      "",
+      "event: chunk",
+      'data: {"i":1}',
+      "",
+      "event: ping",
+      "data: ",
+      "",
+      "event: done",
+      "data: ",
+      "",
+    ].join("\n");
+
+    expect(parseSseFrames(text)).toEqual([
+      { event: "chunk", data: '{"i":0}' },
+      { event: "chunk", data: '{"i":1}' },
+      { event: "ping", data: "" },
+      { event: "done", data: "" },
+    ]);
+  });
+});
+
+describe("iterateSseChunks", () => {
+  test("yields JSON chunks, swallows ping, stops on done", async () => {
+    const text = [
+      "event: chunk",
+      'data: {"i":0}',
+      "",
+      "event: ping",
+      "data: ",
+      "",
+      "event: chunk",
+      'data: {"i":1}',
+      "",
+      "event: done",
+      "data: ",
+      "",
+    ].join("\n");
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(text));
+        controller.close();
+      },
+    });
+
+    const chunks: unknown[] = [];
+    for await (const c of iterateSseChunks(stream)) chunks.push(c);
+    expect(chunks).toEqual([{ i: 0 }, { i: 1 }]);
+  });
+
+  test("error frame throws mapped DispatcherError", async () => {
+    const text = [
+      "event: error",
+      'data: {"code":"access_denied","httpStatus":403,"i18nKey":"errors.access","message":"nope"}',
+      "",
+    ].join("\n");
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(text));
+        controller.close();
+      },
+    });
+
+    await expect(async () => {
+      for await (const _ of iterateSseChunks(stream)) {
+        // no chunks expected
+      }
+    }).toThrow(/nope/);
+  });
+});

package/src/dispatcher-live.ts

@@ -9,11 +9,13 @@ import {
   type PendingWrite,
   type QueryOpts,
   type QueryResult,
+  type StreamOpts,
   type WriteOpts,
   type WriteResult,
 } from "@cosmicdrift/kumiko-headless";
 import { CSRF_HEADER_NAME, readCsrfToken } from "./csrf";
 import { buildAbortError, buildNetworkError, mapServerError } from "./error-mapping";
+import { iterateSseChunks } from "./sse-stream";
 
 // HTTP-only dispatcher. Maps Kumiko's client-side Dispatcher contract to
 // `POST /api/{write,query,batch}`. No local store, no queue, no retry —
@@ -55,6 +57,7 @@ export type LiveDispatcherOptions = {
 const PATH_WRITE = "/api/write";
 const PATH_QUERY = "/api/query";
 const PATH_BATCH = "/api/batch";
+const PATH_STREAM = "/api/stream";
 
 export function createLiveDispatcher(options: LiveDispatcherOptions = {}): Dispatcher {
   const baseUrl = options.baseUrl ?? "";
@@ -183,6 +186,81 @@ export function createLiveDispatcher(options: LiveDispatcherOptions = {}): Dispa
       return normalizeBatchResponse(call);
     },
 
+    async *stream<TChunk = unknown>(
+      type: string,
+      payload: unknown,
+      opts?: StreamOpts,
+    ): AsyncGenerator<TChunk, void, undefined> {
+      const f = options.fetch ?? globalThis.fetch;
+      if (!f) {
+        throw buildNetworkError(
+          "fetch is not available in this runtime — inject via LiveDispatcherOptions.fetch",
+        );
+      }
+
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+      };
+      const csrf = readCsrf();
+      if (csrf !== undefined) headers[CSRF_HEADER_NAME] = csrf;
+
+      let response: Response;
+      try {
+        response = await f(`${baseUrl}${PATH_STREAM}`, {
+          method: "POST",
+          credentials: "include",
+          headers,
+          body: JSON.stringify({ type, payload }),
+          signal: opts?.signal,
+        });
+      } catch (e) {
+        if (isAbortError(e)) throw buildAbortError();
+        observeNetworkOutcome(false);
+        throw buildNetworkError(e);
+      }
+
+      observeNetworkOutcome(true);
+
+      const contentType = response.headers.get("content-type") ?? "";
+      // Pre-SSE gate failures (PAT deny, etc.) return a normal JSON error
+      // envelope — map them like /api/query before trying to read SSE.
+      if (!contentType.includes("text/event-stream")) {
+        let parsed: unknown;
+        try {
+          parsed = await response.json();
+        } catch (e) {
+          throw buildNetworkError(
+            `invalid stream response (${response.status}): ${
+              e instanceof Error ? e.message : String(e)
+            }`,
+          );
+        }
+        const body = parsed as { error?: ServerErrorLike };
+        if (body?.error) {
+          throw mapServerError({
+            ...body.error,
+            httpStatus: body.error.httpStatus ?? response.status,
+          });
+        }
+        throw buildNetworkError(`unexpected non-SSE stream response (${response.status})`);
+      }
+
+      if (!response.body) {
+        throw buildNetworkError("stream response has no body");
+      }
+
+      try {
+        yield* iterateSseChunks<TChunk>(response.body);
+      } catch (e) {
+        // Abort can surface on the initial fetch OR while reading the SSE
+        // body — both must map to the same `aborted` envelope so hooks
+        // (useStreamHandler) can ignore user-cancel without an error toast.
+        if (isAbortError(e) || opts?.signal?.aborted) throw buildAbortError();
+        throw e;
+      }
+    },
+
     statusStore,
     // Live dispatcher has no queue. Returning a constant empty array
     // keeps the contract uniform with savable; UI code that renders

package/src/index.ts

@@ -2,3 +2,5 @@ export { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, readCsrfToken } from "./csrf";
 export type { LiveDispatcherOptions } from "./dispatcher-live";
 export { createLiveDispatcher } from "./dispatcher-live";
 export { buildAbortError, buildNetworkError, mapServerError } from "./error-mapping";
+export type { SseFrame } from "./sse-stream";
+export { iterateSseChunks, parseSseFrames } from "./sse-stream";

package/src/sse-stream.ts

@@ -0,0 +1,97 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import { mapServerError } from "./error-mapping";
+
+// Parse the SSE wire format produced by Hono `streamSSE` for POST /api/stream:
+//   event: chunk|ping|done|error
+//   data: <json-or-empty>
+//   <blank line>
+//
+// Exported for unit tests — live dispatcher is the only production caller.
+
+export type SseFrame = {
+  readonly event: string;
+  readonly data: string;
+};
+
+export function parseSseBlock(block: string): SseFrame | null {
+  const trimmed = block.trim();
+  if (trimmed.length === 0) return null;
+  const event = /^event: (.*)$/m.exec(trimmed)?.[1] ?? "";
+  const data = /^data: (.*)$/m.exec(trimmed)?.[1] ?? "";
+  return { event, data };
+}
+
+/** Split a complete SSE body (tests / non-streaming buffers) into frames. */
+export function parseSseFrames(text: string): SseFrame[] {
+  return text
+    .split("\n\n")
+    .map(parseSseBlock)
+    .filter((f): f is SseFrame => f !== null);
+}
+
+/**
+ * Incremental SSE reader over a fetch body. Yields `chunk` payloads as
+ * parsed JSON; swallows `ping`; returns on `done`; throws DispatcherError
+ * on `error` frames. Caller is responsible for aborting the underlying
+ * fetch via AbortSignal.
+ */
+export async function* iterateSseChunks<TChunk>(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<TChunk, void, undefined> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop() ?? "";
+      for (const part of parts) {
+        const frame = parseSseBlock(part);
+        if (frame === null) continue;
+        if (frame.event === "ping") continue;
+        // skip: terminal SSE done frame — end the generator cleanly
+        if (frame.event === "done") return;
+        if (frame.event === "error") {
+          throw frameDataToDispatcherError(frame.data);
+        }
+        if (frame.event === "chunk") {
+          yield JSON.parse(frame.data) as TChunk;
+        }
+      }
+    }
+    // Trailing buffer without final blank line (some runtimes).
+    const frame = parseSseBlock(buffer);
+    if (frame?.event === "chunk") {
+      yield JSON.parse(frame.data) as TChunk;
+    } else if (frame?.event === "error") {
+      throw frameDataToDispatcherError(frame.data);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function frameDataToDispatcherError(data: string): DispatcherError {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return {
+      code: "stream_error",
+      httpStatus: 200,
+      i18nKey: "errors.unknown",
+      message: data.length > 0 ? data : "stream error frame",
+    };
+  }
+  // Server serializeError shape — mapServerError expects the same fields
+  // as /api/query failures (httpStatus may be absent; reinject 200 for
+  // mid-stream gates that flush SSE headers first).
+  const err = parsed as Parameters<typeof mapServerError>[0];
+  return mapServerError({
+    ...err,
+    httpStatus: err.httpStatus ?? 200,
+  });
+}