@mandujs/core 0.13.0 → 0.13.1

package/src/filling/context.ts

@@ -9,7 +9,8 @@ import type { ZodSchema } from "zod";
 import type { ContractSchema, ContractMethod } from "../contract/schema";
 import type { InferBody, InferHeaders, InferParams, InferQuery, InferResponse } from "../contract/types";
 import { ContractValidator, type ContractValidatorOptions } from "../contract/validator";
-import { type FillingDeps, createDefaultDeps, globalDeps } from "./deps";
+import { type FillingDeps, globalDeps } from "./deps";
+import { createSSEConnection, type SSEOptions, type SSEConnection } from "./sse";
 
 type ContractInput<
   TContract extends ContractSchema,
@@ -531,6 +532,28 @@ export class ManduContext {
     return this.withCookies(response);
   }
 
+  /**
+   * Create a Server-Sent Events (SSE) response.
+   *
+   * @example
+   * return ctx.sse((sse) => {
+   *   sse.event("ready", { ok: true });
+   *   const stop = sse.heartbeat(15000);
+   *   sse.onClose(() => stop());
+   * });
+   */
+  sse(setup?: (connection: SSEConnection) => void | Promise<void>, options: SSEOptions = {}): Response {
+    const connection = createSSEConnection(this.request.signal, options);
+
+    if (setup) {
+      Promise.resolve(setup(connection)).catch(() => {
+        void connection.close();
+      });
+    }
+
+    return this.withCookies(connection.response);
+  }
+
   // ============================================
   // 🥟 상태 저장 (Lifecycle → Handler 전달)
   // ============================================

package/src/filling/deps.ts

