@remember-web/sse 0.1.0-alpha.1

package/src/worker/hub.test.ts

@@ -0,0 +1,213 @@
+// @vitest-environment node
+import { describe, expect, it, vi } from 'vitest';
+
+import { createWorkerHub, PING_INTERVAL_MS } from './hub';
+
+import { FakePort as FakeTabPort, kindsOf, setupFakeTimers } from '../testing';
+
+setupFakeTimers();
+
+describe('워커 허브 — 포트 장부', () => {
+  it('새 포트가 등록되면 현재 상태를 즉시 알려줍니다', () => {
+    const hub = createWorkerHub();
+    const port = new FakeTabPort();
+
+    hub.addPort(port);
+
+    expect(port.sent).toEqual([{ kind: 'status', status: 'idle' }]);
+    expect(hub.tabCount()).toBe(1);
+  });
+
+  it('broadcast는 등록된 모든 포트에 전달됩니다', () => {
+    const hub = createWorkerHub();
+    const first = new FakeTabPort();
+    const second = new FakeTabPort();
+    hub.addPort(first);
+    hub.addPort(second);
+
+    hub.broadcast({
+      kind: 'event',
+      event: 'demo.created',
+      payload: { id: 'a' },
+    });
+
+    expect(first.sent.at(-1)).toEqual({
+      kind: 'event',
+      event: 'demo.created',
+      payload: { id: 'a' },
+    });
+    expect(second.sent.at(-1)).toEqual(first.sent.at(-1));
+  });
+
+  it('close 메시지를 보낸 포트는 장부에서 빠지고 이후 broadcast를 받지 않습니다', () => {
+    const hub = createWorkerHub();
+    const leaving = new FakeTabPort();
+    const staying = new FakeTabPort();
+    hub.addPort(leaving);
+    hub.addPort(staying);
+
+    hub.handleMessage(leaving, { kind: 'close' });
+    hub.broadcast({ kind: 'ping' });
+
+    expect(hub.tabCount()).toBe(1);
+    expect(leaving.closed).toBe(true);
+    expect(leaving.sent.some((m) => m.kind === 'ping')).toBe(false);
+    expect(staying.sent.at(-1)).toEqual({ kind: 'ping' });
+  });
+});
+
+// 무응답 판정은 portRegistry가 소유하지만, 탭이 겪는 건 허브를 거친 결과라 여기서 고정합니다
+describe('워커 허브 — 생존 확인', () => {
+  const pingsOf = (port: FakeTabPort) => kindsOf(port, 'ping');
+
+  it('주기가 되면 모든 포트에 ping을 보냅니다', () => {
+    const hub = createWorkerHub();
+    const first = new FakeTabPort();
+    const second = new FakeTabPort();
+    hub.addPort(first);
+    hub.addPort(second);
+
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+
+    expect(pingsOf(first)).toHaveLength(1);
+    expect(pingsOf(second)).toHaveLength(1);
+  });
+
+  // 빼는 순간부터가 그 탭이 놓치는 구간입니다
+  it('무응답 포트도 장부에 남아 broadcast를 계속 받습니다', () => {
+    const hub = createWorkerHub();
+    const frozen = new FakeTabPort();
+    hub.addPort(frozen);
+
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+
+    hub.broadcast({ kind: 'event', event: 'demo.created', payload: undefined });
+
+    expect(hub.tabCount()).toBe(1);
+    expect(frozen.closed).toBe(false);
+    expect(frozen.sent.at(-1)).toEqual({
+      kind: 'event',
+      event: 'demo.created',
+      payload: undefined,
+    });
+  });
+
+  it('무응답 포트도 계속 ping을 받습니다 — 깨어나 pong하면 그 자리에서 복귀합니다', () => {
+    const hub = createWorkerHub();
+    const frozen = new FakeTabPort();
+    hub.addPort(frozen);
+
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+
+    expect(pingsOf(frozen)).toHaveLength(3);
+  });
+
+  it('떠난 포트의 늦은 메시지는 무시합니다 — 닫힌 핸들을 대신해 아무것도 하지 않습니다', () => {
+    const hub = createWorkerHub();
+    const leaving = new FakeTabPort();
+    const staying = new FakeTabPort();
+    hub.addPort(leaving);
+    hub.addPort(staying);
+
+    hub.handleMessage(leaving, { kind: 'close' });
+    hub.handleMessage(leaving, { kind: 'pong' });
+    hub.handleMessage(leaving, {
+      kind: 'init',
+      baseUrl: 'https://sse.example.com',
+    });
+
+    expect(hub.tabCount()).toBe(1);
+    expect(hub.subscribedEvents()).toEqual([]);
+  });
+});
+
+describe('워커 허브 — 메시지 라우팅', () => {
+  it('subscribe는 이벤트 이름을 중복 없이 모읍니다', () => {
+    const hub = createWorkerHub();
+    const port = new FakeTabPort();
+    hub.addPort(port);
+
+    hub.handleMessage(port, { kind: 'subscribe', event: 'demo.created' });
+    hub.handleMessage(port, { kind: 'subscribe', event: 'demo.created' });
+    hub.handleMessage(port, { kind: 'subscribe', event: 'demo.updated' });
+
+    expect(hub.subscribedEvents().sort()).toEqual([
+      'demo.created',
+      'demo.updated',
+    ]);
+  });
+
+  it("SDK 예약 이벤트('hello')와 'resync' 구독 요청은 장부에 넣지 않습니다", () => {
+    const hub = createWorkerHub();
+    const port = new FakeTabPort();
+    hub.addPort(port);
+
+    hub.handleMessage(port, { kind: 'subscribe', event: 'hello' });
+    hub.handleMessage(port, { kind: 'subscribe', event: 'resync' });
+    hub.handleMessage(port, { kind: 'subscribe', event: 'demo.created' });
+
+    expect(hub.subscribedEvents()).toEqual(['demo.created']);
+  });
+
+  it('event가 문자열이 아닌 subscribe는 장부에 넣지 않습니다', () => {
+    const hub = createWorkerHub();
+    const port = new FakeTabPort();
+    hub.addPort(port);
+
+    hub.handleMessage(port, { kind: 'subscribe' });
+    hub.handleMessage(port, { kind: 'subscribe', event: 42 });
+
+    expect(hub.subscribedEvents()).toEqual([]);
+  });
+
+  it('형식이 어긋난 ticket-response는 위임에 넘기지 않습니다 — 연결 루프가 예외로 죽지 않게', () => {
+    const hub = createWorkerHub();
+    const port = new FakeTabPort();
+    hub.addPort(port);
+
+    expect(() =>
+      hub.handleMessage(port, {
+        kind: 'ticket-response',
+        ok: false,
+        error: null,
+      })
+    ).not.toThrow();
+    expect(() =>
+      hub.handleMessage(port, { kind: 'ticket-response', ok: true, ticket: 42 })
+    ).not.toThrow();
+    expect(() =>
+      hub.handleMessage(port, { kind: 'ticket-response', ok: false })
+    ).not.toThrow();
+    expect(() =>
+      hub.handleMessage(port, {
+        kind: 'ticket-response',
+        ok: false,
+        error: [],
+      })
+    ).not.toThrow();
+    // status는 fatal 판정에 쓰이므로 문자열이면 재시도 대상으로도 넘기지 않습니다
+    expect(() =>
+      hub.handleMessage(port, {
+        kind: 'ticket-response',
+        ok: false,
+        error: { status: '401' },
+      })
+    ).not.toThrow();
+  });
+
+  it('모르는 kind의 메시지는 무시합니다 — 신·구 코드가 섞인 배포 중에도 안전합니다', () => {
+    const hub = createWorkerHub();
+    const port = new FakeTabPort();
+    hub.addPort(port);
+
+    expect(() =>
+      hub.handleMessage(port, { kind: 'future-thing' })
+    ).not.toThrow();
+    expect(() => hub.handleMessage(port, null)).not.toThrow();
+    expect(hub.tabCount()).toBe(1);
+  });
+});

