@remember-web/sse 0.1.0-alpha.1

package/src/core/SseClient.scenarios.test.ts

@@ -0,0 +1,164 @@
+// @vitest-environment node
+import { describe, expect, it, vi } from 'vitest';
+
+import type { SseStatus } from './types';
+
+import {
+  createHarness,
+  lastSource,
+  openConnection,
+  setupFakeTimers,
+} from '../testing';
+
+/**
+ * 유저 여정 시나리오 — 기계 계약(전이·호출 단위)은 SseClient.connection.test.ts가 고정하고,
+ * 이 파일은 사용자 경험 하나를 처음부터 끝까지 걷습니다. 여기가 깨지면 "어떤 경험이 깨졌는지"가 이름에 드러납니다.
+ */
+
+setupFakeTimers();
+
+describe('유저 시나리오', () => {
+  it('화면에 처음 들어오면 실시간 수신이 시작된다', async () => {
+    const { client } = createHarness();
+    const received: { id: string }[] = [];
+
+    client.on('demo.created', (event) => received.push(event));
+    client.connect();
+    await vi.advanceTimersByTimeAsync(0);
+    lastSource().dispatch('hello');
+
+    lastSource().dispatch('demo.created', '{"id":"m1"}');
+    expect(client.status).toBe('open');
+    expect(received).toEqual([{ id: 'm1' }]);
+  });
+
+  it('이동 중 네트워크가 끊겨도 개입 없이 다시 연결되고, 놓친 구간을 메울 수 있게 resync를 알린다', async () => {
+    // 이 테스트가 의존하는 재시도 지연을 명시합니다 — 기본값 튜닝이 아래 대기 시간과 어긋나지 않게
+    const { client } = createHarness({ backoff: { initialDelayMs: 1000 } });
+    const received: { id: string }[] = [];
+    const statuses: SseStatus[] = [];
+    let resyncFired = false;
+    client.on('demo.created', (event) => received.push(event));
+    client.on('resync', () => {
+      resyncFired = true;
+    });
+    client.onStatus((status) => statuses.push(status));
+
+    await openConnection(client);
+    lastSource().dispatch('demo.created', '{"id":"m1"}');
+
+    lastSource().error();
+    expect(statuses.at(-1)).toBe('reconnecting');
+
+    await vi.advanceTimersByTimeAsync(1000);
+    lastSource().dispatch('hello');
+    expect(resyncFired).toBe(true);
+
+    lastSource().dispatch('demo.created', '{"id":"m2"}');
+    expect(received).toEqual([{ id: 'm1' }, { id: 'm2' }]);
+  });
+
+  it('서버가 배포로 연결을 정리해도(goaway) 대기 없이 즉시 재수립되어 수신이 이어진다', async () => {
+    const { client, ticketRequests } = createHarness();
+    const received: { id: string }[] = [];
+    let resyncFired = false;
+    client.on('demo.created', (event) => received.push(event));
+    client.on('resync', () => {
+      resyncFired = true;
+    });
+
+    await openConnection(client);
+    lastSource().dispatch('goaway');
+
+    // 타이머를 진행하지 않았는데 티켓이 재발급됨 — 대기 없는 즉시 재수립
+    await vi.advanceTimersByTimeAsync(0);
+    expect(ticketRequests()).toHaveLength(2);
+    lastSource().dispatch('hello');
+    expect(resyncFired).toBe(true);
+
+    lastSource().dispatch('demo.created', '{"id":"m1"}');
+    expect(client.status).toBe('open');
+    expect(received).toEqual([{ id: 'm1' }]);
+  });
+
+  it('세션이 만료되면 멈춰서 알리고, 재로그인 후 다시 연결할 수 있다', async () => {
+    const { client, ticketRequests, failTicketsWith } = createHarness();
+    const statuses: SseStatus[] = [];
+    client.onStatus((status) => statuses.push(status));
+
+    failTicketsWith(401);
+    client.connect();
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(statuses.at(-1)).toBe('fatal');
+    await vi.advanceTimersByTimeAsync(120_000);
+    expect(ticketRequests()).toHaveLength(1);
+
+    // fatal의 출구는 disconnect뿐이라, 정리한 뒤 다시 connect한다
+    failTicketsWith(null);
+    client.disconnect();
+    client.connect();
+    await vi.advanceTimersByTimeAsync(0);
+    lastSource().dispatch('hello');
+
+    expect(statuses.at(-1)).toBe('open');
+  });
+
+  it('사내 차단 등으로 연결이 계속 안 붙으면 안내(stalled)를 받고, 환경이 풀리면 개입 없이 회복된다', async () => {
+    let blocked = true;
+    let ticketCounter = 0;
+    const firewallFetch = (async () => {
+      if (blocked) {
+        throw new Error('network');
+      }
+      ticketCounter += 1;
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ data: { ticket: `ticket-${ticketCounter}` } }),
+      } as unknown as Response;
+    }) as unknown as typeof globalThis.fetch;
+    const { client } = createHarness({ fetch: firewallFetch });
+    const received: { id: string }[] = [];
+    let stalledCount = 0;
+    client.on('stalled', () => {
+      stalledCount += 1;
+    });
+    client.on('demo.created', (event) => received.push(event));
+
+    client.connect();
+    await vi.advanceTimersByTimeAsync(0);
+    await vi.advanceTimersByTimeAsync(1000);
+    await vi.advanceTimersByTimeAsync(2000);
+    await vi.advanceTimersByTimeAsync(4000);
+    expect(stalledCount).toBe(0);
+
+    await vi.advanceTimersByTimeAsync(8000);
+    expect(stalledCount).toBe(1);
+    // 안내가 나가도 재시도는 멈추지 않는다 — 회복의 전제
+    expect(client.status).toBe('reconnecting');
+
+    blocked = false;
+    await vi.advanceTimersByTimeAsync(16_000);
+    lastSource().dispatch('hello');
+    expect(client.status).toBe('open');
+
+    lastSource().dispatch('demo.created', '{"id":"m1"}');
+    expect(received).toEqual([{ id: 'm1' }]);
+    expect(stalledCount).toBe(1);
+  });
+
+  it('수신하던 화면을 떠나면 연결을 닫는다 — 서버 슬롯은 유휴 정리에 맡긴다', async () => {
+    const { client } = createHarness();
+    const received: { id: string }[] = [];
+    client.on('demo.created', (event) => received.push(event));
+
+    await openConnection(client);
+    lastSource().dispatch('demo.created', '{"id":"m1"}');
+    expect(received).toEqual([{ id: 'm1' }]);
+
+    client.disconnect();
+    expect(client.status).toBe('closed');
+    expect(lastSource().closed).toBe(true);
+  });
+});

