sonamu 0.9.5 → 0.9.6

package/src/shared/web.shared.ts.txt

@@ -326,8 +326,23 @@ export type SSEStreamState = {
   retryCount: number;
   isEnded: boolean;
 };
+export type WebSocketChannelOptions = {
+  enabled?: boolean;
+  retry?: number;
+  retryInterval?: number;
+  protocols?: string | string[];
+};
+export type WebSocketChannelState<TSend extends Record<string, any>> = {
+  isConnected: boolean;
+  error: string | null;
+  retryCount: number;
+  readyState: number;
+  send<K extends keyof TSend>(event: K, data: TSend[K]): void;
+  close(code?: number, reason?: string): void;
+};
+// outbound event 전체를 강제하지 않도록 handler를 optional map으로 둠
 export type EventHandlers<T> = {
-  [K in keyof T]: (data: T[K]) => void;
+  [K in keyof T]?: (data: T[K]) => void;
 };
 
 export function useSSEStream<T extends Record<string, any>>(
@@ -551,6 +566,272 @@ export function useSSEStream<T extends Record<string, any>>(
   return state;
 }
 
+export function useWebSocketChannel<
+  TReceive extends Record<string, any>,
+  TSend extends Record<string, any>,
+>(
+  url: string,
+  params: Record<string, any>,
+  handlers: EventHandlers<TReceive>,
+  options: WebSocketChannelOptions = {},
+): WebSocketChannelState<TSend> {
+  const { enabled = true, retry = 3, retryInterval = 3000, protocols } = options;
+
+  const [state, setState] = useState<Omit<WebSocketChannelState<TSend>, "send" | "close">>({
+    isConnected: false,
+    error: null,
+    retryCount: 0,
+    readyState: 3,
+  });
+
+  const socketRef = useRef<WebSocket | null>(null);
+  const retryTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const handlersRef = useRef(handlers);
+  const manualCloseRef = useRef(false);
+  // 최신 연결 식별자를 따로 두어 stale socket 이벤트가 상태를 덮지 못하게 함
+  const connectionIdRef = useRef(0);
+
+  useEffect(() => {
+    handlersRef.current = handlers;
+  }, [handlers]);
+
+  const close = (code?: number, reason?: string) => {
+    manualCloseRef.current = true;
+    if (retryTimeoutRef.current) {
+      clearTimeout(retryTimeoutRef.current);
+      retryTimeoutRef.current = null;
+    }
+    if (socketRef.current) {
+      socketRef.current.close(code, reason);
+    }
+  };
+
+  const send = <K extends keyof TSend>(event: K, data: TSend[K]) => {
+    const socket = socketRef.current;
+    if (!socket || socket.readyState !== WebSocket.OPEN) {
+      setState((prev) => ({
+        ...prev,
+        error: "WebSocket is not connected",
+      }));
+      return;
+    }
+
+    socket.send(
+      JSON.stringify({
+        event,
+        data,
+      }),
+    );
+  };
+
+  const connect = () => {
+    if (!enabled) {
+      return;
+    }
+
+    const connectionId = ++connectionIdRef.current;
+    manualCloseRef.current = false;
+
+    if (socketRef.current) {
+      socketRef.current.close();
+      socketRef.current = null;
+    }
+
+    if (retryTimeoutRef.current) {
+      clearTimeout(retryTimeoutRef.current);
+      retryTimeoutRef.current = null;
+    }
+
+    const fullUrl = resolveWebSocketUrl(url, params);
+    const socket = new WebSocket(fullUrl, protocols);
+    socketRef.current = socket;
+
+    setState((prev) => ({
+      ...prev,
+      isConnected: false,
+      error: null,
+      readyState: socket.readyState,
+    }));
+
+    // socketRef.current !== socket 가드는 이전 연결의 늦은 콜백을 무시하기 위한 장치임
+    socket.addEventListener("open", () => {
+      if (socketRef.current !== socket) {
+        return;
+      }
+
+      setState((prev) => ({
+        ...prev,
+        isConnected: true,
+        error: null,
+        retryCount: 0,
+        readyState: socket.readyState,
+      }));
+    });
+
+    socket.addEventListener("message", (event) => {
+      if (socketRef.current !== socket) {
+        return;
+      }
+
+      try {
+        const payload = JSON.parse(event.data, dateReviver) as {
+          event: keyof TReceive;
+          data: TReceive[keyof TReceive];
+        };
+        const handler = handlersRef.current[payload.event];
+        if (handler) {
+          handler(payload.data);
+        }
+      } catch (error) {
+        console.error("Failed to parse WebSocket message:", error);
+      }
+    });
+
+    socket.addEventListener("error", () => {
+      if (socketRef.current !== socket) {
+        return;
+      }
+
+      setState((prev) => ({
+        ...prev,
+        isConnected: false,
+        error: "WebSocket connection failed",
+        readyState: socket.readyState,
+      }));
+    });
+
+    socket.addEventListener("close", (event) => {
+      if (socketRef.current !== socket) {
+        return;
+      }
+
+      socketRef.current = null;
+
+      setState((prev) => ({
+        ...prev,
+        isConnected: false,
+        readyState: socket.readyState,
+      }));
+
+      if (manualCloseRef.current || connectionIdRef.current !== connectionId) {
+        return;
+      }
+
+      // 정책 위반/과대 payload close는 재시도보다 명시적 에러 노출이 우선임
+      if (!isRetryableWebSocketCloseCode(event.code)) {
+        setState((prev) => ({
+          ...prev,
+          error:
+            event.code === 1008 || event.code === 1009
+              ? `WebSocket rejected by server (code: ${event.code})`
+              : `WebSocket closed (code: ${event.code})`,
+        }));
+        return;
+      }
+
+      setState((prev) => {
+        if (prev.retryCount >= retry) {
+          return {
+            ...prev,
+            error: `Connection failed after ${retry} attempts`,
+          };
+        }
+
+        retryTimeoutRef.current = setTimeout(() => {
+          if (connectionIdRef.current !== connectionId) {
+            return;
+          }
+
+          setState((inner) => ({
+            ...inner,
+            retryCount: inner.retryCount + 1,
+          }));
+          connect();
+        }, retryInterval);
+
+        return prev;
+      });
+    });
+  };
+
+  useEffect(() => {
+    if (enabled) {
+      setState({
+        isConnected: false,
+        error: null,
+        retryCount: 0,
+        readyState: 3,
+      });
+      connect();
+    }
+
+    return () => {
+      connectionIdRef.current += 1;
+      manualCloseRef.current = true;
+      if (socketRef.current) {
+        socketRef.current.close();
+        socketRef.current = null;
+      }
+      if (retryTimeoutRef.current) {
+        clearTimeout(retryTimeoutRef.current);
+        retryTimeoutRef.current = null;
+      }
+    };
+  }, [url, JSON.stringify(params), enabled, JSON.stringify(protocols)]);
+
+  return {
+    ...state,
+    send,
+    close,
+  };
+}
+
+function isRetryableWebSocketCloseCode(code: number): boolean {
+  if (code === 1000) {
+    return false;
+  }
+
+  return ![1002, 1003, 1007, 1008, 1009].includes(code);
+}
+
+function resolveWebSocketUrl(url: string, params: Record<string, any>): string {
+  const queryString = qs.stringify(params);
+  const withQuery = queryString ? `${url}?${queryString}` : url;
+
+  if (withQuery.startsWith("ws://") || withQuery.startsWith("wss://")) {
+    return withQuery;
+  }
+
+  const baseUrl = resolveWebSocketBaseUrl();
+  return new URL(withQuery, baseUrl).toString();
+}
+
+function resolveWebSocketBaseUrl(): string {
+  const configuredBaseUrl = axios.defaults.baseURL;
+  // HTTP client와 WS client가 다른 origin으로 갈라지지 않게 axios baseURL을 우선 존중함
+  if (configuredBaseUrl) {
+    const absoluteBaseUrl =
+      typeof window !== "undefined"
+        ? new URL(configuredBaseUrl, window.location.origin).toString()
+        : configuredBaseUrl;
+    return toWebSocketBaseUrl(absoluteBaseUrl);
+  }
+
+  if (typeof window !== "undefined") {
+    return toWebSocketBaseUrl(window.location.origin);
+  }
+
+  return toWebSocketBaseUrl("$[[baseUrl]]");
+}
+
+function toWebSocketBaseUrl(baseUrl: string): string {
+  if (baseUrl.startsWith("ws://") || baseUrl.startsWith("wss://")) {
+    return baseUrl;
+  }
+
+  return baseUrl.replace(/^http:/, "ws:").replace(/^https:/, "wss:");
+}
+
 /*
   Dictionary Helper
 */

package/src/stream/__tests__/ws-contracts.test.ts

@@ -0,0 +1,381 @@
+import { describe, expect, it } from "vitest";
+
+import { WebSocketAudience } from "../ws-audience";
+import { WebSocketAudienceResolver } from "../ws-audience-resolver";
+import {
+  NoopWebSocketClusterBus,
+  type WebSocketClusterBus,
+  type WebSocketClusterEnvelope,
+  type WebSocketClusterEnvelopeHandler,
+} from "../ws-cluster-bus";
+import { type ManagedWebSocketConnection } from "../ws-core";
+import { WebSocketDeliveryEngine } from "../ws-delivery";
+import { WebSocketLocalConnectionStore } from "../ws-local-connection-store";
+import { InMemoryWebSocketPresenceStore } from "../ws-presence-store";
+
+async function waitForAsyncQueue(rounds: number = 3): Promise<void> {
+  for (let index = 0; index < rounds; index += 1) {
+    await new Promise<void>((resolve) => {
+      setImmediate(resolve);
+    });
+  }
+}
+
+class ContractClusterBus implements WebSocketClusterBus {
+  readonly published: WebSocketClusterEnvelope[] = [];
+  private readonly handlers = new Set<WebSocketClusterEnvelopeHandler>();
+
+  publish(envelope: WebSocketClusterEnvelope): void {
+    this.published.push(envelope);
+  }
+
+  subscribe(handler: WebSocketClusterEnvelopeHandler): () => void {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+
+  emit(envelope: WebSocketClusterEnvelope): void {
+    for (const handler of this.handlers) {
+      handler(envelope);
+    }
+  }
+
+  shutdown(): void {
+    this.handlers.clear();
+  }
+}
+
+class ContractConnection implements ManagedWebSocketConnection {
+  readonly sent: Array<{ event: string; data: unknown }> = [];
+  closed = false;
+
+  constructor(
+    readonly id: string,
+    readonly namespace: string,
+  ) {}
+
+  publishUntyped(event: string, data: unknown): void {
+    this.sent.push({ event, data });
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+}
+
+describe("WebSocket contract tests", () => {
+  describe("PresenceStore", () => {
+    it("keeps inactive sessions out of counts and audience queries until activation", () => {
+      const store = new InMemoryWebSocketPresenceStore();
+      store.register({
+        sessionId: "s1",
+        nodeId: "node-a",
+        namespace: "chat",
+        active: false,
+      });
+
+      expect(store.getConnectionCount("chat")).toBe(0);
+      expect(store.queryAudience(WebSocketAudience.all("chat"))).toHaveLength(0);
+
+      store.activate("s1");
+
+      expect(store.getConnectionCount("chat")).toBe(1);
+      expect(
+        store.queryAudience(WebSocketAudience.all("chat")).map((meta) => meta.sessionId),
+      ).toEqual(["s1"]);
+    });
+
+    it("isolates room and user bindings by namespace", () => {
+      const store = new InMemoryWebSocketPresenceStore();
+      store.register({
+        sessionId: "chat-1",
+        nodeId: "node-a",
+        namespace: "chat",
+      });
+      store.register({
+        sessionId: "admin-1",
+        nodeId: "node-a",
+        namespace: "admin",
+      });
+
+      store.join("chat-1", "room-1");
+      store.join("admin-1", "room-1");
+      store.setUserId("chat-1", "user-1");
+      store.setUserId("admin-1", "user-1");
+
+      expect(
+        store.queryAudience(WebSocketAudience.room("room-1", "chat")).map((meta) => meta.sessionId),
+      ).toEqual(["chat-1"]);
+      expect(
+        store
+          .queryAudience(WebSocketAudience.user("user-1", "admin"))
+          .map((meta) => meta.sessionId),
+      ).toEqual(["admin-1"]);
+    });
+
+    it("cleans room and user bindings when a session is unregistered", () => {
+      const store = new InMemoryWebSocketPresenceStore();
+      store.register({
+        sessionId: "s1",
+        nodeId: "node-a",
+        namespace: "chat",
+      });
+      store.join("s1", "room-1");
+      store.setUserId("s1", "user-1");
+
+      expect(store.unregister("s1")?.sessionId).toBe("s1");
+
+      expect(store.getConnection("s1")).toBeUndefined();
+      expect(store.queryAudience(WebSocketAudience.room("room-1", "chat"))).toHaveLength(0);
+      expect(store.queryAudience(WebSocketAudience.user("user-1", "chat"))).toHaveLength(0);
+      expect(store.getStats()).toMatchObject({
+        totalConnections: 0,
+        totalRooms: 0,
+      });
+    });
+
+    it("dedupes union audience results", () => {
+      const store = new InMemoryWebSocketPresenceStore();
+      store.register({
+        sessionId: "s1",
+        nodeId: "node-a",
+        namespace: "chat",
+      });
+      store.join("s1", "room-1");
+      store.setUserId("s1", "user-1");
+
+      const metas = store.queryAudience(
+        WebSocketAudience.union(
+          WebSocketAudience.room("room-1", "chat"),
+          WebSocketAudience.user("user-1", "chat"),
+        ),
+      );
+
+      expect(metas.map((meta) => meta.sessionId)).toEqual(["s1"]);
+    });
+  });
+
+  describe("AudienceResolver", () => {
+    it("splits local session ids from unique remote node ids", () => {
+      const store = new InMemoryWebSocketPresenceStore();
+      store.register({
+        sessionId: "local-1",
+        nodeId: "node-a",
+        namespace: "chat",
+      });
+      store.register({
+        sessionId: "remote-1",
+        nodeId: "node-b",
+        namespace: "chat",
+      });
+      store.register({
+        sessionId: "remote-2",
+        nodeId: "node-b",
+        namespace: "chat",
+      });
+      store.join("local-1", "room-1");
+      store.join("remote-1", "room-1");
+      store.join("remote-2", "room-1");
+      const resolver = new WebSocketAudienceResolver({
+        nodeId: "node-a",
+        presenceStore: store,
+      });
+
+      expect(resolver.resolve(WebSocketAudience.room("room-1", "chat"))).toEqual({
+        localSessionIds: ["local-1"],
+        remoteNodeIds: ["node-b"],
+      });
+    });
+  });
+
+  describe("ClusterBus", () => {
+    it("allows subscribers to unsubscribe without affecting later publishes", () => {
+      const bus = new ContractClusterBus();
+      const received: string[] = [];
+      const unsubscribe = bus.subscribe((envelope) => {
+        received.push(envelope.id);
+      });
+
+      bus.emit(createEnvelope("e1"));
+      unsubscribe();
+      bus.emit(createEnvelope("e2"));
+
+      expect(received).toEqual(["e1"]);
+    });
+
+    it("keeps NoopClusterBus publish, subscribe, and shutdown safe", async () => {
+      const bus = new NoopWebSocketClusterBus();
+      const unsubscribe = bus.subscribe(() => {
+        throw new Error("noop bus must not retain handlers");
+      });
+
+      await Promise.resolve(bus.publish(createEnvelope("noop")));
+      expect(unsubscribe()).toBeUndefined();
+      await Promise.resolve(bus.shutdown());
+    });
+  });
+
+  describe("DeliveryEngine", () => {
+    it("queues local delivery and reports queued local target count", async () => {
+      const presenceStore = new InMemoryWebSocketPresenceStore();
+      const localConnections = new WebSocketLocalConnectionStore();
+      const clusterBus = new ContractClusterBus();
+      const connection = new ContractConnection("s1", "chat");
+      localConnections.register(connection);
+      presenceStore.register({
+        sessionId: "s1",
+        nodeId: "node-a",
+        namespace: "chat",
+      });
+      const engine = createDeliveryEngine({
+        nodeId: "node-a",
+        presenceStore,
+        localConnections,
+        clusterBus,
+      });
+
+      engine.publishToAudience(WebSocketAudience.all("chat"), "onReady", {
+        ok: true,
+      });
+
+      expect(connection.sent).toHaveLength(0);
+
+      await waitForAsyncQueue();
+
+      expect(connection.sent).toEqual([
+        {
+          event: "onReady",
+          data: {
+            ok: true,
+          },
+        },
+      ]);
+    });
+
+    it("publishes one remote envelope per remote-node routing plan", async () => {
+      const presenceStore = new InMemoryWebSocketPresenceStore();
+      const localConnections = new WebSocketLocalConnectionStore();
+      const clusterBus = new ContractClusterBus();
+      presenceStore.register({
+        sessionId: "remote-1",
+        nodeId: "node-b",
+        namespace: "chat",
+      });
+      presenceStore.join("remote-1", "room-1");
+      const engine = createDeliveryEngine({
+        nodeId: "node-a",
+        presenceStore,
+        localConnections,
+        clusterBus,
+      });
+
+      engine.publishToAudience(WebSocketAudience.room("room-1", "chat"), "evt", {
+        ok: true,
+      });
+
+      await waitForAsyncQueue();
+
+      expect(clusterBus.published).toHaveLength(1);
+      expect(clusterBus.published[0]).toMatchObject({
+        sourceNodeId: "node-a",
+        targetNodeIds: ["node-b"],
+        event: "evt",
+      });
+    });
+
+    it("ignores cluster envelopes from itself or targeted to another node", async () => {
+      const presenceStore = new InMemoryWebSocketPresenceStore();
+      const localConnections = new WebSocketLocalConnectionStore();
+      const clusterBus = new ContractClusterBus();
+      const connection = new ContractConnection("s1", "chat");
+      localConnections.register(connection);
+      presenceStore.register({
+        sessionId: "s1",
+        nodeId: "node-a",
+        namespace: "chat",
+      });
+      createDeliveryEngine({
+        nodeId: "node-a",
+        presenceStore,
+        localConnections,
+        clusterBus,
+      });
+
+      clusterBus.emit(createEnvelope("self", "node-a", ["node-a"]));
+      clusterBus.emit(createEnvelope("other-target", "node-b", ["node-c"]));
+
+      await waitForAsyncQueue();
+
+      expect(connection.sent).toHaveLength(0);
+    });
+
+    it("delivers accepted cluster envelopes only to local targets", async () => {
+      const presenceStore = new InMemoryWebSocketPresenceStore();
+      const localConnections = new WebSocketLocalConnectionStore();
+      const clusterBus = new ContractClusterBus();
+      const connection = new ContractConnection("s1", "chat");
+      localConnections.register(connection);
+      presenceStore.register({
+        sessionId: "s1",
+        nodeId: "node-a",
+        namespace: "chat",
+      });
+      createDeliveryEngine({
+        nodeId: "node-a",
+        presenceStore,
+        localConnections,
+        clusterBus,
+      });
+
+      clusterBus.emit(createEnvelope("remote", "node-b", ["node-a"]));
+
+      await waitForAsyncQueue();
+
+      expect(connection.sent).toEqual([
+        {
+          event: "evt",
+          data: {
+            ok: true,
+          },
+        },
+      ]);
+    });
+  });
+});
+
+function createDeliveryEngine(input: {
+  nodeId: string;
+  presenceStore: InMemoryWebSocketPresenceStore;
+  localConnections: WebSocketLocalConnectionStore;
+  clusterBus: WebSocketClusterBus;
+}): WebSocketDeliveryEngine {
+  return new WebSocketDeliveryEngine({
+    nodeId: input.nodeId,
+    localConnections: input.localConnections,
+    audienceResolver: new WebSocketAudienceResolver({
+      nodeId: input.nodeId,
+      presenceStore: input.presenceStore,
+    }),
+    clusterBus: input.clusterBus,
+  });
+}
+
+function createEnvelope(
+  id: string,
+  sourceNodeId = "node-b",
+  targetNodeIds: string[] | undefined = ["node-a"],
+): WebSocketClusterEnvelope {
+  return {
+    id,
+    sourceNodeId,
+    targetNodeIds,
+    audience: WebSocketAudience.all("chat"),
+    event: "evt",
+    data: {
+      ok: true,
+    },
+    emittedAt: Date.now(),
+  };
+}