package/src/worker/hub.ts

@@ -0,0 +1,120 @@
+import type { HubPort } from './portRegistry';
+import { createPortRegistry } from './portRegistry';
+import type {
+  Incoming,
+  TabToWorkerMessage,
+  WorkerToTabMessage,
+} from './protocol';
+import { isTicketResponse } from './protocol';
+import { createTicketDelegate } from './ticketDelegate';
+import type { WorkerConnectionOptions } from './workerConnection';
+import { createWorkerConnection } from './workerConnection';
+
+import { isSubscribableEvent } from '../core/eventNames';
+import type { SseStatus } from '../core/types';
+
+export { PING_INTERVAL_MS } from './portRegistry';
+export type { HubPort } from './portRegistry';
+
+/**
+ * @description SharedWorker 쪽 메시지 라우팅 — 탭이 보낸 것을 연결에 전하고, 연결이 낸 것을 탭에 전합니다.
+ * 포트 장부(frozen 탭을 빼지 않는 이유 포함)는 portRegistry가, 연결 수립·정리는 workerConnection이 소유합니다.
+ * 배선 현황은 protocol.ts의 지도를 보세요.
+ */
+export const createWorkerHub = (hubOptions: WorkerConnectionOptions = {}) => {
+  // 늦게 합류한 탭에 스냅샷으로 보냅니다 — 저장과 통지가 어긋나지 않게 setStatus로만 바꿉니다
+  let status: SseStatus = 'idle';
+
+  const registry = createPortRegistry();
+
+  const broadcast = (message: WorkerToTabMessage): void => {
+    registry.forEach((port) => port.postMessage(message));
+  };
+
+  const setStatus = (next: SseStatus): void => {
+    status = next;
+    broadcast({ kind: 'status', status: next });
+  };
+
+  const ticketDelegate = createTicketDelegate(() => {
+    const target = registry.livelyPort();
+    if (target !== undefined) {
+      target.postMessage({ kind: 'ticket-request' });
+      return;
+    }
+    // 전원이 침묵하면 접습니다 — 세션 종료가 아니라 휴면이라, 재수립 판정은 그대로 둡니다.
+    // microtask인 이유: 이 콜백은 연결 루프의 티켓 발급 스택 안이라, 동기로 접으면 그 루프를 재진입으로 끊습니다
+    queueMicrotask(() => connection.close());
+  });
+
+  const connection = createWorkerConnection({
+    options: hubOptions,
+    ticketDelegate,
+    onStatus: setStatus,
+    onEvent: (event, payload) => broadcast({ kind: 'event', event, payload }),
+  });
+
+  return {
+    addPort: (port: HubPort): void => {
+      registry.add(port);
+      port.postMessage({ kind: 'status', status });
+    },
+
+    handleMessage: (port: HubPort, data: unknown): void => {
+      // close로 떠난 포트의 늦은 메시지만 거릅니다 — frozen 탭은 장부에 남아 그대로 지나갑니다
+      if (!registry.has(port)) {
+        return;
+      }
+
+      // 어떤 메시지든 생존 증거입니다 — pong만 세면 깨어나 init부터 보낸 탭이 침묵으로 남아 티켓을 못 받습니다
+      registry.markAlive(port);
+
+      const message = data as Incoming<TabToWorkerMessage> | null;
+      switch (message?.kind) {
+        case 'init':
+          // 휴면(전원 침묵)으로 접힌 연결은 깨어난 탭의 이 신호로 다시 섭니다
+          if (typeof message.baseUrl === 'string') {
+            connection.ensureOpen(message.baseUrl);
+          }
+          return;
+        case 'subscribe':
+          // 예약 이벤트·비문자열은 프록시가 걸러 보내지만, 구버전·타 구현 탭에 대비해 한 번 더 거릅니다
+          if (
+            typeof message.event === 'string' &&
+            isSubscribableEvent(message.event)
+          ) {
+            connection.subscribe(message.event);
+          }
+          return;
+        case 'ticket-response':
+          // 여기서 거르지 않으면 잘못된 응답이 연결 루프를 예외로 죽여 워커가 고착됩니다
+          if (isTicketResponse(message)) {
+            ticketDelegate.settle(message);
+          }
+          return;
+        case 'pong':
+          // 생존 표시는 위에서 이미 끝났습니다 — pong은 그 증거만 나르는 메시지입니다
+          return;
+        case 'close': {
+          const { wasLast } = registry.close(port);
+          // 모두 스스로 떠났으니 세션이 끝났습니다 — 다음 탭에게는 첫 연결입니다
+          if (wasLast) {
+            connection.close({ endSession: true });
+          }
+          return;
+        }
+        default:
+          // 여기 도달하는 건 미지 kind(신·구 코드가 섞인 배포)뿐이라 무시합니다
+          message satisfies null;
+          return;
+      }
+    },
+
+    broadcast,
+
+    tabCount: registry.size,
+    subscribedEvents: connection.subscribedEvents,
+  };
+};
+
+export type WorkerHub = ReturnType<typeof createWorkerHub>;

