@cosmicdrift/kumiko-dispatcher-live 1.0.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dispatcher-live",
-  "version": "1.0.0",
+  "version": "2.0.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": "1.0.0"
+    "@cosmicdrift/kumiko-headless": "2.0.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

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

@@ -46,7 +46,10 @@ describe("createLiveDispatcher", () => {
     expect(headers["Content-Type"]).toBe("application/json");
     expect(headers["X-CSRF-Token"]).toBe("csrf-abc");
     const body = JSON.parse(call?.init.body as string);
-    expect(body).toEqual({ type: "app:write:task:create", payload: { title: "hello" } });
+    expect(body).toMatchObject({ type: "app:write:task:create", payload: { title: "hello" } });
+    // Auto-generated idempotency key (#761) — always present.
+    expect(typeof body.requestId).toBe("string");
+    expect(body.requestId.length).toBeGreaterThan(8);
   });
 
   test("write: propagates requestId into body when provided", async () => {
@@ -59,6 +62,43 @@ describe("createLiveDispatcher", () => {
     expect(body.requestId).toBe("idem-99");
   });
 
+  test("write: generates a fresh requestId per invocation when none provided (#761)", async () => {
+    const { fetch, calls } = makeFetch({ body: { isSuccess: true, data: {} } });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    await disp.write("app:write:x:create", { a: 1 });
+    await disp.write("app:write:x:create", { a: 1 });
+
+    const first = JSON.parse(calls[0]?.init.body as string).requestId;
+    const second = JSON.parse(calls[1]?.init.body as string).requestId;
+    expect(typeof first).toBe("string");
+    expect(typeof second).toBe("string");
+    expect(first).not.toBe(second);
+  });
+
+  test("batch: generates one requestId for the whole batch when none provided (#761)", async () => {
+    const { fetch, calls } = makeFetch({ body: { isSuccess: true, results: [] } });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    await disp.batch([
+      { type: "a", payload: {} },
+      { type: "b", payload: {} },
+    ]);
+
+    const body = JSON.parse(calls[0]?.init.body as string);
+    expect(typeof body.requestId).toBe("string");
+  });
+
+  test("batch: propagates an explicit requestId (#761)", async () => {
+    const { fetch, calls } = makeFetch({ body: { isSuccess: true, results: [] } });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    await disp.batch([{ type: "a", payload: {} }], { requestId: "batch-7" });
+
+    const body = JSON.parse(calls[0]?.init.body as string);
+    expect(body.requestId).toBe("batch-7");
+  });
+
   test("write: no CSRF token → header omitted, request still fires (server will 401/csrf-mismatch)", async () => {
     const { fetch, calls } = makeFetch({ body: { isSuccess: true, data: {} } });
     const disp = createLiveDispatcher({ fetch, readCsrf: () => undefined });
@@ -259,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,129 @@
+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/);
+  });
+
+  test("stream closed without a done frame throws instead of ending cleanly", async () => {
+    const text = ["event: chunk", 'data: {"i":0}', ""].join("\n");
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(text));
+        controller.close();
+      },
+    });
+
+    const chunks: unknown[] = [];
+    await expect(async () => {
+      for await (const c of iterateSseChunks(stream)) chunks.push(c);
+    }).toThrow(/without a done frame/);
+    expect(chunks).toEqual([{ i: 0 }]);
+  });
+
+  test("malformed chunk JSON throws a DispatcherError instead of a raw SyntaxError", async () => {
+    const text = ["event: chunk", "data: {not json", "", "event: done", "data: ", ""].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(/malformed chunk frame/);
+  });
+
+  test("cancels the reader on early break instead of leaving the response open", async () => {
+    let cancelled = false;
+    const text = ["event: chunk", 'data: {"i":0}', "", "event: chunk", 'data: {"i":1}', ""].join(
+      "\n",
+    );
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(text));
+      },
+      cancel() {
+        cancelled = true;
+      },
+    });
+
+    for await (const _ of iterateSseChunks(stream)) {
+      break;
+    }
+    expect(cancelled).toBe(true);
+  });
+});

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 ?? "";
@@ -154,7 +157,11 @@ export function createLiveDispatcher(options: LiveDispatcherOptions = {}): Dispa
       opts?: WriteOpts,
     ): Promise<WriteResult<TData>> {
       const body: Record<string, unknown> = { type, payload };
-      if (opts?.requestId) body["requestId"] = opts.requestId;
+      // Idempotency by default (#761): without a requestId the server-side
+      // dedup never engages and a transport-level double-send duplicates
+      // events. Callers with a logical-submit id (savable queue, form
+      // controllers) pass their own and keep it across their retries.
+      body["requestId"] = opts?.requestId ?? generateRequestId();
       const call = await callJson(PATH_WRITE, body, opts?.signal);
       return normalizeWriteResult<TData>(call);
     },
