@remember-web/sse 0.1.0-alpha.1

package/src/worker/WorkerSseClient.test.ts

@@ -0,0 +1,377 @@
+// @vitest-environment node
+import { describe, expect, it, vi } from 'vitest';
+
+import type { WorkerToTabMessage } from './protocol';
+import { WorkerSseClient } from './WorkerSseClient';
+
+import type { SseStatus } from '../core/types';
+import { FakeSharedWorker, type TestEventMap } from '../testing';
+
+const createProxyHarness = () => {
+  const workers: FakeSharedWorker[] = [];
+  const client = new WorkerSseClient<TestEventMap>({
+    baseUrl: 'https://sse.example.com',
+    getAuthToken: () => 'token-1',
+    sharedWorker: () => {
+      const worker = new FakeSharedWorker();
+      workers.push(worker);
+      return worker as unknown as SharedWorker;
+    },
+  });
+  return { client, workers, lastPort: () => workers.at(-1)!.port };
+};
+
+describe('탭 프록시 — 워커 연결', () => {
+  it('connect하면 워커를 기동하고 포트를 시작합니다', () => {
+    const { client, workers, lastPort } = createProxyHarness();
+
+    client.connect();
+
+    expect(workers).toHaveLength(1);
+    expect(lastPort().started).toBe(true);
+  });
+
+  it('connect하면 init에 baseUrl을 담아 보냅니다 — 워커가 이 값으로 연결을 세웁니다', () => {
+    const { client, lastPort } = createProxyHarness();
+
+    client.connect();
+
+    expect(lastPort().posted[0]).toEqual({
+      kind: 'init',
+      baseUrl: 'https://sse.example.com',
+    });
+  });
+
+  it('connect를 여러 번 불러도 워커 기동은 한 번만 일어납니다', () => {
+    const { client, workers } = createProxyHarness();
+
+    client.connect();
+    client.connect();
+
+    expect(workers).toHaveLength(1);
+  });
+
+  it('open 상태에서 connect해도 init을 다시 보냅니다 — 수거됐는지는 워커만 압니다', () => {
+    const { client, workers, lastPort } = createProxyHarness();
+
+    client.connect();
+    lastPort().deliver({ kind: 'status', status: 'open' });
+    client.connect();
+
+    expect(workers).toHaveLength(1);
+    expect(
+      lastPort().posted.filter((message) => message.kind === 'init')
+    ).toHaveLength(2);
+  });
+
+  it('sharedWorker 팩토리가 던지면(CSP 차단·잘못된 URL 등) fatal이 되고 logger.error로 알립니다', () => {
+    const errors: string[] = [];
+    const client = new WorkerSseClient<TestEventMap>({
+      baseUrl: 'https://sse.example.com',
+      getAuthToken: () => 'token-1',
+      logger: { warn: () => {}, error: (message) => errors.push(message) },
+      sharedWorker: () => {
+        throw new Error('blocked');
+      },
+    });
+
+    expect(() => client.connect()).not.toThrow();
+    expect(client.status).toBe('fatal');
+    expect(errors).toHaveLength(1);
+  });
+
+  it('sharedWorker 팩토리가 던지면 사유를 blocked로 알립니다 — 환경 차단(CSP 등) 안내를 가를 수 있게', () => {
+    const client = new WorkerSseClient<TestEventMap>({
+      baseUrl: 'https://sse.example.com',
+      getAuthToken: () => 'token-1',
+      logger: { warn: () => {}, error: () => {} },
+      sharedWorker: () => {
+        throw new Error('blocked');
+      },
+    });
+    const causes: unknown[] = [];
+    client.on('fatal', (payload) => causes.push(payload));
+
+    client.connect();
+
+    expect(causes).toEqual([{ cause: 'blocked' }]);
+  });
+
+  it('fatal 상태에서 connect()를 다시 불러도 워커를 재기동하지 않고, disconnect()가 먼저 필요함을 logger.warn으로 알립니다', () => {
+    const warnings: string[] = [];
+    const workers: FakeSharedWorker[] = [];
+    let failCreation = true;
+    const client = new WorkerSseClient<TestEventMap>({
+      baseUrl: 'https://sse.example.com',
+      getAuthToken: () => 'token-1',
+      logger: { warn: (message) => warnings.push(message), error: () => {} },
+      sharedWorker: () => {
+        if (failCreation) {
+          throw new Error('blocked');
+        }
+        const worker = new FakeSharedWorker();
+        workers.push(worker);
+        return worker as unknown as SharedWorker;
+      },
+    });
+
+    client.connect();
+    expect(client.status).toBe('fatal');
+
+    failCreation = false;
+    client.connect();
+    expect(client.status).toBe('fatal');
+    expect(workers).toHaveLength(0);
+    expect(warnings).toHaveLength(1);
+
+    client.disconnect();
+    client.connect();
+    expect(workers).toHaveLength(1);
+  });
+
+  it('sharedWorker 팩토리 없이 생성된 경우 connect는 아무 일도 하지 않습니다', () => {
+    const client = new WorkerSseClient<TestEventMap>({
+      baseUrl: 'https://sse.example.com',
+      getAuthToken: () => 'token-1',
+    });
+
+    expect(() => client.connect()).not.toThrow();
+    expect(client.status).toBe('idle');
+  });
+});
+
+describe('탭 프록시 — 구독 전달', () => {
+  it('연결 전에 등록한 구독은 connect 시, 연결 후 등록한 구독은 그 자리에서 워커에 알립니다', () => {
+    const { client, lastPort } = createProxyHarness();
+    client.on('demo.created', () => {});
+
+    client.connect();
+    expect(lastPort().posted).toContainEqual({
+      kind: 'subscribe',
+      event: 'demo.created',
+    });
+
+    client.on('demo.updated', () => {});
+    expect(lastPort().posted).toContainEqual({
+      kind: 'subscribe',
+      event: 'demo.updated',
+    });
+  });
+
+  it('같은 이벤트에 핸들러를 여러 개 등록해도 subscribe는 한 번만 보냅니다', () => {
+    const { client, lastPort } = createProxyHarness();
+
+    client.connect();
+    client.on('demo.created', () => {});
+    client.on('demo.created', () => {});
+
+    const subscribes = lastPort().posted.filter((m) => m.kind === 'subscribe');
+    expect(subscribes).toHaveLength(1);
+  });
+
+  it("SDK 예약 이벤트('hello')와 'resync' 구독은 워커에 subscribe를 보내지 않습니다", () => {
+    const { client, lastPort } = createProxyHarness();
+
+    client.connect();
+    client.on('hello', () => {});
+    client.on('resync', () => {});
+
+    expect(
+      lastPort().posted.filter((m) => m.kind === 'subscribe')
+    ).toHaveLength(0);
+  });
+});
+
+describe('탭 프록시 — 워커 통지 반영', () => {
+  it('워커의 status 통지를 구독자에게 그대로 알립니다', () => {
+    const { client, lastPort } = createProxyHarness();
+    const statuses: SseStatus[] = [];
+    client.onStatus((status) => statuses.push(status));
+
+    client.connect();
+    lastPort().deliver({ kind: 'status', status: 'connecting' });
+    lastPort().deliver({ kind: 'status', status: 'open' });
+
+    expect(statuses).toEqual(['connecting', 'open']);
+    expect(client.status).toBe('open');
+  });
+
+  it('워커의 event 통지를 로컬 핸들러에 배달하고, 핸들러 없는 이벤트는 무시합니다', () => {
+    const { client, lastPort } = createProxyHarness();
+    const received: { id: string }[] = [];
+    client.on('demo.created', (event) => received.push(event));
+
+    client.connect();
+    lastPort().deliver({
+      kind: 'event',
+      event: 'demo.created',
+      payload: { id: 'a' },
+    });
+    expect(() =>
+      lastPort().deliver({ kind: 'event', event: 'demo.unknown', payload: {} })
+    ).not.toThrow();
+
+    expect(received).toEqual([{ id: 'a' }]);
+  });
+
+  it('버전이 다른 워커가 보낸 미지의 status 값은 무시합니다 — status 타입 보증을 지킵니다', () => {
+    const { client, lastPort } = createProxyHarness();
+
+    client.connect();
+    lastPort().deliver({
+      kind: 'status',
+      status: 'future-status',
+    } as unknown as WorkerToTabMessage);
+
+    expect(client.status).toBe('idle');
+  });
+
+  it('워커의 ping에 pong으로 응답합니다 — 이 탭이 살아 있음을 알립니다', () => {
+    const { client, lastPort } = createProxyHarness();
+
+    client.connect();
+    lastPort().deliver({ kind: 'ping' });
+
+    expect(lastPort().posted.at(-1)).toEqual({ kind: 'pong' });
+  });
+
+  it('워커가 티켓을 요청하면 토큰으로 발급받아 결과만 넘깁니다 — 토큰은 탭에 남습니다', async () => {
+    const fetchCalls: { url: string; authorization?: string }[] = [];
+    const client = new WorkerSseClient<TestEventMap>({
+      baseUrl: 'https://sse.example.com',
+      getAuthToken: () => 'token-1',
+      fetch: (async (input: unknown, init?: RequestInit) => {
+        const headers = (init?.headers ?? {}) as Record<string, string>;
+        fetchCalls.push({
+          url: String(input),
+          authorization: headers.Authorization,
+        });
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ data: { ticket: 'ticket-1' } }),
+        } as unknown as Response;
+      }) as unknown as typeof globalThis.fetch,
+      sharedWorker: () => {
+        const worker = new FakeSharedWorker();
+        workersForTicket.push(worker);
+        return worker as unknown as SharedWorker;
+      },
+    });
+    const workersForTicket: FakeSharedWorker[] = [];
+
+    client.connect();
+    const port = workersForTicket.at(-1)!.port;
+    port.deliver({ kind: 'ticket-request' });
+    await vi.waitFor(() =>
+      expect(port.posted.some((m) => m.kind === 'ticket-response')).toBe(true)
+    );
+
+    expect(fetchCalls[0]?.authorization).toBe('Bearer token-1');
+    expect(port.posted.at(-1)).toEqual({
+      kind: 'ticket-response',
+      ok: true,
+      ticket: 'ticket-1',
+    });
+  });
+
+  it('티켓 발급이 실패하면 실패 결과를 그대로 넘깁니다 — 재시도 판단은 워커 몫입니다', async () => {
+    const workersForTicket: FakeSharedWorker[] = [];
+    const client = new WorkerSseClient<TestEventMap>({
+      baseUrl: 'https://sse.example.com',
+      getAuthToken: () => 'token-1',
+      fetch: (async () =>
+        ({
+          ok: false,
+          status: 401,
+        }) as Response) as unknown as typeof globalThis.fetch,
+      sharedWorker: () => {
+        const worker = new FakeSharedWorker();
+        workersForTicket.push(worker);
+        return worker as unknown as SharedWorker;
+      },
+    });
+
+    client.connect();
+    const port = workersForTicket.at(-1)!.port;
+    port.deliver({ kind: 'ticket-request' });
+    await vi.waitFor(() =>
+      expect(port.posted.some((m) => m.kind === 'ticket-response')).toBe(true)
+    );
+
+    expect(port.posted.at(-1)).toEqual({
+      kind: 'ticket-response',
+      ok: false,
+      error: { status: 401 },
+    });
+  });
+
+  it('모르는 kind의 통지는 무시합니다 — 신·구 코드가 섞인 배포 중에도 안전합니다', () => {
+    const { client, lastPort } = createProxyHarness();
+
+    client.connect();
+
+    expect(() =>
+      lastPort().deliver({
+        kind: 'future-thing',
+      } as unknown as WorkerToTabMessage)
+    ).not.toThrow();
+  });
+});
+
+describe('탭 프록시 — 해제', () => {
+  it('disconnect하면 close 메시지를 보낸 뒤 포트를 닫고 closed가 됩니다', () => {
+    const { client, lastPort } = createProxyHarness();
+
+    client.connect();
+    client.disconnect();
+
+    expect(lastPort().posted.at(-1)).toEqual({ kind: 'close' });
+    expect(lastPort().closed).toBe(true);
+    expect(client.status).toBe('closed');
+  });
+
+  it('재연결 직후에는 워커의 상태 통지가 도착할 때까지 직전 상태가 유지됩니다', () => {
+    const { client, lastPort } = createProxyHarness();
+    const statuses: SseStatus[] = [];
+
+    client.connect();
+    lastPort().deliver({ kind: 'status', status: 'open' });
+    client.disconnect();
+    client.onStatus((status) => statuses.push(status));
+
+    // 상태를 소유하지 않으므로 프록시가 임의로 connecting을 만들지 않습니다 — 직결 클라이언트와 갈리는 지점
+    client.connect();
+    expect(client.status).toBe('closed');
+    expect(statuses).toEqual([]);
+
+    lastPort().deliver({ kind: 'status', status: 'connecting' });
+    expect(statuses).toEqual(['connecting']);
+  });
+
+  it('disconnect한 뒤 옛 포트에서 늦게 도착한 통지는 상태를 바꾸지 않습니다', () => {
+    const { client, lastPort } = createProxyHarness();
+
+    client.connect();
+    const oldPort = lastPort();
+    client.disconnect();
+
+    oldPort.deliver({ kind: 'status', status: 'open' });
+    expect(client.status).toBe('closed');
+  });
+
+  it('disconnect 후 다시 connect하면 새 포트로 붙고 기존 구독을 다시 알립니다', () => {
+    const { client, workers, lastPort } = createProxyHarness();
+    client.on('demo.created', () => {});
+
+    client.connect();
+    client.disconnect();
+    client.connect();
+
+    expect(workers).toHaveLength(2);
+    expect(lastPort().posted).toContainEqual({
+      kind: 'subscribe',
+      event: 'demo.created',
+    });
+  });
+});