package/src/worker/portRegistry.test.ts

@@ -0,0 +1,59 @@
+// @vitest-environment node
+import { describe, expect, it, vi } from 'vitest';
+
+import { createPortRegistry, PING_INTERVAL_MS } from './portRegistry';
+
+import { FakePort, setupFakeTimers } from '../testing';
+
+setupFakeTimers();
+
+// sendPings 세 줄의 순서가 규칙 전부입니다 — 승격이 재무장보다 먼저여야 "한 주기 유예"가 성립합니다
+describe('portRegistry — 침묵 판정', () => {
+  it('ping 직후에는 아무도 침묵으로 판정하지 않습니다 — 전원이 응답 대기일 뿐입니다', () => {
+    const registry = createPortRegistry();
+    const port = new FakePort();
+    registry.add(port);
+
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+
+    expect(registry.livelyPort()).toBe(port);
+  });
+
+  it('한 주기를 통째로 놓치면 침묵으로 판정합니다', () => {
+    const registry = createPortRegistry();
+    const port = new FakePort();
+    registry.add(port);
+
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+
+    expect(registry.livelyPort()).toBeUndefined();
+  });
+
+  it('침묵하던 포트도 markAlive면 그 자리에서 되돌아옵니다', () => {
+    const registry = createPortRegistry();
+    const port = new FakePort();
+    registry.add(port);
+
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+    expect(registry.livelyPort()).toBeUndefined();
+
+    registry.markAlive(port);
+
+    expect(registry.livelyPort()).toBe(port);
+  });
+
+  it('이번 주기에 답한 포트를 판정 전 포트보다 먼저 고릅니다', () => {
+    const registry = createPortRegistry();
+    const awaiting = new FakePort();
+    const answered = new FakePort();
+    registry.add(awaiting);
+    registry.add(answered);
+
+    vi.advanceTimersByTime(PING_INTERVAL_MS);
+    registry.markAlive(answered);
+
+    expect(registry.livelyPort()).toBe(answered);
+  });
+});