@@ -1,238 +1,238 @@
-/**
- * DNA-002: Dependency Injection Pattern
- *
- * Filling 핸들러의 의존성을 명시적으로 주입
- * - 테스트 시 목킹 용이
- * - 의존성 역전 원칙 (DIP) 준수
- * - 외부 서비스와의 결합도 감소
- */
-
-/**
- * 데이터베이스 의존성 인터페이스
- */
-export interface DbDeps {
-  /**
-   * SQL 쿼리 실행
-   */
-  query: <T>(sql: string, params?: unknown[]) => Promise<T>;
-
-  /**
-   * 트랜잭션 실행
-   */
-  transaction: <T>(fn: () => Promise<T>) => Promise<T>;
-}
-
-/**
- * 캐시 의존성 인터페이스
- */
-export interface CacheDeps {
-  /**
-   * 캐시에서 값 조회
-   */
-  get: <T>(key: string) => Promise<T | null>;
-
-  /**
-   * 캐시에 값 저장
-   * @param ttl - Time to live (초 단위)
-   */
-  set: <T>(key: string, value: T, ttl?: number) => Promise<void>;
-
-  /**
-   * 캐시에서 값 삭제
-   */
-  delete: (key: string) => Promise<void>;
-
-  /**
-   * 패턴에 맞는 키 삭제
-   */
-  deletePattern?: (pattern: string) => Promise<void>;
-}
-
-/**
- * 로거 의존성 인터페이스
- */
-export interface LoggerDeps {
-  debug: (msg: string, data?: unknown) => void;
-  info: (msg: string, data?: unknown) => void;
-  warn: (msg: string, data?: unknown) => void;
-  error: (msg: string, data?: unknown) => void;
-}
-
-/**
- * 이벤트 버스 의존성 인터페이스
- */
-export interface EventBusDeps {
-  /**
-   * 이벤트 발행
-   */
-  emit: (event: string, payload: unknown) => void;
-
-  /**
-   * 이벤트 구독
-   */
-  on: (event: string, handler: (payload: unknown) => void) => () => void;
-}
-
-/**
- * Filling 핸들러 의존성 타입
- *
- * 모든 필드는 선택적 → 필요한 것만 주입
- */
-export interface FillingDeps {
-  /**
-   * 데이터베이스 접근
-   */
-  db?: DbDeps;
-
-  /**
-   * 캐시 접근
-   */
-  cache?: CacheDeps;
-
-  /**
-   * HTTP 클라이언트
-   */
-  fetch?: typeof fetch;
-
-  /**
-   * 로거
-   */
-  logger?: LoggerDeps;
-
-  /**
-   * 이벤트 버스
-   */
-  events?: EventBusDeps;
-
-  /**
-   * 현재 시간 (테스트용)
-   */
-  now?: () => Date;
-
-  /**
-   * UUID 생성 (테스트용)
-   */
-  uuid?: () => string;
-
-  /**
-   * 커스텀 의존성
-   */
-  [key: string]: unknown;
-}
-
-/**
- * 기본 의존성 생성
- *
- * @example
- * ```ts
- * const deps = createDefaultDeps();
- * console.log(deps.now()); // 현재 시간
- * ```
- */
-export function createDefaultDeps(): FillingDeps {
-  return {
-    fetch: globalThis.fetch,
-    logger: {
-      debug: (msg, data) => console.debug(`[DEBUG] ${msg}`, data ?? ""),
-      info: (msg, data) => console.info(`[INFO] ${msg}`, data ?? ""),
-      warn: (msg, data) => console.warn(`[WARN] ${msg}`, data ?? ""),
-      error: (msg, data) => console.error(`[ERROR] ${msg}`, data ?? ""),
-    },
-    now: () => new Date(),
-    uuid: () => crypto.randomUUID(),
-  };
-}
-
-/**
- * 테스트용 목 의존성 생성 헬퍼
- *
- * @example
- * ```ts
- * const mockDeps = createMockDeps({
- *   db: {
- *     query: vi.fn().mockResolvedValue([{ id: 1, name: "Test" }]),
- *     transaction: vi.fn(fn => fn()),
- *   },
- *   now: () => new Date("2025-01-01"),
- * });
- * ```
- */
-export function createMockDeps(overrides: Partial<FillingDeps> = {}): FillingDeps {
-  const noop = () => {};
-  const asyncNoop = async () => {};
-
-  return {
-    db: {
-      query: async () => [] as any,
-      transaction: async (fn) => fn(),
-    },
-    cache: {
-      get: async () => null,
-      set: asyncNoop,
-      delete: asyncNoop,
-    },
-    fetch: async () => new Response(),
-    logger: {
-      debug: noop,
-      info: noop,
-      warn: noop,
-      error: noop,
-    },
-    events: {
-      emit: noop,
-      on: () => noop,
-    },
-    now: () => new Date("2025-01-01T00:00:00Z"),
-    uuid: () => "00000000-0000-0000-0000-000000000000",
-    ...overrides,
-  };
-}
-
-/**
- * 의존성 병합 (기본값 + 커스텀)
- */
-export function mergeDeps(
-  base: FillingDeps,
-  overrides: Partial<FillingDeps>
-): FillingDeps {
-  return { ...base, ...overrides };
-}
-
-/**
- * 의존성 컨테이너 (싱글톤 관리)
- */
-class DepsContainer {
-  private deps: FillingDeps = createDefaultDeps();
-
-  /**
-   * 전역 의존성 설정
-   */
-  set(deps: Partial<FillingDeps>): void {
-    this.deps = mergeDeps(this.deps, deps);
-  }
-
-  /**
-   * 전역 의존성 가져오기
-   */
-  get(): FillingDeps {
-    return this.deps;
-  }
-
-  /**
-   * 기본값으로 리셋
-   */
-  reset(): void {
-    this.deps = createDefaultDeps();
-  }
-}
-
-/**
- * 전역 의존성 컨테이너
- */
-export const globalDeps = new DepsContainer();
-
-/**
- * 의존성 주입 데코레이터 타입
- * (향후 클래스 기반 핸들러 지원 시)
- */
-export type InjectDeps<T extends keyof FillingDeps> = Pick<FillingDeps, T>;
+/**
+ * DNA-002: Dependency Injection Pattern
+ *
+ * Filling 핸들러의 의존성을 명시적으로 주입
+ * - 테스트 시 목킹 용이
+ * - 의존성 역전 원칙 (DIP) 준수
+ * - 외부 서비스와의 결합도 감소
+ */
+
+/**
+ * 데이터베이스 의존성 인터페이스
+ */
+export interface DbDeps {
+  /**
+   * SQL 쿼리 실행
+   */
+  query: <T>(sql: string, params?: unknown[]) => Promise<T>;
+
+  /**
+   * 트랜잭션 실행
+   */
+  transaction: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+
+/**
+ * 캐시 의존성 인터페이스
+ */
+export interface CacheDeps {
+  /**
+   * 캐시에서 값 조회
+   */
+  get: <T>(key: string) => Promise<T | null>;
+
+  /**
+   * 캐시에 값 저장
+   * @param ttl - Time to live (초 단위)
+   */
+  set: <T>(key: string, value: T, ttl?: number) => Promise<void>;
+
+  /**
+   * 캐시에서 값 삭제
+   */
+  delete: (key: string) => Promise<void>;
+
+  /**
+   * 패턴에 맞는 키 삭제
+   */
+  deletePattern?: (pattern: string) => Promise<void>;
+}
+
+/**
+ * 로거 의존성 인터페이스
+ */
+export interface LoggerDeps {
+  debug: (msg: string, data?: unknown) => void;
+  info: (msg: string, data?: unknown) => void;
+  warn: (msg: string, data?: unknown) => void;
+  error: (msg: string, data?: unknown) => void;
+}
+
+/**
+ * 이벤트 버스 의존성 인터페이스
+ */
+export interface EventBusDeps {
+  /**
+   * 이벤트 발행
+   */
+  emit: (event: string, payload: unknown) => void;
+
+  /**
+   * 이벤트 구독
+   */
+  on: (event: string, handler: (payload: unknown) => void) => () => void;
+}
+
+/**
+ * Filling 핸들러 의존성 타입
+ *
+ * 모든 필드는 선택적 → 필요한 것만 주입
+ */
+export interface FillingDeps {
+  /**
+   * 데이터베이스 접근
+   */
+  db?: DbDeps;
+
+  /**
+   * 캐시 접근
+   */
+  cache?: CacheDeps;
+
+  /**
+   * HTTP 클라이언트
+   */
+  fetch?: typeof fetch;
+
+  /**
+   * 로거
+   */
+  logger?: LoggerDeps;
+
+  /**
+   * 이벤트 버스
+   */
+  events?: EventBusDeps;
+
+  /**
+   * 현재 시간 (테스트용)
+   */
+  now?: () => Date;
+
+  /**
+   * UUID 생성 (테스트용)
+   */
+  uuid?: () => string;
+
+  /**
+   * 커스텀 의존성
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * 기본 의존성 생성
+ *
+ * @example
+ * ```ts
+ * const deps = createDefaultDeps();
+ * console.log(deps.now()); // 현재 시간
+ * ```
+ */
+export function createDefaultDeps(): FillingDeps {
+  return {
+    fetch: globalThis.fetch,
+    logger: {
+      debug: (msg, data) => console.debug(`[DEBUG] ${msg}`, data ?? ""),
+      info: (msg, data) => console.info(`[INFO] ${msg}`, data ?? ""),
+      warn: (msg, data) => console.warn(`[WARN] ${msg}`, data ?? ""),
+      error: (msg, data) => console.error(`[ERROR] ${msg}`, data ?? ""),
+    },
+    now: () => new Date(),
+    uuid: () => crypto.randomUUID(),
+  };
+}
+
+/**
+ * 테스트용 목 의존성 생성 헬퍼
+ *
+ * @example
+ * ```ts
+ * const mockDeps = createMockDeps({
+ *   db: {
+ *     query: vi.fn().mockResolvedValue([{ id: 1, name: "Test" }]),
+ *     transaction: vi.fn(fn => fn()),
+ *   },
+ *   now: () => new Date("2025-01-01"),
+ * });
+ * ```
+ */
+export function createMockDeps(overrides: Partial<FillingDeps> = {}): FillingDeps {
+  const noop = () => {};
+  const asyncNoop = async () => {};
+
+  return {
+    db: {
+      query: async () => [] as any,
+      transaction: async (fn) => fn(),
+    },
+    cache: {
+      get: async () => null,
+      set: asyncNoop,
+      delete: asyncNoop,
+    },
+    fetch: async () => new Response(),
+    logger: {
+      debug: noop,
+      info: noop,
+      warn: noop,
+      error: noop,
+    },
+    events: {
+      emit: noop,
+      on: () => noop,
+    },
+    now: () => new Date("2025-01-01T00:00:00Z"),
+    uuid: () => "00000000-0000-0000-0000-000000000000",
+    ...overrides,
+  };
+}
+
+/**
+ * 의존성 병합 (기본값 + 커스텀)
+ */
+export function mergeDeps(
+  base: FillingDeps,
+  overrides: Partial<FillingDeps>
+): FillingDeps {
+  return { ...base, ...overrides };
+}
+
+/**
+ * 의존성 컨테이너 (싱글톤 관리)
+ */
+class DepsContainer {
+  private deps: FillingDeps = createDefaultDeps();
+
+  /**
+   * 전역 의존성 설정
+   */
+  set(deps: Partial<FillingDeps>): void {
+    this.deps = mergeDeps(this.deps, deps);
+  }
+
+  /**
+   * 전역 의존성 가져오기
+   */
+  get(): FillingDeps {
+    return this.deps;
+  }
+
+  /**
+   * 기본값으로 리셋
+   */
+  reset(): void {
+    this.deps = createDefaultDeps();
+  }
+}
+
+/**
+ * 전역 의존성 컨테이너
+ */
+export const globalDeps = new DepsContainer();
+
+/**
+ * 의존성 주입 데코레이터 타입
+ * (향후 클래스 기반 핸들러 지원 시)
+ */
+export type InjectDeps<T extends keyof FillingDeps> = Pick<FillingDeps, T>;

package/src/filling/index.ts

@@ -8,6 +8,8 @@ export { ManduContext, ValidationError, CookieManager } from "./context";
 export type { CookieOptions } from "./context";
 export { ManduFilling, ManduFillingFactory, LoaderTimeoutError } from "./filling";
 export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";
+export { SSEConnection, createSSEConnection } from "./sse";
+export type { SSEOptions, SSESendOptions, SSECleanup } from "./sse";
 
 // Auth Guards
 export {

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");
+  });
+});