package/src/worker/WorkerSseClient.ts

@@ -0,0 +1,190 @@
+import type {
+  Incoming,
+  TabToWorkerMessage,
+  TicketResponseMessage,
+  WorkerToTabMessage,
+} from './protocol';
+
+import { BaseSseClient } from '../core/BaseSseClient';
+import { isSubscribableEvent, SDK_EVENTS } from '../core/eventNames';
+import { issueTicketWithTimeout } from '../core/ticket';
+import type {
+  FatalPayload,
+  SseClientOptions,
+  SseEventMap,
+  SseStatus,
+} from '../core/types';
+import { isSseStatus } from '../core/types';
+
+/**
+ * @description SseClient와 같은 시그니처의 탭 측 프록시 — 연결은 SharedWorker가 소유합니다.
+ * 워커와 주고받는 메시지의 방향·배선 현황은 protocol.ts의 지도를 보세요.
+ *
+ * 프록시는 상태를 소유하지 않고 워커의 status 통지를 반영합니다 — 스스로 status를 정하는 건
+ * disconnect의 closed와 워커 생성 실패의 fatal뿐이며, (재)connect 직후에는 워커 스냅샷이
+ * 도착할 때까지 직전 상태가 잠시 유지됩니다.
+ *
+ * 얼어붙은 탭에 복귀 절차는 없습니다 — 밀린 메시지는 깨어날 때 그대로 받습니다.
+ * 전원이 침묵해 워커가 접은 연결만 connect()가 다시 엽니다 (배선은 attachAutoResume).
+ */
+export class WorkerSseClient<
+  M extends object = SseEventMap,
+> extends BaseSseClient<M> {
+  // 워커의 구독 장부(hub)는 탭 구분 없는 전역 union이라, 같은 이벤트는 탭당 한 번만 알리면 됩니다
+  readonly #sentSubscriptions = new Set<string>();
+
+  #status: SseStatus = 'idle';
+  #port: MessagePort | null = null;
+
+  constructor(
+    protected readonly options: Omit<SseClientOptions, 'eventSource'>
+  ) {
+    super(options.logger);
+  }
+
+  get status(): SseStatus {
+    return this.#status;
+  }
+
+  connect(): void {
+    // 팩토리 없는 생성은 방어적 no-op — 정상 경로(createSseClient)는 항상 팩토리와 함께 이 클래스를 고릅니다
+    const factory = this.options.sharedWorker;
+    if (factory === undefined) {
+      return;
+    }
+    // 직결 클라이언트와 같은 회복 계약 — fatal은 disconnect()로 정리한 뒤에만 다시 시도할 수 있습니다
+    if (this.#status === 'fatal') {
+      this.options.logger?.warn(
+        'sse: fatal 상태에서는 connect()가 무시됩니다 — disconnect()로 정리한 뒤 다시 connect() 하세요'
+      );
+      return;
+    }
+    // 연결이 접혔는지(전원 침묵)는 탭의 status로 알 수 없습니다 — 거르지 않고 매번 보냅니다
+    if (this.#port !== null) {
+      this.#requestConnection();
+      return;
+    }
+
+    const worker = this.#createWorker(factory);
+    if (worker === null) {
+      return;
+    }
+
+    const port = worker.port;
+    this.#port = port;
+    port.onmessage = (event) => {
+      const isSamePort = this.#port === port;
+      if (!isSamePort) {
+        return;
+      }
+      this.#handleWorkerMessage(event.data, port);
+    };
+    port.start();
+
+    this.#requestConnection();
+    this.emitter.handlerTypes().forEach((type) => this.#sendSubscribe(type));
+  }
+
+  disconnect(): void {
+    // 이 탭만 해제합니다 — 마지막 탭 판단과 연결 정리는 워커 몫이라 close를 상태 알림보다 먼저 보냅니다
+    this.#post({ kind: 'close' });
+    this.#port?.close();
+    this.#port = null;
+    this.#sentSubscriptions.clear();
+    this.#setStatus('closed');
+  }
+
+  // 포트가 없으면 조용히 넘어갑니다 — connect()가 그때까지 모인 구독을 한 번에 보냅니다
+  protected registerSubscription(type: string): void {
+    this.#sendSubscribe(type);
+  }
+
+  // 워커는 baseUrl을 모르므로 탭이 알려줍니다 — 이미 연결이 서 있으면 워커가 무시합니다
+  #requestConnection(): void {
+    this.#post({ kind: 'init', baseUrl: this.options.baseUrl });
+  }
+
+  // 팩토리는 소비처 코드고 new SharedWorker도 URL 오류·CSP 차단 시 동기로 던집니다 — 직결 클라이언트의 EventSource 생성 실패와 같은 fatal 처리
+  #createWorker(factory: () => SharedWorker): SharedWorker | null {
+    try {
+      return factory();
+    } catch (error) {
+      this.options.logger?.error(
+        'sse: SharedWorker 생성 실패 — 워커 URL·CSP를 확인하세요',
+        error
+      );
+      this.#setStatus('fatal');
+      this.emitter.emit(SDK_EVENTS.fatal, {
+        cause: 'blocked',
+      } satisfies FatalPayload);
+      return null;
+    }
+  }
+
+  #sendSubscribe(type: string): void {
+    if (this.#port === null || this.#sentSubscriptions.has(type)) {
+      return;
+    }
+    if (!isSubscribableEvent(type)) {
+      return;
+    }
+
+    this.#sentSubscriptions.add(type);
+    this.#post({ kind: 'subscribe', event: type });
+  }
+
+  #handleWorkerMessage(data: unknown, port: MessagePort): void {
+    const message = data as Incoming<WorkerToTabMessage> | null;
+    switch (message?.kind) {
+      case 'status':
+        // 포트 너머는 신뢰 경계 — 검증 없이 반영하면 status 게터의 타입 보증이 깨집니다
+        if (isSseStatus(message.status)) {
+          this.#setStatus(message.status);
+        }
+        return;
+      case 'event':
+        if (typeof message.event === 'string') {
+          this.emitter.emit(message.event, message.payload);
+        }
+        return;
+      case 'ping':
+        this.#post({ kind: 'pong' });
+        return;
+      case 'ticket-request':
+        // 토큰은 탭에만 있습니다 — 발급까지 여기서 하고 워커에는 결과만 넘깁니다
+        void this.#issueTicketForWorker(port);
+        return;
+      default:
+        // 여기 도달하는 건 미지 kind(신·구 코드가 섞인 배포)뿐이라 무시합니다
+        message satisfies null;
+        return;
+    }
+  }
+
+  async #issueTicketForWorker(port: MessagePort): Promise<void> {
+    const result = await issueTicketWithTimeout(this.options);
+    // 발급 중 재연결로 포트가 바뀌었으면, 이 티켓은 이미 사라진 세션의 것입니다
+    if (this.#port !== port) {
+      return;
+    }
+
+    const ticketResponse: TicketResponseMessage = result.ok
+      ? { kind: 'ticket-response', ok: true, ticket: result.ticket }
+      : { kind: 'ticket-response', ok: false, error: result.error };
+
+    this.#post(ticketResponse);
+  }
+
+  #post(message: TabToWorkerMessage): void {
+    this.#port?.postMessage(message);
+  }
+
+  #setStatus(next: SseStatus): void {
+    if (this.#status === next) {
+      return;
+    }
+
+    this.#status = next;
+    this.emitter.emitStatus(next);
+  }
+}