package/src/worker/portRegistry.ts

@@ -0,0 +1,86 @@
+import type { WorkerToTabMessage } from './protocol';
+
+/** @description 장부가 포트에 요구하는 최소 표면 — 실제 MessagePort와 테스트 대역이 함께 만족합니다 */
+export interface HubPort {
+  postMessage(message: WorkerToTabMessage): void;
+  close(): void;
+}
+
+// 15초는 소비자 요구가 아직 없는 임의 기본값입니다 — 티켓 대상 판별의 지연 허용치가 정해지면 조정합니다
+export const PING_INTERVAL_MS = 15_000;
+
+/**
+ * @description 탭 포트의 장부 — 등록·떠남과 ping 주기를 소유합니다.
+ *
+ * 무응답 포트를 장부에서 빼지 않습니다: frozen 탭의 메시지는 브라우저가 큐잉했다가
+ * 깨어날 때 전부 배달하므로, 계속 보내는 것이 곧 공백 없는 복구입니다 —
+ * 빼는 순간부터가 그 탭이 놓치는 구간이 됩니다.
+ * close 없이 사라진 탭(크래시·창 닫기)의 포트는 장부에 남지만 무해합니다 — 전송은 조용히
+ * 버려지고, 상한은 워커 생존 중 닫힌 탭 수이며, 마지막 클라이언트가 사라지면 브라우저가 워커째 거둡니다.
+ */
+export const createPortRegistry = () => {
+  const ports = new Set<HubPort>();
+  // 이번 주기 pong을 아직 안 낸 포트 — ping 직후에는 전원이 여기 있으므로 무응답 판정에 쓰면 안 됩니다
+  const awaitingPong = new Set<HubPort>();
+  // 한 주기를 통째로 놓친 포트 — frozen이거나 죽은 것. pong이 오면 되돌아옵니다
+  const silent = new Set<HubPort>();
+
+  const sendPings = (): void => {
+    awaitingPong.forEach((port) => silent.add(port));
+
+    ports.forEach((port) => awaitingPong.add(port));
+    ports.forEach((port) => port.postMessage({ kind: 'ping' }));
+  };
+
+  // 해제 수단을 두지 않습니다 — 이 타이머의 수명은 워커 수명이고, 워커는 브라우저가 통째로 거둡니다.
+  // 테스트의 가짜 타이머는 vitest.setup의 afterEach(useRealTimers)가 시계째 버려 교차 오염이 없습니다
+  setInterval(sendPings, PING_INTERVAL_MS);
+
+  return {
+    add: (port: HubPort): void => {
+      ports.add(port);
+    },
+
+    /** @description 떠난 포트의 늦은 메시지를 거르는 유일한 기준 — frozen 탭은 장부에 남아 있습니다 */
+    has: (port: HubPort): boolean => ports.has(port),
+
+    /**
+     * @description 탭이 스스로 떠났습니다 — 장부에서 빼고 포트를 닫습니다.
+     * 마지막이었는지 함께 알려 호출부가 세션을 접을지 정하게 합니다.
+     */
+    close: (port: HubPort): { wasLast: boolean } => {
+      ports.delete(port);
+      awaitingPong.delete(port);
+      silent.delete(port);
+      port.close();
+
+      return { wasLast: ports.size === 0 };
+    },
+
+    markAlive: (port: HubPort): void => {
+      awaitingPong.delete(port);
+      silent.delete(port);
+    },
+
+    size: (): number => ports.size,
+
+    forEach: (visit: (port: HubPort) => void): void => ports.forEach(visit),
+
+    /**
+     * @description 티켓을 물어볼 탭 하나 — EventSource가 하나라 티켓도 한 장이면 됩니다.
+     * 전원에게 뿌리면 탭 수만큼 POST가 나가고, 그 증폭이 429(fatal)를 자초합니다.
+     * 이번 주기에 답한 탭을 먼저 고르고, 없으면 아직 판정 전인 탭에게 묻습니다.
+     * 전원이 확정 침묵이면 undefined: 답이 올 수 없는 요청을 큐에 쌓으면
+     * 깨어난 탭이 그 수만큼 한꺼번에 POST를 쏘게 됩니다.
+     */
+    livelyPort: (): HubPort | undefined => {
+      const candidates = [...ports];
+      return (
+        candidates.find((port) => !awaitingPong.has(port)) ??
+        candidates.find((port) => !silent.has(port))
+      );
+    },
+  };
+};
+
+export type PortRegistry = ReturnType<typeof createPortRegistry>;