@@ -171,11 +178,90 @@ export function createLiveDispatcher(options: LiveDispatcherOptions = {}): Dispa
 
     async batch(commands: readonly Command[], opts?: WriteOpts): Promise<BatchResult> {
       const body: Record<string, unknown> = { commands };
-      if (opts?.requestId) body["requestId"] = opts.requestId;
+      // One id for the whole batch — the server caches the BatchResult
+      // under it, so a retried batch returns the cached outcome instead of
+      // re-executing the commands (#761).
+      body["requestId"] = opts?.requestId ?? generateRequestId();
       const call = await callJson(PATH_BATCH, body, opts?.signal);
       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();
+        observeNetworkOutcome(false);
+        throw e;
+      }
+    },
+
     statusStore,
     // Live dispatcher has no queue. Returning a constant empty array
     // keeps the contract uniform with savable; UI code that renders
@@ -189,6 +275,16 @@ export function createLiveDispatcher(options: LiveDispatcherOptions = {}): Dispa
 const EMPTY_PENDING_WRITES: readonly PendingWrite[] = Object.freeze([]);
 const EMPTY_PENDING_FILES: readonly PendingFile[] = Object.freeze([]);
 
+// crypto.randomUUID where available (browser, Bun, Node); Math.random
+// fallback for React-Native runtimes without the WebCrypto polyfill.
+// Uniqueness only needs to hold per user within the server's dedup window —
+// this is an idempotency key, not a security token.
+function generateRequestId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  return `req-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}
+
 type CallOutcome =
   | { readonly ok: true; readonly body: unknown; readonly status: number }
   | { readonly ok: false; readonly networkFailure: DispatcherError };

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, parseSseBlock, parseSseFrames } from "./sse-stream";

package/src/sse-stream.ts

@@ -0,0 +1,133 @@
+import { type DispatcherError, StreamFrame } 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 = "";
+  let sawDone = false;
+  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 === StreamFrame.ping) continue;
+        // skip: terminal SSE done frame — end the generator cleanly
+        if (frame.event === StreamFrame.done) {
+          sawDone = true;
+          return;
+        }
+        if (frame.event === StreamFrame.error) {
+          throw frameDataToDispatcherError(frame.data);
+        }
+        if (frame.event === StreamFrame.chunk) {
+          yield parseChunkData<TChunk>(frame.data);
+        }
+      }
+    }
+    // Trailing buffer without final blank line (some runtimes).
+    const frame = parseSseBlock(buffer);
+    if (frame?.event === StreamFrame.chunk) {
+      yield parseChunkData<TChunk>(frame.data);
+    } else if (frame?.event === StreamFrame.error) {
+      throw frameDataToDispatcherError(frame.data);
+    } else if (frame?.event === StreamFrame.done) {
+      sawDone = true;
+    }
+    if (!sawDone) {
+      throw buildTruncatedStreamError();
+    }
+  } finally {
+    // cancel() releases the reader's lock too (safe on an already-drained
+    // stream) and, unlike releaseLock() alone, tells the underlying HTTP
+    // response to close instead of leaving the connection open until the
+    // server finishes writing a body no one is reading anymore.
+    await reader.cancel().catch(() => {});
+  }
+}
+
+function parseChunkData<TChunk>(data: string): TChunk {
+  try {
+    return JSON.parse(data) as TChunk;
+  } catch (e) {
+    const cause = e instanceof Error ? e.message : String(e);
+    throw {
+      code: "stream_error",
+      httpStatus: 200,
+      i18nKey: "errors.unknown",
+      message: `malformed chunk frame: ${cause}`,
+    } satisfies DispatcherError;
+  }
+}
+
+function buildTruncatedStreamError(): DispatcherError {
+  return {
+    code: "stream_error",
+    httpStatus: 200,
+    i18nKey: "errors.unknown",
+    message: "stream ended without a done frame",
+  };
+}
+
+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,
+  });
+}