sonamu 0.9.4 → 0.9.6

package/src/api/config.ts

@@ -3,6 +3,7 @@ import { type FastifyCorsOptions } from "@fastify/cors";
 import { type FastifyFormbodyOptions } from "@fastify/formbody";
 import { type FastifyMultipartOptions } from "@fastify/multipart";
 import { type FastifyStaticOptions } from "@fastify/static";
+import { type WebsocketPluginOptions } from "@fastify/websocket";
 import { type BetterAuthOptions } from "better-auth";
 import {
   type FastifyInstance,
@@ -18,9 +19,10 @@ import { type CacheConfig } from "../cache/types";
 import { type SonamuDBConfig } from "../database/db";
 import { type SonamuLoggingOptions } from "../logger/configure";
 import { type StorageConfig } from "../storage/types";
+import { type WebSocketRuntimeOptions } from "../stream/ws";
 import { type WorkflowOptions } from "../tasks/workflow-manager";
 import { type Executable, type SonamuFastifyConfig } from "../types/types";
-import { type Context } from "./context";
+import { type Context, type WebSocketContext } from "./context";
 
 export type DatabaseConfig = Omit<Knex.Config, "connection"> & {
   connection?: Knex.PgConnectionConfig;
@@ -180,6 +182,7 @@ export type SonamuServerOptions = {
     qs?: boolean | QsPluginOptions;
     sse?: boolean | SsePluginOptions;
     static?: boolean | FastifyStaticOptions;
+    ws?: boolean | WebsocketPluginOptions;
 
     custom?: (server: FastifyInstance) => void;
   };
@@ -200,6 +203,14 @@ export type SonamuServerOptions = {
     };
   };
 
+  /**
+   * WebSocket runtime 설정.
+   *
+   * 단일 인스턴스에서는 기본값으로 충분하며, 멀티 인스턴스/대규모 환경에서는
+   * presence store와 cluster bus를 여기서 주입합니다.
+   */
+  websocket?: WebSocketRuntimeOptions;
+
   apiConfig: SonamuFastifyConfig;
 
   /**
@@ -255,9 +266,24 @@ export type SonamuTaskOptions = {
   contextProvider: (
     defaultContext: Pick<
       Context,
-      "reply" | "request" | "headers" | "createSSE" | "naiteStore" | "locale" | "user" | "session"
+      | "transport"
+      | "reply"
+      | "request"
+      | "headers"
+      | "createSSE"
+      | "naiteStore"
+      | "locale"
+      | "user"
+      | "session"
     >,
   ) => Context | Promise<Context>;
+  websocketContextProvider?: (
+    defaultContext: Pick<
+      WebSocketContext,
+      "transport" | "request" | "headers" | "ws" | "naiteStore" | "locale" | "user" | "session"
+    >,
+    request: FastifyRequest,
+  ) => WebSocketContext | Promise<WebSocketContext>;
 };
 
 export type SonamuSSROptions = {

package/src/api/context.ts

@@ -14,24 +14,38 @@ import { type NaiteStore } from "../naite/naite";
 import { type BufferedFile } from "../storage/buffered-file";
 import { type UploadedFile } from "../storage/uploaded-file";
 import { type createSSEFactory } from "../stream/sse";
+import { type WebSocketConnection, type WebSocketEventMap } from "../stream/ws";
 
 // oxlint-disable-next-line @typescript-eslint/no-empty-interface -- Context 확장 타입
 export interface ContextExtend {}
-export type Context = {
+type BaseContext = {
   request: FastifyRequest;
-  reply: FastifyReply<Server, IncomingMessage, ServerResponse, RouteGenericInterface>;
   headers: IncomingHttpHeaders;
-  createSSE: <T extends ZodObject>(events: T) => ReturnType<typeof createSSEFactory<T>>;
   naiteStore: NaiteStore;
   /** 현재 요청의 locale */
   locale: string;
+  /** 현재 로그인한 사용자 (null이면 미인증) */
+  user: User | null;
+  /** 현재 세션 정보 (null이면 미인증) */
+  session: Session | null;
+};
+
+export type Context = BaseContext & {
+  transport: "http";
+  reply: FastifyReply<Server, IncomingMessage, ServerResponse, RouteGenericInterface>;
+  createSSE: <T extends ZodObject>(events: T) => ReturnType<typeof createSSEFactory<T>>;
   /** buffer 모드에서 업로드된 파일 */
   bufferedFiles?: BufferedFile[];
   /** stream 모드에서 업로드된 파일 */
   uploadedFiles?: UploadedFile[];
+} & ContextExtend;
 
-  /** 현재 로그인한 사용자 (null이면 미인증) */
-  user: User | null;
-  /** 현재 세션 정보 (null이면 미인증) */
-  session: Session | null;
+export type WebSocketContext<
+  TOut extends WebSocketEventMap = WebSocketEventMap,
+  TIn extends WebSocketEventMap = WebSocketEventMap,
+> = BaseContext & {
+  transport: "ws";
+  ws: WebSocketConnection<TOut, TIn>;
 } & ContextExtend;
+
+export type RuntimeContext = Context | WebSocketContext;

package/src/api/decorators.ts

@@ -61,6 +61,24 @@ export type StreamDecoratorOptions = {
   guards?: GuardKey[];
   description?: string;
 };