package/src/worker/protocol.ts

@@ -0,0 +1,80 @@
+import type { TicketError } from '../core/ticket';
+import type { SseStatus } from '../core/types';
+
+/**
+ * @description 탭 프록시(WorkerSseClient) ↔ 워커 허브(hub)가 포트로 주고받는 메시지 어휘와 배선 지도.
+ * 수신 처리가 아직 없는 kind는 미지 kind와 같은 규칙으로 무시됩니다 —
+ * 배포 skew로 신·구 코드가 섞여도 안전하게 (코어의 "미지 이벤트는 무시"와 대칭).
+ *
+ *   subscribe·close            : WorkerSseClient → hub. 배선 완료
+ *   status·event               : hub → WorkerSseClient. 배선 완료 — frozen 탭에게도 계속 보냅니다
+ *                                (밀린 몫은 브라우저가 큐잉했다 배달 — 근거는 portRegistry)
+ *   ping / pong                : hub → 탭 / 탭 → hub. 배선 완료 — 무응답이어도 장부에서 빼지 않고
+ *                                티켓 대상에서만 제외합니다. 전원이 침묵하면 연결을 접습니다(휴면)
+ *   init                       : 탭 → hub. 배선 완료 — 첫 탭의 baseUrl로 연결을 세우고,
+ *                                휴면으로 접힌 연결을 깨어난 탭이 이 신호로 다시 엽니다
+ *   ticket-request / response  : hub → 탭 / 탭 → hub. 배선 완료 — 토큰은 탭에 남고 발급 결과만 오갑니다
+ *
+ * 로그아웃은 서버가 goaway(reason: user_logout)로 알려 모든 탭에 함께 닿습니다 — 탭이 워커에 알리는 kind는 두지 않습니다.
+ */
+/** @description 티켓 위임의 응답 — 토큰이 아니라 발급 결과(티켓 문자열)만 워커로 넘어갑니다 */
+export type TicketResponseMessage =
+  | { kind: 'ticket-response'; ok: true; ticket: string }
+  | { kind: 'ticket-response'; ok: false; error: TicketError };
+
+export type TabToWorkerMessage =
+  | { kind: 'init'; baseUrl: string }
+  // 구독은 워커 수명 동안 유지됩니다 — 탭별 필터링은 프록시의 로컬 dispatch 몫
+  | { kind: 'subscribe'; event: string }
+  | { kind: 'pong' }
+  | { kind: 'close' }
+  | TicketResponseMessage;
+
+export type WorkerToTabMessage =
+  | { kind: 'event'; event: string; payload: unknown }
+  | { kind: 'status'; status: SseStatus }
+  | { kind: 'ping' }
+  | { kind: 'ticket-request' };
+
+/**
+ * @description 포트로 갓 도착한 메시지 — kind만 믿고 나머지 필드는 검사 전까지 unknown입니다.
+ * 보낸 쪽이 구버전·타 구현일 수 있어, 검사를 빠뜨리면 컴파일이 막히도록 여기서 좁혀둡니다.
+ */
+export type Incoming<M extends { kind: string }> = {
+  [K in keyof M]: K extends 'kind' ? M[K] : unknown;
+};
+
+/** @description 판정을 메시지 정의 옆에 둡니다 — 필드가 바뀌면 여기도 같이 눈에 띄도록 */
+export const isTicketResponse = (
+  message: Incoming<TabToWorkerMessage>
+): message is TicketResponseMessage => {
+  if (message.kind !== 'ticket-response') {
+    return false;
+  }
+
+  const { ok, ticket, error } = message as {
+    ok?: unknown;
+    ticket?: unknown;
+    error?: unknown;
+  };
+
+  if (ok === true) {
+    return typeof ticket === 'string';
+  }
+  if (
+    ok !== false ||
+    typeof error !== 'object' ||
+    error === null ||
+    Array.isArray(error)
+  ) {
+    return false;
+  }
+
+  // status는 fatal 판정에 쓰이므로 숫자가 아니면 재시도 대상으로 흘려보내지 않습니다
+  const { status, cause } = error as { status?: unknown; cause?: unknown };
+  if (status !== undefined && typeof status !== 'number') {
+    return false;
+  }
+  // 미지 cause 문자열은 버리지 않고 통과시킵니다 — 코어가 모르는 값은 status 규칙으로 처리하므로 배포 skew에 안전합니다
+  return cause === undefined || typeof cause === 'string';
+};

