sonamu 0.11.16 → 0.12.0

package/src/api/__tests__/sonamu.websocket-routes.test.ts

@@ -0,0 +1,234 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import Fastify, { type FastifyInstance } from "fastify";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+
+import { RecordingClusterBus, flushAsync } from "../../stream/__tests__/ws-test-helpers";
+import { createWebSocketRuntime, type WebSocketRuntime } from "../../stream/ws";
+import { InMemoryWebSocketPresenceStore } from "../../stream/ws-presence-store";
+import { type SonamuFastifyConfig } from "../../types/types";
+import { type ExtendedApi } from "../decorators";
+import { Sonamu } from "../sonamu";
+
+const ChatEventsV1 = z.object({
+  onMessage: z.object({ text: z.string() }),
+});
+// HMR로 바뀐 스키마: 기본값 필드가 추가돼 인코딩 결과가 달라진다
+const ChatEventsV2 = z.object({
+  onMessage: z.object({ text: z.string(), edited: z.boolean().default(true) }),
+});
+const NoticeEvents = z.object({
+  onNotice: z.object({ level: z.number() }),
+});
+const AlertEvents = z.object({
+  onAlert: z.object({ message: z.string() }),
+});
+
+function createWebSocketApi(input: {
+  modelName: string;
+  methodName: string;
+  path: string;
+  outEvents: z.ZodObject;
+}): ExtendedApi {
+  return {
+    modelName: input.modelName,
+    methodName: input.methodName,
+    path: input.path,
+    options: {},
+    websocketOptions: {
+      outEvents: input.outEvents,
+      inEvents: z.object({}),
+      namespace: "chat",
+    },
+    typeParameters: [],
+    parameters: [],
+    returnType: "void",
+  };
+}
+
+const chatApi = (outEvents: z.ZodObject) =>
+  createWebSocketApi({
+    modelName: "ChatFrame",
+    methodName: "subscribe",
+    path: "/chat/subscribe",
+    outEvents,
+  });
+const noticeApi = createWebSocketApi({
+  modelName: "NoticeFrame",
+  methodName: "subscribe",
+  path: "/notice/subscribe",
+  outEvents: NoticeEvents,
+});
+const alertApi = createWebSocketApi({
+  modelName: "AlertFrame",
+  methodName: "subscribe",
+  path: "/alert/subscribe",
+  outEvents: AlertEvents,
+});
+
+// 테스트가 서버 측에서 publish하는 payload 모양
+type ServerPublishData = { text: string; extra?: number } | { level: number } | { message: string };
+
+const config = /* SAFETY: route 등록 단계는 SonamuFastifyConfig의 함수를 호출하지 않는다. */ {
+  contextProvider(defaultContext) {
+    return defaultContext;
+  },
+  guardHandler() {},
+} as SonamuFastifyConfig;
+
+describe("Sonamu websocket route table 등록", () => {
+  const originalState = Sonamu.captureTestingSnapshot();
+  const originalInitialized = Sonamu.isInitialized;
+  const originalNodeEnv = process.env.NODE_ENV;
+  const servers: FastifyInstance[] = [];
+  let tempRoot: string;
+  let runtime: WebSocketRuntime;
+  let clusterBus: RecordingClusterBus;
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(os.tmpdir(), "sonamu-ws-routes-"));
+    // web, web-dist가 없는 api 루트를 만들어 dev/prod 모두 정적 서빙 없이 route만 등록하게 한다
+    Reflect.set(Sonamu, "apiRootPathValue", path.join(tempRoot, "api"));
+    Reflect.set(Sonamu, "configValue", {
+      sync: { targets: [] },
+      api: { route: { prefix: "/api" } },
+      server: {},
+      validation: { zodCompiler: false },
+    });
+    Sonamu.isInitialized = true;
+
+    // 원격 노드 node-b의 세션이 room-1에 있고, 이 노드(node-a)에는 로컬 연결이 하나도 없다
+    const presenceStore = new InMemoryWebSocketPresenceStore();
+    await presenceStore.register({
+      sessionId: "remote-1",
+      nodeId: "node-b",
+      namespace: "chat",
+      active: true,
+      connectedAt: new Date(),
+    });
+    await presenceStore.join("remote-1", "room-1");
+    clusterBus = new RecordingClusterBus();
+    runtime = createWebSocketRuntime({ nodeId: "node-a", presenceStore, clusterBus });
+    Sonamu.websocketRuntime = runtime;
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    await Promise.all(servers.splice(0).map((server) => server.close()));
+    Sonamu.restoreTestingSnapshot(originalState);
+    Sonamu.isInitialized = originalInitialized;
+    if (originalNodeEnv === undefined) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = originalNodeEnv;
+    }
+    vi.restoreAllMocks();
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  function setApis(apis: ExtendedApi[]): void {
+    Reflect.set(Sonamu, "syncerValue", {
+      apis,
+      models: { ChatFrame: {}, NoticeFrame: {}, AlertFrame: {} },
+      types: {},
+    });
+  }
+
+  async function startServer(environment: "production" | "test"): Promise<FastifyInstance> {
+    process.env.NODE_ENV = environment;
+    const server = Fastify();
+    servers.push(server);
+    await Sonamu.withFastify(server, config, { doSilent: true, enableSync: false });
+    return server;
+  }
+
+  // 서버 측 publish 결과로 이 노드의 route table을 관찰한다
+  async function publishAndCollectFrames(
+    event: string,
+    data: ServerPublishData,
+  ): Promise<Record<string, string> | undefined> {
+    const before = clusterBus.published.length;
+    await runtime.publishToRoom("room-1", event, data, "chat");
+    await flushAsync();
+    const published = clusterBus.published.slice(before);
+    expect(published.length).toBeLessThanOrEqual(1);
+    return published[0]?.frames;
+  }
+
+  for (const environment of ["production", "test"] as const) {
+    const label =
+      environment === "production" ? "프로덕션 route 등록 경로" : "dev/HMR catch-all 경로";
+
+    it(`${label}: 시작 시 모든 @websocket route의 outEvents가 api.path 키로 등록돼, 로컬 연결이 없어도 원격 수신자용 frame을 만든다`, async () => {
+      setApis([chatApi(ChatEventsV1), noticeApi]);
+
+      const server = await startServer(environment);
+
+      // 의도한 등록 경로를 실제로 탔는지 확인한다 (프로덕션은 route별 등록, dev는 catch-all)
+      if (environment === "production") {
+        expect(server.hasRoute({ method: "GET", url: "/api/chat/subscribe" })).toBe(true);
+        expect(server.hasRoute({ method: "GET", url: "/api/notice/subscribe" })).toBe(true);
+      } else {
+        expect(server.hasRoute({ method: "GET", url: "/api/*" })).toBe(true);
+      }
+
+      const chatFrames = await publishAndCollectFrames("onMessage", { text: "hi", extra: 1 });
+      expect(chatFrames).toBeDefined();
+      expect(Object.keys(chatFrames ?? {})).toEqual(["/chat/subscribe"]);
+      expect(JSON.parse(chatFrames?.["/chat/subscribe"] ?? "null")).toEqual({
+        event: "onMessage",
+        data: { text: "hi" },
+      });
+
+      const noticeFrames = await publishAndCollectFrames("onNotice", { level: 2 });
+      expect(Object.keys(noticeFrames ?? {})).toEqual(["/notice/subscribe"]);
+      expect(JSON.parse(noticeFrames?.["/notice/subscribe"] ?? "null")).toEqual({
+        event: "onNotice",
+        data: { level: 2 },
+      });
+    });
+  }
+
+  it("HMR refresh 뒤에는 바뀐 스키마로 인코딩하고, 제거된 route는 빠지고, 추가된 route는 포함된다", async () => {
+    setApis([chatApi(ChatEventsV1), noticeApi]);
+    await startServer("test");
+
+    // syncer HMR 사이클과 같은 순서: API를 다시 읽은 뒤 refreshHttpValidators를 호출한다
+    setApis([chatApi(ChatEventsV2), alertApi]);
+    await Sonamu.refreshHttpValidators();
+
+    const chatFrames = await publishAndCollectFrames("onMessage", { text: "hi" });
+    expect(JSON.parse(chatFrames?.["/chat/subscribe"] ?? "null")).toEqual({
+      event: "onMessage",
+      data: { text: "hi", edited: true },
+    });
+
+    const noticeFrames = await publishAndCollectFrames("onNotice", { level: 2 });
+    expect(noticeFrames?.["/notice/subscribe"]).toBeUndefined();
+
+    const alertFrames = await publishAndCollectFrames("onAlert", { message: "fire" });
+    expect(Object.keys(alertFrames ?? {})).toEqual(["/alert/subscribe"]);
+    expect(JSON.parse(alertFrames?.["/alert/subscribe"] ?? "null")).toEqual({
+      event: "onAlert",
+      data: { message: "fire" },
+    });
+  });
+
+  it("HMR refresh로 스키마가 바뀌면 이전 스키마로만 유효한 payload는 더 이상 인코딩되지 않는다", async () => {
+    const StrictV2 = z.object({ onMessage: z.object({ text: z.string().max(3) }) });
+    setApis([chatApi(ChatEventsV1)]);
+    await startServer("test");
+
+    const before = await publishAndCollectFrames("onMessage", { text: "long text" });
+    expect(before?.["/chat/subscribe"]).toBeDefined();
+
+    setApis([chatApi(StrictV2)]);
+    await Sonamu.refreshHttpValidators();
+
+    const after = await publishAndCollectFrames("onMessage", { text: "long text" });
+    expect(after?.["/chat/subscribe"]).toBeUndefined();
+  });
+});

