sonamu 0.11.16 → 0.13.0

package/src/api/sonamu.ts

@@ -9,7 +9,12 @@ import { dispose as logtapeDispose } from "@logtape/logtape";
 import { type Auth, type BetterAuthOptions } from "better-auth";
 import chalk from "chalk";
 import { type FSWatcher } from "chokidar";
-import { type FastifyInstance, type FastifyReply, type FastifyRequest } from "fastify";
+import {
+  type FastifyBaseLogger,
+  type FastifyInstance,
+  type FastifyReply,
+  type FastifyRequest,
+} from "fastify";
 import mime, { lookup as mimeLookup } from "mime-types";
 import { type WebSocket } from "ws";
 import { type ZodObject } from "zod";
@@ -470,14 +475,17 @@ class SonamuClass {
     const options = this.config.server;
     const { default: fastify } = await import("fastify");
     const { getLogTapeFastifyLogger } = await import("@logtape/fastify");
+    // Fastify 5는 logger 옵션에 설정 객체만 받고, 로거 인스턴스는 loggerInstance로 넘겨야 한다
+    // SAFETY: LogTape 어댑터는 pino 호환 메서드 집합(trace~fatal, silent, child)을 제공하며 Fastify 4에서도 같은 객체를 logger로 넘겨 동작했다.
+    const loggerInstance: FastifyBaseLogger | undefined =
+      this.config.logging !== false
+        ? (getLogTapeFastifyLogger({
+            category: this.config.logging?.fastifyCategory ?? ["fastify"],
+          }) as FastifyBaseLogger)
+        : undefined;
     const server = fastify({
       ...options.fastify,
-      logger:
-        this.config.logging !== false
-          ? getLogTapeFastifyLogger({
-              category: this.config.logging?.fastifyCategory ?? ["fastify"],
-            })
-          : undefined,
+      loggerInstance,
     });
     this.server = server;
     this.websocketRuntime = new WebSocketRuntime(options.websocket);
@@ -714,13 +722,14 @@ class SonamuClass {
         // 등록된 API와 일치하지 않는 요청에 대한 fallback입니다.
         throw new NotFoundException(SD("error.api.notFound"));
       },
-      wsHandler: async (connection, request) => {
-        await this.handleDevWebSocketRequest(connection.socket, request, config);
+      wsHandler: async (socket, request) => {
+        await this.handleDevWebSocketRequest(socket, request, config);
       },
     });
 
+    // HEAD는 위 GET catch-all이 exposeHeadRoutes로 자동 노출하므로 중복 선언하면 Fastify 5가 FST_ERR_DUPLICATED_ROUTE를 던진다
     server.route({
-      method: ["HEAD", "POST", "PUT", "DELETE", "PATCH"],
+      method: ["POST", "PUT", "DELETE", "PATCH"],
       url: `${this.config.api.route.prefix}/*`,
       handler: async (request, reply) => {
         const handler = await this.handleDevApiRequest(request, config);
@@ -784,13 +793,14 @@ class SonamuClass {
         }
         throw new NotFoundException(SD("error.api.notFound"));
       },
-      wsHandler: async (connection, request) => {
-        await this.handleDevWebSocketRequest(connection.socket, request, config);
+      wsHandler: async (socket, request) => {
+        await this.handleDevWebSocketRequest(socket, request, config);
       },
     });
 
+    // HEAD는 위 GET catch-all이 exposeHeadRoutes로 자동 노출하므로 중복 선언하면 Fastify 5가 FST_ERR_DUPLICATED_ROUTE를 던진다
     server.route({
-      method: ["HEAD", "POST", "PUT", "DELETE", "PATCH"],
+      method: ["POST", "PUT", "DELETE", "PATCH"],
       url: `${this.config.api.route.prefix}/*`,
       handler: async (request, reply) => {
         const result = await this.handleDevApiRequest(request, config);
@@ -1331,6 +1341,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 접속을 유도함
@@ -1370,7 +1390,7 @@ class SonamuClass {
     }
 
     const handler = this.createWebSocketHandler(matchedApi, config);
-    await handler({ socket }, request);
+    await handler(socket, request);
   }
 
   // WS route 핸들러의 실행 순서를 고정함:
@@ -1383,15 +1403,10 @@ class SonamuClass {
   }
 
   private createWebSocketHandler(api: ExtendedApi, config: SonamuFastifyConfig) {
-    return async (
-      connection: {
-        socket: WebSocket;
-      },
-      request: FastifyRequest,
-    ): Promise<void> => {
-      const socket = connection.socket;
+    // @fastify/websocket 11부터 wsHandler는 connection 래퍼 대신 ws.WebSocket을 직접 전달한다
+    return async (socket: WebSocket, request: FastifyRequest): Promise<void> => {
       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 +1418,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 +1444,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 +1622,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/auth/audit-log/plugin.ts

@@ -85,6 +85,8 @@ const getOrganizationTriggerInfo = (user: { id?: string } | null | undefined): B
 type BetterAuthRequestCtx = GenericEndpointContext & {
   context: GenericEndpointContext["context"] & {
     location?: BuilderLocation | null;
+    // after hook에서 dispatch가 채우는 응답값. better-auth 1.6.2x부터 GenericEndpointContext 타입에서 빠졌지만 HookEndpointContext에는 남아 있다.
+    returned?: unknown;
   };
 };
 

package/src/compress/types.ts

@@ -14,7 +14,7 @@ export type CompressOptions = {
   /** 압축을 적용할 최소 바이트 크기 (기본값: 1024) */
   threshold?: number;
   /** 사용할 인코딩 우선순위 (기본값: ["br", "gzip", "deflate"]) */
-  encodings?: ("br" | "gzip" | "deflate" | "identity")[];
+  encodings?: ("zstd" | "br" | "gzip" | "deflate" | "identity")[];
   /** 압축할 Content-Type 필터 */
   customTypes?: RegExp | ((contentType: string) => boolean);
 };

package/src/exceptions/error-handler.ts

@@ -1,4 +1,4 @@
-import { type FastifyInstance } from "fastify";
+import { type FastifyError, type FastifyInstance } from "fastify";
 import type z from "zod";
 
 import { isObjectValue, isStringValue } from "../utils/runtime-value";
@@ -19,7 +19,8 @@ function isZodIssuePayload<Value>(payload: Value): payload is Value & z.core.$Zo
 }
 
 export function setupErrorHandler(server: FastifyInstance) {
-  server.setErrorHandler((error, request, reply) => {
+  // Fastify 5는 error 타입 기본값이 unknown이므로 기존 FastifyError 계약을 명시한다
+  server.setErrorHandler<FastifyError>((error, request, reply) => {
     error.statusCode ??= 400;
 
     if (isSoException(error) && isZodIssuePayload(error.payload)) {

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";