package/src/core/SseClient.test.ts

@@ -0,0 +1,63 @@
+// @vitest-environment node
+import { describe, expect, it } from 'vitest';
+
+import { SseClient } from './SseClient';
+import type { SseClientLike } from './types';
+import { wire } from './wire';
+
+// interface 픽스처인 이유: M 제약이 Record로 조여지면 이 파일이 컴파일 에러로 잡습니다
+interface TestEventMap {
+  'demo.created': { id: string };
+}
+
+const createClient = () =>
+  new SseClient<TestEventMap>({
+    baseUrl: 'https://example.test',
+    getAuthToken: () => '',
+  });
+
+// no-throw·구독·리스너 격리 계약은 SseClientLike.contract.test.ts가 두 구현을 함께 검증합니다
+describe('SSR 안전성', () => {
+  it('EventSource가 없으면 connect()는 상태 전이 없이 조용한 no-op입니다', () => {
+    const client = createClient();
+    client.connect();
+    expect(client.status).toBe('idle');
+  });
+});
+
+describe('wire()', () => {
+  it('모든 핸들러의 일괄 해제 함수를 반환합니다', () => {
+    const client = createClient();
+    const unwire = wire(client, {
+      resync: () => {},
+      'demo.created': () => {},
+    });
+    expect(() => unwire()).not.toThrow();
+  });
+
+  it('undefined·null 같은 호출 불가능한 핸들러는 등록하지 않고 건너뜁니다', () => {
+    const registered: string[] = [];
+    const observingClient = {
+      on: (type: string) => {
+        registered.push(type);
+        return () => {};
+      },
+    } as unknown as SseClientLike<TestEventMap>;
+    const jsConsumerHandlers = {
+      resync: undefined,
+      'null.handler': null,
+      'demo.created': () => {},
+    } as unknown as Parameters<typeof wire>[1];
+
+    wire(observingClient, jsConsumerHandlers);
+
+    expect(registered).toEqual(['demo.created']);
+  });
+
+  it('맵에 없는 키를 컴파일에서 거부합니다', () => {
+    const client = createClient();
+    // @ts-expect-error 맵(M)에 없는 이벤트 키는 WireHandlers가 거부합니다
+    const unwire = wire(client, { 'not.in.map': () => {} });
+    expect(() => unwire()).not.toThrow();
+  });
+});

