@remember-web/sse 0.1.0-alpha.1

package/src/testing/doubles.ts

@@ -0,0 +1,128 @@
+// 테스트 대역 모음 — 엔트리(index.ts)에서 참조하지 않으므로 빌드 산출물에 포함되지 않습니다.
+// 파일마다 대역을 복사하면 한쪽에만 메서드가 생겨 같은 상황이 계층마다 다르게 재현됩니다
+import type {
+  TabToWorkerMessage,
+  WorkerToTabMessage,
+} from '../worker/protocol';
+
+/** @description EventSource 대역 — 생성분을 정적으로 모아 마지막 인스턴스를 집어낼 수 있게 합니다 */
+export class FakeEventSource {
+  static readonly instances: FakeEventSource[] = [];
+
+  /** @description 테스트 간 격리 — 재할당 대신 비워, 앞서 넘긴 참조가 옛 배열을 보지 않게 합니다 */
+  static reset(): void {
+    FakeEventSource.instances.length = 0;
+  }
+
+  readonly listeners = new Map<
+    string,
+    Set<(event: { data?: string }) => void>
+  >();
+  onerror: ((event: unknown) => void) | null = null;
+  closed = false;
+
+  constructor(readonly url: string) {
+    FakeEventSource.instances.push(this);
+  }
+
+  addEventListener(
+    type: string,
+    listener: (event: { data?: string }) => void
+  ): void {
+    const set = this.listeners.get(type) ?? new Set();
+    set.add(listener);
+    this.listeners.set(type, set);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+
+  // 실제 EventSource는 close() 후 아무것도 배달하지 않습니다 — 하네스도 동일하게
+  dispatch(type: string, data?: string): void {
+    if (this.closed) {
+      return;
+    }
+    this.listeners.get(type)?.forEach((listener) => listener({ data }));
+  }
+
+  error(): void {
+    if (this.closed) {
+      return;
+    }
+    this.onerror?.({});
+  }
+}
+
+export const lastSource = (): FakeEventSource =>
+  FakeEventSource.instances.at(-1)!;
+
+/**
+ * @description 포트 대역 — 허브 쪽(HubPort)과 탭 쪽(MessagePort) 양쪽 표면을 함께 만족합니다.
+ * 한 포트의 양 끝을 한 객체로 보므로, 허브가 보낸 메시지는 sent에, 탭이 보낸 메시지는 posted에 쌓입니다.
+ */
+export class FakePort {
+  /** @description 허브가 이 포트로 보낸 것 */
+  sent: WorkerToTabMessage[] = [];
+  /** @description 탭 프록시가 이 포트로 보낸 것 */
+  posted: TabToWorkerMessage[] = [];
+  closeCount = 0;
+  started = false;
+  onmessage: ((event: { data: unknown }) => void) | null = null;
+
+  get closed(): boolean {
+    return this.closeCount > 0;
+  }
+
+  // 실제 MessagePort는 close 후에도 던지지 않고 조용히 버립니다 — 던지면 그 실패 경로가 예외로 위장됩니다
+  postMessage(message: WorkerToTabMessage | TabToWorkerMessage): void {
+    if (this.closed) {
+      return;
+    }
+
+    if (isWorkerToTab(message)) {
+      this.sent.push(message);
+      return;
+    }
+    this.posted.push(message);
+  }
+
+  start(): void {
+    this.started = true;
+  }
+
+  close(): void {
+    this.closeCount += 1;
+  }
+
+  /** @description 워커가 탭에 보낸 것처럼 프록시의 onmessage를 깨웁니다 */
+  deliver(message: WorkerToTabMessage): void {
+    this.onmessage?.({ data: message });
+  }
+}
+
+// 두 방향 유니온에 겹치는 kind가 없어 kind만으로 방향이 갈립니다
+const WORKER_TO_TAB_KINDS: Record<WorkerToTabMessage['kind'], true> = {
+  event: true,
+  status: true,
+  ping: true,
+  'ticket-request': true,
+};
+
+const isWorkerToTab = (
+  message: WorkerToTabMessage | TabToWorkerMessage
+): message is WorkerToTabMessage => message.kind in WORKER_TO_TAB_KINDS;
+
+export const kindsOf = <K extends WorkerToTabMessage['kind']>(
+  port: FakePort,
+  kind: K
+): Extract<WorkerToTabMessage, { kind: K }>[] =>
+  port.sent.filter(
+    (message): message is Extract<WorkerToTabMessage, { kind: K }> =>
+      message.kind === kind
+  );
+
+/** @description SharedWorker 대역 — 팩토리가 넘겨받는 표면은 port 하나뿐입니다 */
+export class FakeSharedWorker {
+  readonly port = new FakePort();
+}

package/src/testing/harness.ts

@@ -0,0 +1,82 @@
+// 테스트 전용 하네스 — 엔트리(index.ts)에서 참조하지 않으므로 빌드 산출물에 포함되지 않습니다
+import { beforeEach, vi } from 'vitest';
+
+import { FakeEventSource } from './doubles';
+
+import { SseClient } from '../core/SseClient';
+import type { SseClientOptions } from '../core/types';
+
+export interface TestEventMap {
+  'demo.created': { id: string };
+}
+
+export const createFetchMock = () => {
+  const requests: { url: string; method?: string; authorization?: string }[] =
+    [];
+  let ticketFailureStatus: number | null = null;
+  let ticketCounter = 0;
+
+  const fetchMock = async (input: unknown, init?: RequestInit) => {
+    const headers = (init?.headers ?? {}) as Record<string, string>;
+    requests.push({
+      url: String(input),
+      method: init?.method,
+      authorization: headers.Authorization,
+    });
+
+    if (init?.method === 'POST') {
+      if (ticketFailureStatus !== null) {
+        return { ok: false, status: ticketFailureStatus } as Response;
+      }
+      ticketCounter += 1;
+      const ticket = `ticket-${ticketCounter}`;
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ data: { ticket } }),
+      } as unknown as Response;
+    }
+
+    return { ok: true, status: 204 } as Response;
+  };
+
+  return {
+    fetch: fetchMock as unknown as typeof globalThis.fetch,
+    requests,
+    ticketRequests: () =>
+      requests.filter((request) => request.method === 'POST'),
+    failTicketsWith: (status: number | null) => {
+      ticketFailureStatus = status;
+    },
+  };
+};
+
+export const createHarness = (overrides?: Partial<SseClientOptions>) => {
+  const fetchMock = createFetchMock();
+  const client = new SseClient<TestEventMap>({
+    baseUrl: 'https://sse.example.com',
+    getAuthToken: () => 'token-1',
+    fetch: fetchMock.fetch,
+    eventSource: FakeEventSource as unknown as typeof EventSource,
+    ...overrides,
+  });
+  return { client, ...fetchMock };
+};
+
+/**
+ * @description 재연결 시점을 결정적으로 만드는 준비 — 정리는 vitest.setup.ts가 전역으로 합니다.
+ * 백오프를 기다리는 테스트 파일만 켜세요. React 테스트처럼 실제 타이머가 필요한 곳은 켜지 않습니다.
+ */
+export const setupFakeTimers = (): void => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    // 무작위 재시도 지연(full jitter)을 최대값으로 고정해 재시도 시점을 예측 가능하게 만듭니다
+    vi.spyOn(Math, 'random').mockReturnValue(1);
+  });
+};
+
+export const openConnection = async (client: SseClient<TestEventMap>) => {
+  client.connect();
+  await vi.advanceTimersByTimeAsync(0);
+  FakeEventSource.instances.at(-1)!.dispatch('hello');
+};

