@mandujs/core 0.13.0 → 0.13.2

package/src/filling/sse.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, mock } from "bun:test";
+import { createSSEConnection } from "./sse";
+import { ManduContext } from "./context";
+
+async function readChunk(response: Response): Promise<string> {
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error("Missing response body");
+
+  const { value, done } = await reader.read();
+  if (done || !value) return "";
+  return new TextDecoder().decode(value);
+}
+
+describe("SSEConnection", () => {
+  it("streams real-time chunks and finishes with done=true after close", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch(req) {
+        const ctx = new ManduContext(req);
+        return ctx.sse(async (sse) => {
+          sse.event("tick", { step: 1 }, { id: "1" });
+          await new Promise((resolve) => setTimeout(resolve, 20));
+          sse.event("tick", { step: 2 }, { id: "2" });
+          await sse.close();
+        });
+      },
+    });
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${server.port}/stream`);
+      expect(response.headers.get("content-type")).toContain("text/event-stream");
+
+      const reader = response.body?.getReader();
+      if (!reader) throw new Error("Missing response body");
+
+      const firstRead = await reader.read();
+      expect(firstRead.done).toBe(false);
+      const firstChunk = new TextDecoder().decode(firstRead.value);
+      expect(firstChunk).toContain("event: tick");
+      expect(firstChunk).toContain('data: {"step":1}');
+
+      const secondRead = await reader.read();
+      expect(secondRead.done).toBe(false);
+      const secondChunk = new TextDecoder().decode(secondRead.value);
+      expect(secondChunk).toContain('data: {"step":2}');
+
+      const finalRead = await reader.read();
+      expect(finalRead.done).toBe(true);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  it("closes stream when context-level SSE setup throws (error path)", async () => {
+    const ctx = new ManduContext(new Request("http://localhost/realtime-error"));
+
+    const response = ctx.sse(async () => {
+      throw new Error("setup failed");
+    });
+
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("Missing response body");
+
+    // setup error is swallowed intentionally, but stream must close cleanly.
+    await Promise.resolve();
+    const read = await reader.read();
+    expect(read.done).toBe(true);
+  });
+  it("sends SSE event payload with metadata", async () => {
+    const sse = createSSEConnection();
+
+    sse.send({ ok: true }, { event: "ready", id: "1", retry: 3000 });
+    const chunk = await readChunk(sse.response);
+
+    expect(chunk).toContain("event: ready");
+    expect(chunk).toContain("id: 1");
+    expect(chunk).toContain("retry: 3000");
+    expect(chunk).toContain('data: {"ok":true}');
+  });
+
+  it("sanitizes event/id fields to prevent SSE injection", async () => {
+    const sse = createSSEConnection();
+
+    sse.send("payload", {
+      event: "update\nretry:0",
+      id: "abc\r\ndata: injected",
+    });
+
+    const chunk = await readChunk(sse.response);
+    expect(chunk).toContain("event: update retry:0");
+    expect(chunk).toContain("id: abc data: injected");
+    expect(chunk).not.toContain("\nevent: update\nretry:0\n");
+  });
+
+  it("normalizes payload lines across CR/LF variants", async () => {
+    const sse = createSSEConnection();
+
+    sse.send("a\rb\nc\r\nd");
+    const chunk = await readChunk(sse.response);
+
+    expect(chunk).toContain("data: a");
+    expect(chunk).toContain("data: b");
+    expect(chunk).toContain("data: c");
+    expect(chunk).toContain("data: d");
+  });
+
+  it("registers heartbeat and cleanup on close", async () => {
+    const sse = createSSEConnection();
+    const cleanup = mock(() => {});
+
+    const stop = sse.heartbeat(1000, "ping");
+    sse.onClose(cleanup);
+
+    await sse.close();
+
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(typeof stop).toBe("function");
+  });
+
+  it("continues closing when cleanup handlers throw", async () => {
+    const sse = createSSEConnection();
+    const badCleanup = mock(() => {
+      throw new Error("cleanup failed");
+    });
+    const goodCleanup = mock(() => {});
+
+    sse.onClose(badCleanup);
+    sse.onClose(goodCleanup);
+
+    await expect(sse.close()).resolves.toBeUndefined();
+    expect(badCleanup).toHaveBeenCalledTimes(1);
+    expect(goodCleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not throw when registering onClose after already closed", async () => {
+    const sse = createSSEConnection();
+    await sse.close();
+
+    const badCleanup = () => Promise.reject(new Error("late cleanup failed"));
+    expect(() => sse.onClose(badCleanup)).not.toThrow();
+  });
+
+  it("closes automatically when request signal aborts", async () => {
+    const controller = new AbortController();
+    const sse = createSSEConnection(controller.signal);
+    const cleanup = mock(() => {});
+
+    sse.onClose(cleanup);
+    controller.abort();
+
+    await Promise.resolve();
+
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("supports context-level SSE response helper", async () => {
+    const ctx = new ManduContext(new Request("http://localhost/realtime"));
+
+    const response = ctx.sse((sse) => {
+      sse.event("message", "hello");
+    });
+
+    expect(response.headers.get("content-type")).toContain("text/event-stream");
+    const chunk = await readChunk(response);
+    expect(chunk).toContain("event: message");
+    expect(chunk).toContain("data: hello");
+  });
+});

package/src/filling/sse.ts

@@ -0,0 +1,162 @@
+export interface SSEOptions {
+  /** Additional headers merged into default SSE headers */
+  headers?: HeadersInit;
+  /** HTTP status code (default: 200) */
+  status?: number;
+}
+
+export interface SSESendOptions {
+  event?: string;
+  id?: string;
+  retry?: number;
+}
+
+export type SSECleanup = () => void | Promise<void>;
+
+function sanitizeSingleLineField(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").trim();
+}
+
+function splitSSELines(value: string): string[] {
+  return value.split(/\r\n|[\r\n]/);
+}
+
+const DEFAULT_SSE_HEADERS: HeadersInit = {
+  "Content-Type": "text/event-stream; charset=utf-8",
+  "Cache-Control": "no-cache, no-transform",
+  Connection: "keep-alive",
+  "X-Accel-Buffering": "no",
+};
+
+export class SSEConnection {
+  readonly response: Response;
+
+  private controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+  private encoder = new TextEncoder();
+  private pending: string[] = [];
+  private closed = false;
+  private cleanupHandlers: SSECleanup[] = [];
+
+  constructor(signal?: AbortSignal, options: SSEOptions = {}) {
+    const stream = new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        this.controller = controller;
+        for (const chunk of this.pending) {
+          controller.enqueue(this.encoder.encode(chunk));
+        }
+        this.pending = [];
+      },
+      cancel: () => {
+        this.close();
+      },
+    });
+
+    const headers = new Headers(DEFAULT_SSE_HEADERS);
+    if (options.headers) {
+      const extra = new Headers(options.headers);
+      extra.forEach((value, key) => headers.set(key, value));
+    }
+
+    this.response = new Response(stream, {
+      status: options.status ?? 200,
+      headers,
+    });
+
+    signal?.addEventListener("abort", () => this.close(), { once: true });
+  }
+
+  send(data: unknown, options: SSESendOptions = {}): void {
+    if (this.closed) return;
+
+    const lines: string[] = [];
+
+    if (options.event) {
+      const safeEvent = sanitizeSingleLineField(options.event);
+      if (safeEvent) lines.push(`event: ${safeEvent}`);
+    }
+    if (options.id) {
+      const safeId = sanitizeSingleLineField(options.id);
+      if (safeId) lines.push(`id: ${safeId}`);
+    }
+    if (typeof options.retry === "number") lines.push(`retry: ${Math.max(0, Math.floor(options.retry))}`);
+
+    const payload = typeof data === "string" ? data : JSON.stringify(data);
+    const payloadLines = splitSSELines(payload);
+    for (const line of payloadLines) {
+      lines.push(`data: ${line}`);
+    }
+
+    this.enqueue(`${lines.join("\n")}\n\n`);
+  }
+
+  event(name: string, data: unknown, options: Omit<SSESendOptions, "event"> = {}): void {
+    this.send(data, { ...options, event: name });
+  }
+
+  comment(text: string): void {
+    if (this.closed) return;
+    const lines = splitSSELines(text).map((line) => `: ${line}`);
+    this.enqueue(`${lines.join("\n")}\n\n`);
+  }
+
+  heartbeat(intervalMs = 15000, comment = "heartbeat"): () => void {
+    const timer = setInterval(() => {
+      if (this.closed) return;
+      this.comment(comment);
+    }, Math.max(1000, intervalMs));
+
+    const stop = () => clearInterval(timer);
+    this.onClose(stop);
+    return stop;
+  }
+
+  onClose(handler: SSECleanup): void {
+    if (this.closed) {
+      void Promise.resolve(handler()).catch(() => {
+        // ignore cleanup errors after close
+      });
+      return;
+    }
+    this.cleanupHandlers.push(handler);
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+
+    try {
+      this.controller?.close();
+    } catch {
+      // no-op
+    }
+
+    const handlers = [...this.cleanupHandlers];
+    this.cleanupHandlers = [];
+    for (const handler of handlers) {
+      try {
+        await handler();
+      } catch {
+        // continue running remaining cleanup handlers
+      }
+    }
+  }
+
+  private enqueue(chunk: string): void {
+    if (this.controller) {
+      try {
+        this.controller.enqueue(this.encoder.encode(chunk));
+      } catch {
+        void this.close();
+      }
+      return;
+    }
+    this.pending.push(chunk);
+  }
+}
+
+/**
+ * Create a production-safe Server-Sent Events connection helper.
+ */
+export function createSSEConnection(signal?: AbortSignal, options: SSEOptions = {}): SSEConnection {
+  return new SSEConnection(signal, options);
+}

package/src/generator/index.ts

@@ -1,3 +1,3 @@
-export * from "./generate";
-export * from "./templates";
-export * from "./contract-glue";
+export * from "./generate";
+export * from "./templates";
+export * from "./contract-glue";