package/src/core/SseClient.ts

@@ -0,0 +1,310 @@
+import type { Backoff } from './backoff';
+import { createBackoff } from './backoff';
+import { BaseSseClient } from './BaseSseClient';
+import { SDK_EVENTS, SERVER_CONNECTION_EVENTS } from './eventNames';
+import { waitForRetry } from './retryWait';
+import type { StatusMachine } from './statusMachine';
+import { createStatusMachine } from './statusMachine';
+import type { AttachedEvents, StreamOutcome } from './stream';
+import { attachDomainListener, streamUntilClosed } from './stream';
+import type { TicketResult } from './ticket';
+import { issueTicketWithTimeout } from './ticket';
+import type {
+  FatalCause,
+  FatalPayload,
+  SseClientOptions,
+  SseEventMap,
+  SseStatus,
+} from './types';
+
+// 상태 코드 → 사유 매핑이 단일 원천입니다 — 멈출 코드 판정과 사유가 같은 표에서 나와 어긋날 수 없습니다
+const TICKET_FATAL_CAUSES = {
+  401: 'auth',
+  403: 'auth',
+  429: 'rate_limit',
+} as const satisfies Record<number, FatalCause>;
+
+type FatalTicketStatus = keyof typeof TICKET_FATAL_CAUSES;
+
+const isFatalTicketStatus = (status: number): status is FatalTicketStatus =>
+  status in TICKET_FATAL_CAUSES;
+
+const HELLO_TIMEOUT_MS = 10_000;
+
+// 즉시 실패(CORS·오프라인)의 기본 백오프(full jitter) 기준 최대 15초, 보통 7~8초 안에 알립니다 — 순간 끊김에는 침묵합니다
+const STALLED_AFTER_ATTEMPTS = 5;
+
+/**
+ * @description 내부 확장 지점 — 워커가 티켓 발급을 탭에 위임할 때 씁니다.
+ * 공개 옵션(SseClientOptions)에는 노출하지 않습니다: 소비처가 티켓 발급 절차를 바꿀 이유가 없습니다.
+ */
+export interface SseClientInternals {
+  issueTicket?: () => Promise<TicketResult>;
+  /** @description 워커가 인스턴스를 갈아끼워도 재수립 판정이 이어지게 합니다 — 첫 hello가 resync를 쏠지 가릅니다 */
+  hasOpenedBefore?: boolean;
+}
+
+/** @description SSR 환경에서도 안전하게 생성할 수 있습니다 — 연결은 connect()를 호출할 때 시작됩니다 */
+export class SseClient<
+  M extends object = SseEventMap,
+> extends BaseSseClient<M> {
+  readonly #backoff: Backoff;
+  readonly #machine: StatusMachine;
+
+  #currentStream: {
+    source: EventSource;
+    attachedEvents: AttachedEvents;
+  } | null = null;
+
+  #abort: AbortController | null = null;
+  #hasOpened: boolean;
+  #networkFailures = 0;
+
+  constructor(
+    protected readonly options: SseClientOptions,
+    protected readonly internals: SseClientInternals = {}
+  ) {
+    super(options.logger);
+    this.#hasOpened = internals.hasOpenedBefore ?? false;
+    this.#backoff = createBackoff(options.backoff);
+    this.#machine = createStatusMachine((status) =>
+      this.emitter.emitStatus(status)
+    );
+  }
+
+  get status(): SseStatus {
+    return this.#machine.status;
+  }
+
+  connect(): void {
+    if ((this.options.eventSource ?? globalThis.EventSource) === undefined) {
+      // SSR 대응 - no-op
+      return;
+    }
+
+    const controller = new AbortController();
+    const previous = this.#abort;
+    // 전이 통지 중 리스너가 disconnect()해도 이 controller가 abort되도록 전이보다 먼저 교체합니다
+    this.#abort = controller;
+
+    if (!this.#machine.transition('connect')) {
+      this.#abort = previous;
+      if (this.#machine.status === 'fatal') {
+        this.options.logger?.warn(
+          'sse: fatal 상태에서는 connect()가 무시됩니다 — disconnect()로 정리한 뒤 다시 connect() 하세요'
+        );
+      }
+      return;
+    }
+    if (controller.signal.aborted) {
+      return;
+    }
+
+    // 루프가 예외로 죽으면 재시도가 영영 없습니다 — fatal로 떨어뜨려 회복 경로(정리 후 connect)에 맡깁니다
+    void this.#runConnection(controller.signal).catch((error) => {
+      this.options.logger?.error('sse: 연결 루프가 예외로 중단됐습니다', error);
+      // 전이가 거부된 상태(reconnecting 등)에서 발화하면 "전이 후 발화" 계약이 깨집니다
+      if (this.#machine.transition('fatalFailure')) {
+        this.emitter.emit(SDK_EVENTS.fatal, {
+          cause: 'unknown',
+        } satisfies FatalPayload);
+      }
+    });
+  }
+
+  disconnect(): void {
+    // abort가 연결 루프를 중단합니다 — 진행 중이던 티켓 발급·대기·스트림 전부
+    this.#abort?.abort();
+    this.#abort = null;
+    this.#endSession();
+    this.#machine.transition('disconnect');
+  }
+
+  // 한 연결 세션을 접습니다 — 다음 connect()가 첫 연결처럼 시작하도록 재수립 판단과 백오프도 함께 되돌립니다
+  #endSession(): void {
+    this.#closeStream();
+    this.#hasOpened = false;
+    this.#backoff.reset();
+    this.#networkFailures = 0;
+  }
+
+  /**
+   * @description hello에 닿지 못한 네트워크성(응답 status 부재) 연속 실패를 셉니다 — 임계값 도달 순간에만
+   * stalled를 발화해 한 구간에 한 번만 알립니다. 반드시 상태 전이 뒤에 부르세요.
+   * 연속은 open 도달과 서버 응답(5xx)이 끊고, 스트림 단계 실패는 status가 없어 전부 여기 해당합니다.
+   */
+  #countNetworkFailure(): void {
+    this.#networkFailures += 1;
+    if (this.#networkFailures === STALLED_AFTER_ATTEMPTS) {
+      this.emitter.emit(SDK_EVENTS.stalled, undefined);
+    }
+  }
+
+  // 열린 스트림이 없으면 조용히 넘어갑니다 — 다음 #openStream이 구독 장부를 보고 한 번에 붙입니다
+  protected registerSubscription(type: string): void {
+    this.#attachSourceListener(type);
+  }
+
+  // 티켓 발급 → 스트림 유지 → 끊김 → 대기 → 재시도. disconnect(abort)만이 루프를 종료합니다
+  async #runConnection(signal: AbortSignal): Promise<void> {
+    while (!signal.aborted) {
+      const next = await this.#attemptConnection(signal);
+      if (signal.aborted || next === 'stop') {
+        return;
+      }
+
+      if (next === 'retryWithDelay') {
+        await waitForRetry(this.#backoff.nextDelayMs(), signal);
+        if (signal.aborted) {
+          return;
+        }
+      }
+      this.#machine.transition('readyToRetry');
+    }
+  }
+
+  // 스트림이 끊길 때까지 대기하고, 루프의 다음 동작('stop'·'retryWithDelay'·'retryNow')을 반환합니다
+  async #attemptConnection(
+    signal: AbortSignal
+  ): Promise<'stop' | 'retryWithDelay' | 'retryNow'> {
+    const result = await (this.internals.issueTicket?.() ??
+      issueTicketWithTimeout(this.options));
+
+    if (signal.aborted) {
+      return 'stop';
+    }
+
+    if (!result.ok) {
+      const { status, cause } = result.error;
+
+      // 로그는 원인 예외를 쥔 ticket.ts가 남깁니다 — 여기서 또 찍으면 직결 경로에서 같은 말이 두 줄 됩니다
+      if (cause === 'auth_callback') {
+        this.#machine.transition('fatalFailure');
+        this.emitter.emit(SDK_EVENTS.fatal, {
+          cause: 'auth_callback',
+        } satisfies FatalPayload);
+        return 'stop';
+      }
+
+      if (status !== undefined && isFatalTicketStatus(status)) {
+        this.options.logger?.warn(
+          `sse: 티켓 발급이 ${status}로 거부되어 멈춥니다 — disconnect()로 정리한 뒤 다시 connect() 하세요`
+        );
+        this.#machine.transition('fatalFailure');
+        // 전이를 마친 뒤 알립니다 — 핸들러가 그 자리에서 disconnect()·connect() 회복을 시작할 수 있게
+        this.emitter.emit(SDK_EVENTS.fatal, {
+          cause: TICKET_FATAL_CAUSES[status],
+          status,
+        } satisfies FatalPayload);
+        return 'stop';
+      }
+
+      this.#machine.transition('retryableFailure');
+      // 서버가 응답한 거부(5xx 등)는 네트워크성이 아니라 세지 않습니다 — 서버 장애에 네트워크 안내가 나가는 오안내를 막습니다
+      if (status === undefined) {
+        this.#countNetworkFailure();
+      } else {
+        this.#networkFailures = 0;
+      }
+      return 'retryWithDelay';
+    }
+
+    try {
+      const outcome = await this.#openStream(result.ticket, signal);
+      if (outcome === 'goaway-close') {
+        return 'stop';
+      }
+      return outcome === 'goaway' ? 'retryNow' : 'retryWithDelay';
+    } catch (error) {
+      this.options.logger?.error(
+        'sse: EventSource 생성 실패 — baseUrl을 확인하세요',
+        error
+      );
+
+      this.#machine.transition('fatalFailure');
+      // 생성의 동기 throw는 설정 실수입니다 — 네트워크성 실패는 onerror로 와서 reconnecting으로 갑니다
+      this.emitter.emit(SDK_EVENTS.fatal, {
+        cause: 'config',
+      } satisfies FatalPayload);
+      return 'stop';
+    }
+  }
+
+  // EventSource를 생성하고 스트림이 끊길 때까지 대기합니다 — 이벤트 연결은 stream.ts, 여기서는 상태 전이만 담당합니다
+  #openStream(ticket: string, signal: AbortSignal): Promise<StreamOutcome> {
+    const EventSourceImpl = this.options.eventSource ?? globalThis.EventSource;
+    const source = new EventSourceImpl(
+      `${this.options.baseUrl}/v1/events?ticket=${encodeURIComponent(ticket)}`
+    );
+    this.#currentStream = { source, attachedEvents: new Set() };
+    this.emitter
+      .handlerTypes()
+      .forEach((type) => this.#attachSourceListener(type));
+
+    // hello 전 끊김(타임아웃 포함)만 미연결로 셉니다 — 수립 후 끊김은 다음 시도부터 다시 셉니다
+    let opened = false;
+
+    return streamUntilClosed(source, signal, {
+      helloTimeoutMs: HELLO_TIMEOUT_MS,
+      onHello: () => {
+        if (!this.#machine.transition('hello')) {
+          return false;
+        }
+
+        if (signal.aborted) {
+          return false;
+        }
+        opened = true;
+        this.#backoff.reset();
+        this.#networkFailures = 0;
+
+        // 갱신 전에 읽어야 이번 hello를 뺀 값입니다 — 두 번째부터가 재수립입니다
+        const isReestablished = this.#hasOpened;
+        this.#hasOpened = true;
+
+        if (isReestablished) {
+          this.emitter.emit(SDK_EVENTS.resync, undefined);
+        }
+        return true;
+      },
+
+      onClosed: (closure) => {
+        if (closure.outcome === 'error') {
+          this.#closeStream();
+          this.#machine.transition('retryableFailure');
+          if (!opened) {
+            this.#countNetworkFailure();
+          }
+          return;
+        }
+
+        // 서버가 재연결하지 말라고 했으면 reconnecting을 거치지 않습니다 — 소비처에 헛된 재연결 중을 보이지 않게
+        if (closure.outcome === 'goaway-close') {
+          this.#endSession();
+          this.#machine.transition('disconnect');
+        } else {
+          this.#closeStream();
+          this.#machine.transition('retryableFailure');
+        }
+
+        // 전이를 마친 뒤 알립니다 — 핸들러가 그 자리에서 connect()·disconnect()를 부를 수 있게
+        this.emitter.emit(SERVER_CONNECTION_EVENTS.goaway, closure.goaway);
+      },
+    });
+  }
+
+  #attachSourceListener(type: string): void {
+    if (this.#currentStream === null) {
+      return;
+    }
+    const { source, attachedEvents } = this.#currentStream;
+    attachDomainListener(source, attachedEvents, type, (t, payload) =>
+      this.emitter.emit(t, payload)
+    );
+  }
+
+  #closeStream(): void {
+    this.#currentStream?.source.close();
+    this.#currentStream = null;
+  }
+}