+export type WebSocketDecoratorOptions = {
+  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 이벤트 키별로 넘겨주는 값이므로 어떤 타입이든 상관없음
+  outEvents: z.ZodObject<any>;
+  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 이벤트 키별로 넘겨주는 값이므로 어떤 타입이든 상관없음
+  inEvents: z.ZodObject<any>;
+  path?: string;
+  resourceName?: string;
+  guards?: GuardKey[];
+  description?: string;
+  heartbeat?: number;
+  maxPayload?: number;
+  namespace?: string;
+};
+export type ResolvedWebSocketDecoratorOptions = WebSocketDecoratorOptions & {
+  // codegen이 타입 이름을 재사용할 수 있도록 syncer가 AST에서 보강하는 메타데이터
+  outEventsTypeRef?: ApiParamType.Ref;
+  inEventsTypeRef?: ApiParamType.Ref;
+};
 
 type BufferUploadOptions = {
   consume?: "buffer";
@@ -85,6 +103,7 @@ export const registeredApis: {
   path: string;
   options: ApiDecoratorOptions;
   streamOptions?: StreamDecoratorOptions;
+  websocketOptions?: ResolvedWebSocketDecoratorOptions;
   uploadOptions?: UploadDecoratorOptions;
 }[] = [];
 export type ExtendedApi = {
@@ -93,6 +112,7 @@ export type ExtendedApi = {
   path: string;
   options: ApiDecoratorOptions;
   streamOptions?: StreamDecoratorOptions;
+  websocketOptions?: ResolvedWebSocketDecoratorOptions;
   uploadOptions?: UploadDecoratorOptions;
   typeParameters: ApiParamType.TypeParam[];
   parameters: ApiParam[];
@@ -103,6 +123,7 @@ type DecoratorTarget = { constructor: { name: string } };
 const DECORATOR_TYPES = {
   API: Symbol("api"),
   STREAM: Symbol("stream"),
+  WEBSOCKET: Symbol("websocket"),
   UPLOAD: Symbol("upload"),
 } as const;
 
@@ -110,7 +131,7 @@ function checkSingleDecorator(target: DecoratorTarget, propertyKey: string, deco
   const method = target[propertyKey as keyof typeof target] as { __decoratorType?: symbol };
   if (method?.__decoratorType && method?.__decoratorType !== decoratorType) {
     throw new Error(
-      `@${decoratorType.description ?? String(decoratorType)} decorator can only be used once on ${target.constructor.name}.${propertyKey}. You can use only one of @api or @stream decorator on the same method.`,
+      `@${decoratorType.description ?? String(decoratorType)} decorator can only be used once on ${target.constructor.name}.${propertyKey}. You can use only one of @api, @stream, @websocket, or @upload decorator on the same method.`,
     );
   } else {
     method.__decoratorType = decoratorType;
@@ -278,6 +299,85 @@ export function stream(options: StreamDecoratorOptions) {
   };
 }
 
+export function websocket(options: WebSocketDecoratorOptions) {
+  return (target: DecoratorTarget, propertyKey: string, descriptor: PropertyDescriptor) => {
+    const modelName = target.constructor.name.match(/(.+)Class$/)?.[1];
+    assert(
+      modelName,
+      `modelName is required on @websocket decorator on ${target.constructor.name}.${propertyKey}`,
+    );
+    const methodName = propertyKey;
+
+    checkSingleDecorator(target, propertyKey, DECORATOR_TYPES.WEBSOCKET);
+
+    const defaultPath = `/${inflection.camelize(
+      modelName.replace(/Model$/, "").replace(/Frame$/, ""),
+      true,
+    )}/${inflection.camelize(propertyKey, true)}`;
+    const path = options.path ?? defaultPath;
+    const { outEvents: _outEvents, inEvents: _inEvents, ...apiOptions } = options;
+    const optionsWithDefaults = {
+      ...apiOptions,
+      httpMethod: "GET" as HTTPMethods,
+    };
+
+    const existingApi = registeredApis.find(
+      (api) => api.modelName === modelName && api.methodName === methodName,
+    );
+    if (existingApi) {
+      assertNoConflictingPath("websocket", modelName, methodName, existingApi.path, path);
+      existingApi.path = path;
+
+      assertNoConflictingOptions(
+        "websocket",
+        modelName,
+        methodName,
+        existingApi.options,
+        optionsWithDefaults,
+      );
+      existingApi.options = {
+        ...existingApi.options,
+        ...optionsWithDefaults,
+      };
+
+      existingApi.websocketOptions = options;
+    } else {
+      registeredApis.push({
+        modelName,
+        methodName,
+        path,
+        options: optionsWithDefaults,
+        websocketOptions: options,
+      });
+    }
+
+    const originalMethod = descriptor.value;
+    descriptor.value = async function (this: BaseModelClass | BaseFrameClass, ...args: unknown[]) {
+      if (this instanceof BaseModelClass) {
+        getLogger(convertDomainToCategory(this.modelName, "model")).debug(
+          "websocket: {model}.{method}",
+          {
+            model: modelName,
+            method: methodName,
+          },
+        );
+      }
+
+      if (this instanceof BaseFrameClass) {
+        getLogger(convertDomainToCategory(this.frameName, "frame")).debug(
+          "websocket: {model}.{method}",
+          {
+            model: modelName,
+            method: methodName,
+          },
+        );
+      }
+
+      return originalMethod.apply(this, args);
+    };
+  };
+}
+
 export function transactional(options: TransactionalOptions = {}) {
   const { isolation, readOnly, dbPreset = "w" } = options;