package/src/testing/index.ts

@@ -0,0 +1,3 @@
+// 테스트 대역·하네스의 단일 진입 — 대역이 필요한 테스트는 여기서만 가져옵니다
+export * from './doubles';
+export * from './harness';

package/src/worker/SseClientLike.contract.test.ts

@@ -0,0 +1,270 @@
+// @vitest-environment node
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { WorkerSseClient } from './WorkerSseClient';
+
+import { SseClient } from '../core/SseClient';
+import type { SseClientLike, SseClientOptions } from '../core/types';
+import {
+  createFetchMock,
+  FakeEventSource,
+  FakePort,
+  lastSource,
+  setupFakeTimers,
+  type TestEventMap,
+} from '../testing';
+
+type ExtraOptions = Partial<Omit<SseClientOptions, 'eventSource'>>;
+
+/**
+ * @description 구현마다 다른 "연결을 여는 방법"과 "이벤트를 흘려보내는 방법".
+ * 계약 본문은 이 훅으로만 구현에 닿습니다 — 스텁 종류(EventSource·포트)를 알지 못합니다.
+ */
+interface ContractDriver {
+  createClient(extra?: ExtraOptions): SseClientLike<TestEventMap>;
+  /** @description hello까지 도달시켜 status가 open이 되게 합니다 */
+  open(client: SseClientLike<TestEventMap>): Promise<void>;
+  /** @description 열린 연결로 도메인 이벤트 하나를 배달합니다 */
+  deliver(event: string, payload: unknown): void;
+  /** @description 재수립 — 끊고 다시 hello까지 도달시킵니다 */
+  reopen(client: SseClientLike<TestEventMap>): Promise<void>;
+}
+
+const testSseClientContract = (driver: ContractDriver): void => {
+  const createClient = driver.createClient;
+
+  it('브라우저 전역이 없는 환경에서 connect가 던지지 않습니다', () => {
+    const client = createClient();
+    expect(() => client.connect()).not.toThrow();
+  });
+
+  it('연결 전 구독이 해제 함수를 반환합니다', () => {
+    const client = createClient();
+    const unsubscribe = client.on('demo.created', () => {});
+    expect(typeof unsubscribe).toBe('function');
+    unsubscribe();
+  });
+
+  it('disconnect는 closed로 전이하고, 던지는 리스너가 있어도 나머지 리스너에 통지합니다', () => {
+    const client = createClient();
+    const received: string[] = [];
+    client.onStatus(() => {
+      throw new Error('listener boom');
+    });
+    client.onStatus((status) => {
+      received.push(status);
+    });
+
+    expect(() => client.disconnect()).not.toThrow();
+
+    expect(received).toEqual(['closed']);
+    expect(client.status).toBe('closed');
+  });
+
+  it("SDK가 소비하는 'hello' 구독에는 배달되지 않는다고 logger.warn을 냅니다", () => {
+    const warnings: string[] = [];
+    const client = createClient({
+      logger: { warn: (message) => warnings.push(message), error: () => {} },
+    });
+
+    client.on('hello', () => {});
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("'hello'");
+  });
+
+  it('격리한 리스너 예외를 logger.warn으로 보고합니다', () => {
+    const warnings: string[] = [];
+    const client = createClient({
+      logger: { warn: (message) => warnings.push(message), error: () => {} },
+    });
+    client.onStatus(() => {
+      throw new Error('listener boom');
+    });
+
+    client.disconnect();
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('리스너 예외');
+  });
+
+  it('connect부터 수립까지 connecting → open을 통지합니다', async () => {
+    const client = createClient();
+    const seen: string[] = [];
+    client.onStatus((status) => seen.push(status));
+
+    await driver.open(client);
+
+    expect(seen).toEqual(['connecting', 'open']);
+    expect(client.status).toBe('open');
+  });
+
+  it('구독한 도메인 이벤트의 페이로드를 배달합니다', async () => {
+    const client = createClient();
+    const received: unknown[] = [];
+    client.on('demo.created', (payload) => received.push(payload));
+
+    await driver.open(client);
+    driver.deliver('demo.created', { id: 'a' });
+
+    expect(received).toEqual([{ id: 'a' }]);
+  });
+
+  it('해제한 뒤에는 배달하지 않습니다', async () => {
+    const client = createClient();
+    const received: unknown[] = [];
+    const unsubscribe = client.on('demo.created', (payload) =>
+      received.push(payload)
+    );
+
+    await driver.open(client);
+    unsubscribe();
+    driver.deliver('demo.created', { id: 'a' });
+
+    expect(received).toEqual([]);
+  });
+
+  it('구독하지 않은 이벤트는 배달하지 않습니다', async () => {
+    const client = createClient();
+    const received: unknown[] = [];
+    client.on('demo.created', (payload) => received.push(payload));
+
+    await driver.open(client);
+    driver.deliver('other.event', { id: 'a' });
+
+    expect(received).toEqual([]);
+  });
+
+  it('재수립하면 resync를 발화합니다 — 첫 수립에는 발화하지 않습니다', async () => {
+    const client = createClient();
+    let resyncCount = 0;
+    client.on('resync', () => {
+      resyncCount += 1;
+    });
+
+    await driver.open(client);
+    expect(resyncCount).toBe(0);
+
+    await driver.reopen(client);
+    expect(resyncCount).toBe(1);
+  });
+
+  it('disconnect를 두 번 불러도 closed 통지는 한 번뿐입니다', async () => {
+    const client = createClient();
+    await driver.open(client);
+
+    const seen: string[] = [];
+    client.onStatus((status) => seen.push(status));
+    client.disconnect();
+    client.disconnect();
+
+    expect(seen).toEqual(['closed']);
+    expect(client.status).toBe('closed');
+  });
+
+  it('열린 뒤 connect를 다시 불러도 상태가 흔들리지 않습니다', async () => {
+    const client = createClient();
+    await driver.open(client);
+
+    const seen: string[] = [];
+    client.onStatus((status) => seen.push(status));
+    client.connect();
+
+    expect(seen).toEqual([]);
+    expect(client.status).toBe('open');
+  });
+
+  it('disconnect 뒤 다시 connect하면 열립니다', async () => {
+    const client = createClient();
+    await driver.open(client);
+    client.disconnect();
+
+    await driver.open(client);
+
+    expect(client.status).toBe('open');
+  });
+};
+
+const options = {
+  baseUrl: 'https://sse.example.com',
+  getAuthToken: () => 'token',
+};
+
+describe('SseClient — SseClientLike 계약', () => {
+  setupFakeTimers();
+
+  let fetchMock: ReturnType<typeof createFetchMock>;
+  beforeEach(() => {
+    fetchMock = createFetchMock();
+  });
+
+  const openDirect = async (client: SseClientLike<TestEventMap>) => {
+    client.connect();
+    await vi.advanceTimersByTimeAsync(0);
+    lastSource().dispatch('hello');
+  };
+
+  testSseClientContract({
+    createClient: (extra) =>
+      new SseClient<TestEventMap>({
+        ...options,
+        fetch: fetchMock.fetch,
+        eventSource: FakeEventSource as unknown as typeof EventSource,
+        ...extra,
+      }),
+    open: openDirect,
+    deliver: (event, payload) =>
+      lastSource().dispatch(event, JSON.stringify(payload)),
+    reopen: async () => {
+      // onerror가 재연결 루프를 돌리고, 첫 백오프가 흐른 뒤 새 소스가 hello를 받습니다
+      lastSource().error();
+      await vi.advanceTimersByTimeAsync(1000);
+      lastSource().dispatch('hello');
+    },
+  });
+});
+
+describe('WorkerSseClient — SseClientLike 계약', () => {
+  setupFakeTimers();
+
+  let ports: FakePort[] = [];
+  beforeEach(() => {
+    ports = [];
+  });
+
+  const lastPort = () => ports.at(-1)!;
+
+  // 워커가 세우는 연결을 대신합니다 — 프록시 입장에서 수립은 워커의 status 통지가 전부입니다
+  const openViaWorker = async (client: SseClientLike<TestEventMap>) => {
+    client.connect();
+    lastPort().deliver({ kind: 'status', status: 'connecting' });
+    lastPort().deliver({ kind: 'status', status: 'open' });
+  };
+
+  testSseClientContract({
+    createClient: (extra) =>
+      new WorkerSseClient<TestEventMap>({
+        ...options,
+        sharedWorker: () => {
+          const port = new FakePort();
+          ports.push(port);
+          return { port } as unknown as SharedWorker;
+        },
+        ...extra,
+      }),
+    open: openViaWorker,
+    deliver: (event, payload) =>
+      lastPort().deliver({ kind: 'event', event, payload }),
+    // 워커가 재수립 때 실제로 보내는 순서입니다 — resync 전달은 hub.connection.test.ts가 검증합니다
+    reopen: async () => {
+      lastPort().deliver({ kind: 'status', status: 'reconnecting' });
+      lastPort().deliver({ kind: 'status', status: 'connecting' });
+      lastPort().deliver({ kind: 'status', status: 'open' });
+      lastPort().deliver({
+        kind: 'event',
+        event: 'resync',
+        payload: undefined,
+      });
+    },
+  });
+});