package/src/core/backoff.test.ts

@@ -0,0 +1,43 @@
+// @vitest-environment node
+import { describe, expect, it } from 'vitest';
+
+import { createBackoff } from './backoff';
+
+// random을 1로 고정하면 jitter 상한 = 계산된 지연 그대로
+const fixedRandom = () => 1;
+
+describe('createBackoff', () => {
+  it('시도마다 multiplier 배로 늘고 maxDelayMs에서 멈춥니다', () => {
+    const backoff = createBackoff(
+      { initialDelayMs: 1000, maxDelayMs: 4000, multiplier: 2 },
+      fixedRandom
+    );
+
+    expect(backoff.nextDelayMs()).toBe(1000);
+    expect(backoff.nextDelayMs()).toBe(2000);
+    expect(backoff.nextDelayMs()).toBe(4000);
+    expect(backoff.nextDelayMs()).toBe(4000);
+  });
+
+  it('full jitter — 지연은 [0, 계산값] 균등이라 random 비율이 그대로 곱해집니다', () => {
+    const backoff = createBackoff(
+      { initialDelayMs: 1000, maxDelayMs: 30_000, multiplier: 2 },
+      () => 0.5
+    );
+
+    expect(backoff.nextDelayMs()).toBe(500);
+    expect(backoff.nextDelayMs()).toBe(1000);
+  });
+
+  it('reset() 후에는 첫 지연부터 다시 시작합니다', () => {
+    const backoff = createBackoff(
+      { initialDelayMs: 1000, maxDelayMs: 30_000, multiplier: 2 },
+      fixedRandom
+    );
+
+    backoff.nextDelayMs();
+    backoff.nextDelayMs();
+    backoff.reset();
+    expect(backoff.nextDelayMs()).toBe(1000);
+  });
+});