package/src/worker/sse.worker.ts

@@ -0,0 +1,19 @@
+import { createWorkerHub } from './hub';
+
+// dom lib의 self(Window)와 다른 SharedWorker 전역 스코프 — 필요한 표면만 좁혀 캐스팅합니다
+interface SharedWorkerScope {
+  onconnect: ((event: MessageEvent) => void) | null;
+}
+
+const hub = createWorkerHub();
+
+(self as unknown as SharedWorkerScope).onconnect = (event) => {
+  const port = event.ports[0];
+  if (port === undefined) {
+    return;
+  }
+
+  hub.addPort(port);
+  port.onmessage = (message) => hub.handleMessage(port, message.data);
+  port.start();
+};

package/src/worker/ticketDelegate.test.ts

@@ -0,0 +1,99 @@
+// @vitest-environment node
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createTicketDelegate,
+  TICKET_RESPONSE_TIMEOUT_MS,
+} from './ticketDelegate';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('티켓 위임 — 탭에 발급을 요청합니다', () => {
+  it('요청하면 탭에 ticket-request를 보내고, 응답이 오면 그 결과로 완료됩니다', async () => {
+    const requests: number[] = [];
+    const delegate = createTicketDelegate(() => requests.push(1));
+
+    const pending = delegate.request();
+    expect(requests).toHaveLength(1);
+
+    delegate.settle({ kind: 'ticket-response', ok: true, ticket: 'ticket-1' });
+
+    await expect(pending).resolves.toEqual({ ok: true, ticket: 'ticket-1' });
+  });
+
+  it('실패 응답은 상태 코드를 그대로 전달합니다 — 재시도 가능 여부는 코어가 판단합니다', async () => {
+    const delegate = createTicketDelegate(() => {});
+
+    const pending = delegate.request();
+    delegate.settle({
+      kind: 'ticket-response',
+      ok: false,
+      error: { status: 401 },
+    });
+
+    await expect(pending).resolves.toEqual({
+      ok: false,
+      error: { status: 401 },
+    });
+  });
+
+  it('응답이 오지 않으면 시간 제한 뒤 네트워크성 실패로 완료됩니다 — 탭이 죽어도 연결 루프가 멈추지 않습니다', async () => {
+    const delegate = createTicketDelegate(() => {});
+
+    const pending = delegate.request();
+    await vi.advanceTimersByTimeAsync(TICKET_RESPONSE_TIMEOUT_MS);
+
+    await expect(pending).resolves.toEqual({ ok: false, error: {} });
+  });
+
+  it('시간 제한 뒤 뒤늦게 도착한 응답은 무시합니다', async () => {
+    const delegate = createTicketDelegate(() => {});
+
+    const pending = delegate.request();
+    await vi.advanceTimersByTimeAsync(TICKET_RESPONSE_TIMEOUT_MS);
+    expect(() =>
+      delegate.settle({ kind: 'ticket-response', ok: true, ticket: 'late' })
+    ).not.toThrow();
+
+    await expect(pending).resolves.toEqual({ ok: false, error: {} });
+  });
+
+  it('요청이 진행 중이면 새 요청을 겹쳐 보내지 않고 같은 응답을 함께 기다립니다', async () => {
+    let requestCount = 0;
+    const delegate = createTicketDelegate(() => {
+      requestCount += 1;
+    });
+
+    const first = delegate.request();
+    const second = delegate.request();
+    expect(requestCount).toBe(1);
+
+    delegate.settle({ kind: 'ticket-response', ok: true, ticket: 'ticket-1' });
+
+    await expect(first).resolves.toEqual({ ok: true, ticket: 'ticket-1' });
+    await expect(second).resolves.toEqual({ ok: true, ticket: 'ticket-1' });
+  });
+
+  it('완료된 뒤 다시 요청하면 탭에 새로 요청합니다', async () => {
+    let requestCount = 0;
+    const delegate = createTicketDelegate(() => {
+      requestCount += 1;
+    });
+
+    const first = delegate.request();
+    delegate.settle({ kind: 'ticket-response', ok: true, ticket: 'ticket-1' });
+    await first;
+
+    const second = delegate.request();
+    expect(requestCount).toBe(2);
+    delegate.settle({ kind: 'ticket-response', ok: true, ticket: 'ticket-2' });
+
+    await expect(second).resolves.toEqual({ ok: true, ticket: 'ticket-2' });
+  });
+});