package/src/worker/WorkerSseClient.scenarios.test.ts

@@ -0,0 +1,179 @@
+// @vitest-environment node
+import { describe, expect, it, vi } from 'vitest';
+
+import { createWorkerHub, PING_INTERVAL_MS } from './hub';
+import { WorkerSseClient } from './WorkerSseClient';
+
+import {
+  FakeEventSource,
+  FakePort as FakeTabPort,
+  lastSource,
+  setupFakeTimers,
+  type TestEventMap,
+} from '../testing';
+
+/**
+ * 유저 여정 시나리오(워커 경로) — 기계 계약은 hub.test.ts·hub.connection.test.ts·WorkerSseClient.test.ts가
+ * 고정하고, 이 파일은 소비처가 겪는 경험 하나를 탭에서 서버까지 걷습니다.
+ * 그 파일들은 허브를 직접 부르므로 "그 메시지를 누가 보내는가"를 검증하지 못합니다 — 여기서만 잡힙니다.
+ */
+
+setupFakeTimers();
+
+/** @description 탭 프록시와 허브를 실제 배선대로 이어 붙입니다 — sse.worker.ts가 하는 일과 같습니다 */
+const connectTab = (hub: ReturnType<typeof createWorkerHub>) => {
+  const port = new FakeTabPort();
+  const client = new WorkerSseClient<TestEventMap>({
+    baseUrl: 'https://sse.example.com',
+    getAuthToken: () => 'token-1',
+    fetch: (async (_input: unknown, init?: RequestInit) =>
+      init?.method === 'POST'
+        ? ({
+            ok: true,
+            status: 200,
+            json: async () => ({ data: { ticket: 'ticket' } }),
+          } as unknown as Response)
+        : ({ ok: true, status: 204 } as Response)) as unknown as typeof fetch,
+    sharedWorker: () => ({ port }) as unknown as SharedWorker,
+  });
+
+  // 실제로는 MessagePort가 하는 일 — 얼어붙은 탭을 흉내내려면 배달을 멈출 수 있어야 합니다
+  let frozen = false;
+  let deliveredToTab = 0;
+
+  // 한 번 배달하면 상대가 답을 보내므로, 더 오갈 게 없을 때까지 왕복시킵니다
+  const deliverMessages = async (): Promise<void> => {
+    for (let round = 0; round < 10; round += 1) {
+      const toWorker = port.posted.splice(0);
+      toWorker.forEach((message) => hub.handleMessage(port, message));
+
+      // 얼어붙은 탭은 받지 못하고 큐에 쌓입니다 — 깨어나면 그 자리부터 이어 배달됩니다
+      const toTab = frozen ? [] : port.sent.slice(deliveredToTab);
+      deliveredToTab += toTab.length;
+      toTab.forEach((message) => port.deliver(message));
+
+      await vi.advanceTimersByTimeAsync(0);
+      if (toWorker.length === 0 && toTab.length === 0) {
+        return;
+      }
+    }
+  };
+
+  hub.addPort(port);
+  return {
+    client,
+    port,
+    deliverMessages,
+    freezeTab: () => {
+      frozen = true;
+    },
+    wakeTab: () => {
+      frozen = false;
+    },
+  };
+};
+
+const createHub = () =>
+  createWorkerHub({
+    eventSource: FakeEventSource as unknown as typeof EventSource,
+    logger: { warn: () => {}, error: () => {} },
+    fetch: (async () =>
+      ({ ok: true, status: 204 }) as Response) as unknown as typeof fetch,
+  });
+
+describe('유저 시나리오 — 워커 경로', () => {
+  it('탭이 얼어붙은 사이의 이벤트도, 깨어나면 밀렸던 배달로 전부 도착한다', async () => {
+    const hub = createHub();
+    const { client, deliverMessages, freezeTab, wakeTab } = connectTab(hub);
+
+    const received: unknown[] = [];
+    client.on('demo.created', (payload) => received.push(payload));
+
+    client.connect();
+    await deliverMessages();
+    lastSource().dispatch('hello');
+    await deliverMessages();
+    expect(client.status).toBe('open');
+
+    // 얼어붙음 — 두 주기가 지나도 장부에 남고, 이벤트는 큐에 쌓입니다
+    freezeTab();
+    await vi.advanceTimersByTimeAsync(PING_INTERVAL_MS);
+    await vi.advanceTimersByTimeAsync(PING_INTERVAL_MS);
+    lastSource().dispatch('demo.created', '{"id":"missed-1"}');
+    lastSource().dispatch('demo.created', '{"id":"missed-2"}');
+    expect(received).toEqual([]);
+
+    wakeTab();
+    await deliverMessages();
+
+    expect(received).toEqual([{ id: 'missed-1' }, { id: 'missed-2' }]);
+    expect(client.status).toBe('open');
+  });
+
+  it('전원이 얼어붙어 연결이 끊겨도, 깨어난 탭의 connect가 다시 세우고 resync를 받는다', async () => {
+    const hub = createHub();
+    const { client, deliverMessages, freezeTab, wakeTab } = connectTab(hub);
+
+    const events: string[] = [];
+    client.on('resync', () => events.push('resync'));
+
+    client.connect();
+    await deliverMessages();
+    lastSource().dispatch('hello');
+    await deliverMessages();
+    expect(client.status).toBe('open');
+
+    // 유일한 탭이 얼어붙어 확정 침묵이 됩니다
+    freezeTab();
+    await vi.advanceTimersByTimeAsync(PING_INTERVAL_MS);
+    await vi.advanceTimersByTimeAsync(PING_INTERVAL_MS);
+
+    // 그 사이 연결이 끊깁니다 — 티켓을 물을 곳이 없어 워커가 휴면으로 접습니다
+    lastSource().error();
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(FakeEventSource.instances).toHaveLength(1);
+
+    // 깨어남 — 소비처가 이 시점에 connect()를 부릅니다(attachAutoResume이 하는 일)
+    wakeTab();
+    client.connect();
+    await deliverMessages();
+
+    // 전제를 먼저 단언합니다 — 조건부로 두면 재수립 실패가 아래 resync 단언으로 흘러 원인이 흐려집니다
+    expect(FakeEventSource.instances.length).toBeGreaterThan(1);
+    lastSource().dispatch('hello');
+    await deliverMessages();
+
+    expect(client.status).toBe('open');
+    // 휴면 동안의 공백을 소비처가 메울 수 있어야 합니다 — 세션이 이어진 재수립이라 resync가 옵니다
+    expect(events).toEqual(['resync']);
+  });
+
+  // connect()는 탭이 깨어날 때마다 불립니다(attachAutoResume) — 탭 전환마다 재조회가 나가면 안 됩니다
+  it('연결이 살아 있는 동안의 connect 반복은 재수립도 resync도 만들지 않는다', async () => {
+    const hub = createHub();
+    const { client, deliverMessages, freezeTab, wakeTab } = connectTab(hub);
+
+    const events: string[] = [];
+    client.on('resync', () => events.push('resync'));
+
+    client.connect();
+    await deliverMessages();
+    lastSource().dispatch('hello');
+    await deliverMessages();
+
+    freezeTab();
+    await vi.advanceTimersByTimeAsync(PING_INTERVAL_MS);
+    await vi.advanceTimersByTimeAsync(PING_INTERVAL_MS);
+
+    // 연결은 살아 있습니다 — 깨어난 탭의 connect는 아무것도 다시 세울 필요가 없습니다
+    wakeTab();
+    client.connect();
+    client.connect();
+    client.connect();
+    await deliverMessages();
+
+    expect(FakeEventSource.instances).toHaveLength(1);
+    expect(events).toEqual([]);
+    expect(client.status).toBe('open');
+  });
+});