package/src/core/backoff.ts

@@ -0,0 +1,39 @@
+export interface BackoffOptions {
+  initialDelayMs: number;
+  maxDelayMs: number;
+  multiplier: number;
+}
+
+const DEFAULT_BACKOFF: BackoffOptions = {
+  initialDelayMs: 1000,
+  maxDelayMs: 30_000,
+  multiplier: 2,
+};
+
+/** @description 지수 백오프 + full jitter — 동시 재연결 폭주(thundering herd)를 분산시킵니다 */
+export const createBackoff = (
+  options?: Partial<BackoffOptions>,
+  random: () => number = Math.random
+) => {
+  const initialDelayMs =
+    options?.initialDelayMs ?? DEFAULT_BACKOFF.initialDelayMs;
+  const maxDelayMs = options?.maxDelayMs ?? DEFAULT_BACKOFF.maxDelayMs;
+  const multiplier = options?.multiplier ?? DEFAULT_BACKOFF.multiplier;
+  let attempt = 0;
+
+  return {
+    nextDelayMs: (): number => {
+      const capped = Math.min(
+        maxDelayMs,
+        initialDelayMs * multiplier ** attempt
+      );
+      attempt += 1;
+      return random() * capped;
+    },
+    reset: (): void => {
+      attempt = 0;
+    },
+  };
+};
+
+export type Backoff = ReturnType<typeof createBackoff>;

