sonamu 0.12.0 → 0.13.1

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

@@ -111,10 +111,7 @@ describe("Sonamu websocket context scoping", () => {
       Reflect.set(Sonamu, "syncerValue", { types: {} });
 
       await Sonamu.createWebSocketHandlerForTesting(api, config)(
-        {
-          socket:
-            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ {} as WebSocket,
-        },
+        /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ {} as WebSocket,
         request,
       );
 
@@ -369,12 +366,11 @@ describe("Sonamu websocket context scoping", () => {
       Reflect.set(Sonamu, "syncerValue", { types: {} });
 
       let handlerDone = false;
-      const handling = Sonamu.createWebSocketHandlerForTesting(api, config)(
-        { socket },
-        request,
-      ).then(() => {
-        handlerDone = true;
-      });
+      const handling = Sonamu.createWebSocketHandlerForTesting(api, config)(socket, request).then(
+        () => {
+          handlerDone = true;
+        },
+      );
       await new Promise<void>((resolve) => setImmediate(resolve));
 
       // 등록이 끝나기 전에는 context를 만들지 않는다

package/src/api/config.ts

@@ -201,7 +201,7 @@ export type SonamuServerOptions = {
   // 프로젝트 외부에서 접근할 수 있는 URL. 기본값은 {server.listen.host}:{server.listen.port} 입니다.
   baseUrl?: string;
 
-  fastify?: Omit<FastifyServerOptions, "logger">;
+  fastify?: Omit<FastifyServerOptions, "logger" | "loggerInstance">;
 
   listen?: {
     port: number;

package/src/api/context.ts

@@ -1,13 +1,7 @@
-import {
-  type IncomingHttpHeaders,
-  type IncomingMessage,
-  type Server,
-  type ServerResponse,
-} from "http";
+import { type IncomingHttpHeaders } from "http";
 
 import { type Session, type User } from "better-auth";
 import { type FastifyReply, type FastifyRequest } from "fastify";
-import { type RouteGenericInterface } from "fastify/types/route";
 import { type ZodObject } from "zod";
 
 import { type NaiteStore } from "../naite/naite";
@@ -32,7 +26,7 @@ type BaseContext = {
 
 export type Context = BaseContext & {
   transport: "http";
-  reply: FastifyReply<Server, IncomingMessage, ServerResponse, RouteGenericInterface>;
+  reply: FastifyReply;
   createSSE: <T extends ZodObject>(events: T) => ReturnType<typeof createSSEFactory<T>>;
   /** buffer 모드에서 업로드된 파일 */
   bufferedFiles?: BufferedFile[];

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);
@@ -1380,7 +1390,7 @@ class SonamuClass {
     }
 
     const handler = this.createWebSocketHandler(matchedApi, config);
-    await handler({ socket }, request);
+    await handler(socket, request);
   }
 
   // WS route 핸들러의 실행 순서를 고정함:
@@ -1393,13 +1403,8 @@ 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: Awaited<ReturnType<WebSocketRuntime["registerConnection"]>> | null = null;
       let preRegisterPhase: "guard" | "query" | "register" | "handler" = "guard";

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/template/implementations/model.template.ts

@@ -33,9 +33,9 @@ export class Template__model extends Template {
     const listParamsNode = zodTypeToRenderingNode(listParamsZodType);
 
     const subsetKeyZodType = await getZodTypeById(`${entityId}SubsetKey`);
-    const subsetKeys =
-      /* SAFETY: 생성된 *SubsetKey 타입은 enum 스키마로 등록된다. */ (subsetKeyZodType as z.ZodEnum)
-        .enum;
+    const subsetKeys = /* SAFETY: 생성된 *SubsetKey 타입은 enum 스키마로 등록된다. */ (
+      subsetKeyZodType as z.ZodEnum
+    ).enum;
 
     const names = EntityManager.getNamesFromId(entityId);
     const entity = EntityManager.get(entityId);

package/src/template/implementations/view_list.template.ts

@@ -305,20 +305,19 @@ export class Template__view_list extends Template {
       });
 
     // 필터 컬럼
-    const filterColumns =
-      /* SAFETY: ListParams 렌더링 노드의 자식은 모두 필터 컬럼 노드다. */ (
-        listParamsNode.children as RenderingNode[]
+    const filterColumns = /* SAFETY: ListParams 렌더링 노드의 자식은 모두 필터 컬럼 노드다. */ (
+      listParamsNode.children as RenderingNode[]
+    )
+      .filter(
+        (col) =>
+          col.name !== "id" &&
+          col.name !== "queryMode" &&
+          ["enums", "number-id", "number-fk_id", "string-fk_id"].includes(col.renderType),
       )
-        .filter(
-          (col) =>
-            col.name !== "id" &&
-            col.name !== "queryMode" &&
-            ["enums", "number-id", "number-fk_id", "string-fk_id"].includes(col.renderType),
-        )
-        // orderBy가 가장 뒤로 오게 순서 조정
-        .toSorted((a) => {
-          return a.name === "orderBy" ? 1 : -1;
-        });
+      // orderBy가 가장 뒤로 오게 순서 조정
+      .toSorted((a) => {
+        return a.name === "orderBy" ? 1 : -1;
+      });
 
     // 필터 컬럼을 프리 템플릿으로 설정
     const preTemplates: RenderedTemplate["preTemplates"] = [];

package/src/ui/ai-api.ts

@@ -24,7 +24,8 @@ export async function setAiApi(server: FastifyInstance) {
     const result = aiClient.handleFixture(await convertToModelMessages(messages), fixtureRecords);
     const response = result.toUIMessageStreamResponse();
 
-    reply.raw.writeHead(response.status, Object.fromEntries(Object.entries(response.headers)));
+    // ai 7의 Response.headers는 Headers 인스턴스라 entries()로 풀어야 Node 응답 헤더로 전달된다
+    reply.raw.writeHead(response.status, Object.fromEntries(response.headers.entries()));
 
     if (response.body) {
       const reader = response.body.getReader();
@@ -49,7 +50,8 @@ export async function setAiApi(server: FastifyInstance) {
     const result = aiClient.handleEntity(await convertToModelMessages(messages));
     const response = result.toUIMessageStreamResponse();
 
-    reply.raw.writeHead(response.status, Object.fromEntries(Object.entries(response.headers)));
+    // ai 7의 Response.headers는 Headers 인스턴스라 entries()로 풀어야 Node 응답 헤더로 전달된다
+    reply.raw.writeHead(response.status, Object.fromEntries(response.headers.entries()));
 
     if (response.body) {
       const reader = response.body.getReader();

package/src/ui/ai-client.ts

@@ -52,7 +52,7 @@ class AIClient {
   handleFixture(
     messages: ModelMessage[],
     fixtureRecords: FixtureRecord[],
-  ): StreamTextResult<any, any> {
+  ): StreamTextResult<any, any, any> {
     if (!this.aiSdk || !this.model) {
       throw new Error("AI SDK not initialized. Call init() first.");
     }
@@ -253,7 +253,7 @@ class AIClient {
     });
   }
 
-  handleEntity(messages: ModelMessage[]): StreamTextResult<any, any> {
+  handleEntity(messages: ModelMessage[]): StreamTextResult<any, any, any> {
     if (!this.aiSdk || !this.model) {
       throw new Error("AI SDK not initialized. Call init() first.");
     }

package/src/ui/api.ts

@@ -323,54 +323,52 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           filter?: "enums" | "types";
           reload?: "1";
         };
-      }>(
-        "/api/entity/typeIds",
-        (request): Promise<{ typeIds: string[] }> =>
-          forwardAsyncErrors(async () => {
-            const { filter, reload } = request.query;
-
-            if (reload === "1") {
-              await Sonamu.syncer.autoloadTypes();
-            }
+      }>("/api/entity/typeIds", (request): Promise<{ typeIds: string[] }> =>
+        forwardAsyncErrors(async () => {
+          const { filter, reload } = request.query;
 
-            const typeIds = (() => {
-              // 프로젝트에서 정의한 타입들
-              const projectTypeIds = Object.entries(Sonamu.syncer.types)
-                .filter(([_typeId, zodType]) => {
-                  const { _zod: zodMetadata } = zodType;
-                  return (
-                    /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ (zodMetadata
-                      .def.type as string) !== "enum"
-                  );
-                })
-                .map(([typeId, _zodType]) => typeId);
-
-              // 내장 타입들 (sonamu 코어에서 제공)
-              const builtInTypeIds = [...BUILT_IN_TYPE_IDS];
-
-              // 모든 타입 병합
-              const allTypeIds = [...builtInTypeIds, ...projectTypeIds];
-
-              if (filter === "types") {
-                return allTypeIds;
-              }
+          if (reload === "1") {
+            await Sonamu.syncer.autoloadTypes();
+          }
 
-              const enumIds = EntityManager.getAllIds().flatMap((entityId) => {
-                const entity = EntityManager.get(entityId);
-                return Object.keys(entity.enumLabels);
-              });
+          const typeIds = (() => {
+            // 프로젝트에서 정의한 타입들
+            const projectTypeIds = Object.entries(Sonamu.syncer.types)
+              .filter(([_typeId, zodType]) => {
+                const { _zod: zodMetadata } = zodType;
+                return (
+                  /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ (zodMetadata
+                    .def.type as string) !== "enum"
+                );
+              })
+              .map(([typeId, _zodType]) => typeId);
 
-              if (filter === "enums") {
-                return enumIds;
-              } else {
-                return [...allTypeIds, ...enumIds];
-              }
-            })();
+            // 내장 타입들 (sonamu 코어에서 제공)
+            const builtInTypeIds = [...BUILT_IN_TYPE_IDS];
 
-            return {
-              typeIds,
-            };
-          }),
+            // 모든 타입 병합
+            const allTypeIds = [...builtInTypeIds, ...projectTypeIds];
+
+            if (filter === "types") {
+              return allTypeIds;
+            }
+
+            const enumIds = EntityManager.getAllIds().flatMap((entityId) => {
+              const entity = EntityManager.get(entityId);
+              return Object.keys(entity.enumLabels);
+            });
+
+            if (filter === "enums") {
+              return enumIds;
+            } else {
+              return [...allTypeIds, ...enumIds];
+            }
+          })();
+
+          return {
+            typeIds,
+          };
+        }),
       );
 
       server.post<{
@@ -902,25 +900,23 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             enumId?: string;
           };
         };
-      }>(
-        "/api/scaffolding/preview",
-        (request): Promise<{ pathAndCodes: PathAndCode[] }> =>
-          forwardAsyncErrors(async () => {
-            const { option } = request.body;
-
-            try {
-              const { templateKey, ...templateOptions } = option;
-              const pathAndCodes = await Sonamu.syncer.renderTemplate(
-                /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ templateKey as TemplateKey,
-                templateOptions,
-              );
+      }>("/api/scaffolding/preview", (request): Promise<{ pathAndCodes: PathAndCode[] }> =>
+        forwardAsyncErrors(async () => {
+          const { option } = request.body;
 
-              return { pathAndCodes };
-            } catch (e) {
-              console.error(e);
-              throw e;
-            }
-          }),
+          try {
+            const { templateKey, ...templateOptions } = option;
+            const pathAndCodes = await Sonamu.syncer.renderTemplate(
+              /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ templateKey as TemplateKey,
+              templateOptions,
+            );
+
+            return { pathAndCodes };
+          } catch (e) {
+            console.error(e);
+            throw e;
+          }
+        }),
       );
 
       server.post("/api/fixture", (request) =>