package/src/api/__tests__/sonamu.websocket.test.ts

@@ -3,17 +3,16 @@ import { describe, expect, it, vi } from "vitest";
 import { type WebSocket } from "ws";
 import { z } from "zod";
 
-import {
-  type AnyWebSocketConnection,
-  type WebSocketConnection,
-  WebSocketRuntime,
-} from "../../stream/ws";
+import { type WebSocketConnection, WebSocketRuntime } from "../../stream/ws";
 import { type WebSocketTelemetryConnectionContext } from "../../stream/ws-telemetry";
 import { type SonamuFastifyConfig } from "../../types/types";
 import { type WebSocketContext } from "../context";
 import { type ExtendedApi } from "../decorators";
 import { Sonamu } from "../sonamu";
 
+// runtime.registerConnection이 돌려주는 연결 타입. spy 대역도 이 타입으로 만들어야 한다
+type RuntimeWebSocketConnection = Awaited<ReturnType<WebSocketRuntime["registerConnection"]>>;
+
 interface TestWebSocketMessage {
   roomId?: string;
 }
@@ -25,7 +24,7 @@ interface TestWebSocketEvents {
 describe("Sonamu websocket context scoping", () => {
   it("웹소켓 컨텍스트를 생성한 뒤 해당 컨텍스트 안에서 guard를 실행한다", async () => {
     const executionOrder: string[] = [];
-    const rawWs: AnyWebSocketConnection = {
+    const rawWs: RuntimeWebSocketConnection = {
       id: "ws-guard",
       namespace: "chat",
       transport: "ws" as const,
@@ -38,10 +37,18 @@ describe("Sonamu websocket context scoping", () => {
       waitForClose() {
         return Promise.resolve();
       },
-      join() {},
-      leave() {},
-      setUserId() {},
-      clearUserId() {},
+      join() {
+        return Promise.resolve();
+      },
+      leave() {
+        return Promise.resolve();
+      },
+      setUserId() {
+        return Promise.resolve();
+      },
+      clearUserId() {
+        return Promise.resolve();
+      },
     };
     const runtime = new WebSocketRuntime({ nodeId: "websocket-guard-test" });
     const originalState = Sonamu.captureTestingSnapshot();
@@ -49,8 +56,8 @@ describe("Sonamu websocket context scoping", () => {
     let guardContext: WebSocketContext | null = null;
     let guardTransport: WebSocketContext["transport"] | null = null;
 
-    vi.spyOn(runtime, "registerConnection").mockReturnValue(rawWs);
-    vi.spyOn(runtime, "activateConnection").mockImplementation(() => {
+    vi.spyOn(runtime, "registerConnection").mockResolvedValue(rawWs);
+    vi.spyOn(runtime, "activateConnection").mockImplementation(async () => {
       executionOrder.push("activate");
     });
     vi.spyOn(Sonamu, "createWebSocketContext").mockImplementation(async (_config, request, ws) => {
@@ -144,10 +151,18 @@ describe("Sonamu websocket context scoping", () => {
       waitForClose() {
         return Promise.resolve();
       },
-      join() {},
-      leave() {},
-      setUserId() {},
-      clearUserId() {},
+      join() {
+        return Promise.resolve();
+      },
+      leave() {
+        return Promise.resolve();
+      },
+      setUserId() {
+        return Promise.resolve();
+      },
+      clearUserId() {
+        return Promise.resolve();
+      },
     };
 
     let context: WebSocketContext<TestWebSocketEvents, TestWebSocketEvents> | null = null;
@@ -201,10 +216,18 @@ describe("Sonamu websocket context scoping", () => {
       waitForClose() {
         return Promise.resolve();
       },
-      join() {},
-      leave() {},
-      setUserId() {},
-      clearUserId() {},
+      join() {
+        return Promise.resolve();
+      },
+      leave() {
+        return Promise.resolve();
+      },
+      setUserId() {
+        return Promise.resolve();
+      },
+      clearUserId() {
+        return Promise.resolve();
+      },
     };
 
     let context: WebSocketContext<TestWebSocketEvents, TestWebSocketEvents> | null = null;
@@ -243,4 +266,202 @@ describe("Sonamu websocket context scoping", () => {
 
     expect(seenTraceContext).toEqual(messageTraceContext);
   });
+
+  it("핸들러는 registerConnection과 activateConnection이 끝날 때까지 기다리며 context → guard → activate → handler 순서를 지킨다", async () => {
+    const executionOrder: string[] = [];
+    const rawWs: RuntimeWebSocketConnection = {
+      id: "ws-async",
+      namespace: "chat",
+      transport: "ws" as const,
+      closed: false,
+      publishUntyped() {},
+      close() {},
+      onClose() {},
+      onMessage() {},
+      publish() {},
+      waitForClose() {
+        return Promise.resolve();
+      },
+      join() {
+        return Promise.resolve();
+      },
+      leave() {
+        return Promise.resolve();
+      },
+      setUserId() {
+        return Promise.resolve();
+      },
+      clearUserId() {
+        return Promise.resolve();
+      },
+    };
+    const runtime = new WebSocketRuntime({ nodeId: "websocket-async-test" });
+    const originalState = Sonamu.captureTestingSnapshot();
+    let releaseRegister!: () => void;
+    let releaseActivate!: () => void;
+    const registerGate = new Promise<void>((resolve) => {
+      releaseRegister = resolve;
+    });
+    const activateGate = new Promise<void>((resolve) => {
+      releaseActivate = resolve;
+    });
+
+    const registerSpy = vi.spyOn(runtime, "registerConnection").mockImplementation(async () => {
+      executionOrder.push("register:start");
+      await registerGate;
+      executionOrder.push("register:end");
+      return rawWs;
+    });
+    const activateSpy = vi
+      .spyOn(runtime, "activateConnection")
+      .mockImplementation(async (connectionId) => {
+        executionOrder.push(`activate:start:${connectionId}`);
+        await activateGate;
+        executionOrder.push("activate:end");
+      });
+    vi.spyOn(Sonamu, "createWebSocketContext").mockImplementation(async (_config, request, ws) => {
+      executionOrder.push("context");
+      return {
+        transport: "ws",
+        request,
+        headers: request.headers,
+        ws,
+        naiteStore: new Map(),
+        locale: "ko",
+        user: null,
+        session: null,
+      };
+    });
+    vi.spyOn(Sonamu, "invokeModelMethod").mockImplementation(async () => {
+      executionOrder.push("handler");
+    });
+
+    const config = /* SAFETY: 테스트는 guardHandler와 contextProvider만 사용한다. */ {
+      guardHandler() {
+        executionOrder.push("guard");
+      },
+      contextProvider(defaultContext) {
+        return defaultContext;
+      },
+    } as SonamuFastifyConfig;
+    const api: ExtendedApi = {
+      modelName: "ChatFrame",
+      methodName: "subscribe",
+      path: "/chat/subscribe",
+      options: { guards: ["user"] },
+      websocketOptions: {
+        outEvents: z.object({}),
+        inEvents: z.object({}),
+        namespace: "chat",
+      },
+      typeParameters: [],
+      parameters: [],
+      returnType: "void",
+    };
+    const request = /* SAFETY: 테스트는 headers와 query만 읽는다. */ {
+      headers: {},
+      query: {},
+    } as FastifyRequest;
+    const socket =
+      /* SAFETY: registerConnection이 mock이라 소켓 메서드는 호출되지 않는다. */ {} as WebSocket;
+    try {
+      Sonamu.websocketRuntime = runtime;
+      Reflect.set(Sonamu, "syncerValue", { types: {} });
+
+      let handlerDone = false;
+      const handling = Sonamu.createWebSocketHandlerForTesting(api, config)(
+        { socket },
+        request,
+      ).then(() => {
+        handlerDone = true;
+      });
+      await new Promise<void>((resolve) => setImmediate(resolve));
+
+      // 등록이 끝나기 전에는 context를 만들지 않는다
+      expect(executionOrder).toEqual(["register:start"]);
+
+      releaseRegister();
+      await new Promise<void>((resolve) => setImmediate(resolve));
+
+      // 활성화가 끝나기 전에는 handler를 실행하지 않는다
+      expect(executionOrder).toEqual([
+        "register:start",
+        "register:end",
+        "context",
+        "guard",
+        "activate:start:ws-async",
+      ]);
+      expect(handlerDone).toBe(false);
+
+      releaseActivate();
+      await handling;
+
+      expect(executionOrder).toEqual([
+        "register:start",
+        "register:end",
+        "context",
+        "guard",
+        "activate:start:ws-async",
+        "activate:end",
+        "handler",
+      ]);
+      expect(registerSpy).toHaveBeenCalledWith(
+        socket,
+        expect.objectContaining({
+          routeKey: "/chat/subscribe",
+          namespace: "chat",
+          active: false,
+        }),
+      );
+      expect(activateSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      Sonamu.restoreTestingSnapshot(originalState);
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("scoped 연결의 join/leave/setUserId/clearUserId는 원본 연결의 promise를 그대로 반환한다", async () => {
+    const joinPromise = Promise.resolve();
+    const leavePromise = Promise.resolve();
+    const setUserIdPromise = Promise.resolve();
+    const clearUserIdPromise = Promise.resolve();
+    const calls: string[] = [];
+    const rawWs: WebSocketConnection<TestWebSocketEvents, TestWebSocketEvents> = {
+      id: "ws-scoped",
+      namespace: "chat",
+      transport: "ws" as const,
+      closed: false,
+      publishUntyped() {},
+      close() {},
+      onClose() {},
+      onMessage() {},
+      publish() {},
+      waitForClose() {
+        return Promise.resolve();
+      },
+      join(roomId) {
+        calls.push(`join:${roomId}`);
+        return joinPromise;
+      },
+      leave(roomId) {
+        calls.push(`leave:${roomId}`);
+        return leavePromise;
+      },
+      setUserId(userId) {
+        calls.push(`setUserId:${JSON.stringify(userId)}`);
+        return setUserIdPromise;
+      },
+      clearUserId() {
+        calls.push("clearUserId");
+        return clearUserIdPromise;
+      },
+    };
+    const scopedWs = Sonamu.createScopedWebSocketConnectionForTesting(rawWs, () => null);
+
+    expect(scopedWs.join("room-1")).toBe(joinPromise);
+    expect(scopedWs.leave("room-1")).toBe(leavePromise);
+    expect(scopedWs.setUserId(1)).toBe(setUserIdPromise);
+    expect(scopedWs.clearUserId()).toBe(clearUserIdPromise);
+    expect(calls).toEqual(["join:room-1", "leave:room-1", "setUserId:1", "clearUserId"]);
+  });
 });

package/src/api/sonamu.ts

@@ -1331,6 +1331,16 @@ class SonamuClass {
     this.aotHttpValidatorRegistry = nextAotRegistry;
     this.preparedApis = nextApis;
     this.preparedModels = nextModels;
+
+    // @websocket route의 outEvents를 api.path 키로 route table에 반영한다.
+    // 발행 노드가 route별로 한 번 인코딩한 frame을 원격 노드가 그대로 보내므로, HMR 뒤에도 최신 스키마를 써야 한다
+    this.websocketRuntimeValue?.replaceRoutes(
+      nextApis.flatMap((api) =>
+        api.websocketOptions
+          ? [{ routeKey: api.path, outEvents: api.websocketOptions.outEvents }]
+          : [],
+      ),
+    );
   }
 
   // WS path를 일반 HTTP GET으로 호출한 경우 426 + Upgrade 헤더로 명시적으로 websocket 접속을 유도함
@@ -1391,7 +1401,7 @@ class SonamuClass {
     ): Promise<void> => {
       const socket = connection.socket;
       let wsContext: WebSocketContext<object, object> | null = null;
-      let rawWs: ReturnType<WebSocketRuntime["registerConnection"]> | null = null;
+      let rawWs: Awaited<ReturnType<WebSocketRuntime["registerConnection"]>> | null = null;
       let preRegisterPhase: "guard" | "query" | "register" | "handler" = "guard";
       let traceContext: WebSocketTelemetryConnectionContext = {};
 
@@ -1403,7 +1413,9 @@ class SonamuClass {
         preRegisterPhase = "query";
         const reqBody = await this.parseWebSocketRequestParams(api, request);
         preRegisterPhase = "register";
-        rawWs = this.websocketRuntime.registerConnection(socket, {
+        // 등록(store 반영 포함)이 끝난 뒤에 context/guard를 진행한다. 리스너는 등록 중에도 붙어 있어 close를 놓치지 않는다
+        rawWs = await this.websocketRuntime.registerConnection(socket, {
+          routeKey: api.path,
           outEvents: api.websocketOptions!.outEvents,
           inEvents: api.websocketOptions!.inEvents,
           namespace: api.websocketOptions!.namespace,
@@ -1427,7 +1439,8 @@ class SonamuClass {
           });
         });
 
-        this.websocketRuntime.activateConnection(rawWs.id);
+        // 활성화가 store에 반영된 뒤 handler를 실행해 handler 안의 publish가 이 연결을 대상으로 잡게 한다
+        await this.websocketRuntime.activateConnection(rawWs.id);
         preRegisterPhase = "handler";
 
         const { ApiParamType } = await import("../types/types");
@@ -1604,16 +1617,16 @@ class SonamuClass {
         return ws.waitForClose();
       },
       join(roomId) {
-        ws.join(roomId);
+        return ws.join(roomId);
       },
       leave(roomId) {
-        ws.leave(roomId);
+        return ws.leave(roomId);
       },
       setUserId(userId) {
-        ws.setUserId(userId);
+        return ws.setUserId(userId);
       },
       clearUserId() {
-        ws.clearUserId();
+        return ws.clearUserId();
       },
     };
   }

package/src/index.ts

@@ -39,6 +39,7 @@ export * from "./stream/ws-audience";
 export * from "./stream/ws-cluster-bus";
 export * from "./stream/ws-core";
 export * from "./stream/ws-presence-store";
+export * from "./stream/ws-session-id";
 export * from "./stream/ws";
 export * from "./stream/ws-registry";
 export * from "./tasks/decorator";