package/src/core/emitter.ts

@@ -0,0 +1,56 @@
+import type {
+  SseEventHandler,
+  SseLogger,
+  SseStatus,
+  Unsubscribe,
+} from './types';
+
+/**
+ * @description SseClient·WorkerSseClient가 공유하는 구독·발행 코어.
+ * 리스너 예외를 격리합니다 — 하나가 던져도 나머지 리스너와 호출자의 정리 로직이 중단되지 않게.
+ */
+export const createEmitter = (logger?: SseLogger) => {
+  const handlers = new Map<string, Set<SseEventHandler<unknown>>>();
+  const statusListeners = new Set<(status: SseStatus) => void>();
+
+  const safeCall = <T>(listener: (value: T) => void, value: T): void => {
+    try {
+      listener(value);
+    } catch (error) {
+      logger?.warn('sse: 리스너 예외를 격리했습니다', error);
+    }
+  };
+
+  return {
+    on: (type: string, handler: SseEventHandler<unknown>): Unsubscribe => {
+      const set = handlers.get(type) ?? new Set();
+
+      set.add(handler);
+      handlers.set(type, set);
+
+      return () => {
+        set.delete(handler);
+      };
+    },
+
+    onStatus: (listener: (status: SseStatus) => void): Unsubscribe => {
+      statusListeners.add(listener);
+
+      return () => {
+        statusListeners.delete(listener);
+      };
+    },
+
+    emit: (type: string, payload: unknown): void => {
+      handlers.get(type)?.forEach((handler) => safeCall(handler, payload));
+    },
+
+    emitStatus: (status: SseStatus): void => {
+      statusListeners.forEach((listener) => safeCall(listener, status));
+    },
+
+    handlerTypes: (): string[] => [...handlers.keys()],
+  };
+};
+
+export type Emitter = ReturnType<typeof createEmitter>;