sonamu 0.10.11 → 0.10.13

package/src/api/config.ts

@@ -23,8 +23,15 @@ 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 { isFunctionValue, isObjectValue } from "../utils/runtime-value";
 import { type Context, type WebSocketContext } from "./context";
 
+function isExecutableConfig(
+  value: Executable<SonamuConfig>,
+): value is (() => SonamuConfig) | (() => Promise<SonamuConfig>) {
+  return isFunctionValue(value);
+}
+
 export type DatabaseConfig = Omit<Knex.Config, "connection"> & {
   connection?: Knex.PgConnectionConfig;
 };
@@ -64,6 +71,40 @@ export type SonamuTestConfig = {
   devRunner?: SonamuDevRunnerConfig;
 };
 
+export type ZodCompilerApiMode = false | "jit" | "aot";
+export type ZodCompilerConfig =
+  | false
+  | {
+      api?: ZodCompilerApiMode;
+    };
+export type NormalizedZodCompilerPolicy = {
+  api: ZodCompilerApiMode;
+  targets: Record<string, never>;
+};
+
+export function normalizeZodCompilerPolicy<Value>(
+  value: Value,
+  _syncTargets: readonly string[] = [],
+): NormalizedZodCompilerPolicy {
+  if (value === undefined || value === false) {
+    return { api: false, targets: {} };
+  }
+  if (!isObjectValue(value) || Array.isArray(value)) {
+    throw new Error("validation.zodCompiler must be false or an object");
+  }
+
+  const api = "api" in value ? (value.api ?? false) : false;
+  if (api !== false && api !== "jit" && api !== "aot") {
+    throw new Error("validation.zodCompiler.api must be false, 'jit', or 'aot'");
+  }
+
+  if ("targets" in value) {
+    throw new Error("validation.zodCompiler.targets is not supported in the API-only phase");
+  }
+
+  return { api, targets: {} };
+}
+
 export type SonamuConfig<TSinkId extends string = string, TFilterId extends string = string> = {
   projectName?: string;
 
@@ -92,6 +133,10 @@ export type SonamuConfig<TSinkId extends string = string, TFilterId extends stri
     targets: string[]; // "web", "app" 등
   };
 
+  validation?: {
+    zodCompiler?: ZodCompilerConfig;
+  };
+
   database: {
     // 데이터베이스(pg는 pg 모듈, pgnative는 pg-native 모듈의 설치가 필요합니다.)
     database?: "pg" | "pgnative";
@@ -288,7 +333,7 @@ export type SonamuSSROptions = {
 
 // NOTE(Haze, 251209): config에는 T, Promise<T>, () => T, () => Promise<T>가 모두 올 수 있어야 함.
 export function defineConfig(config: Executable<SonamuConfig>): Promise<SonamuConfig> {
-  if (typeof config === "function") {
+  if (isExecutableConfig(config)) {
     return Promise.resolve(config());
   }
 
@@ -308,7 +353,21 @@ export function defineConfig(config: Executable<SonamuConfig>): Promise<SonamuCo
  * @param rootPath
  * @returns
  */
-export async function loadConfig(rootPath: string): Promise<SonamuConfig> {
+export interface ConfigLoaderDependencies {
+  ensureTsLoaderRegistered(rootPath: string): Promise<void>;
+}
+
+const defaultConfigLoaderDependencies: ConfigLoaderDependencies = {
+  async ensureTsLoaderRegistered(rootPath) {
+    const registration = await import("../bin/ts-loader-registration");
+    await registration.ensureTsLoaderRegistered(rootPath);
+  },
+};
+
+export async function loadConfig(
+  rootPath: string,
+  dependencies: ConfigLoaderDependencies = defaultConfigLoaderDependencies,
+): Promise<SonamuConfig> {
   applyCurrentSnapshotToProcessEnv(rootPath);
 
   const shouldLoadSourceConfig = process.env.HOT === "yes" || process.env.VITEST === "true";
@@ -317,8 +376,7 @@ export async function loadConfig(rootPath: string): Promise<SonamuConfig> {
     : `${rootPath}/dist/sonamu.config.js`;
 
   if (shouldLoadSourceConfig) {
-    const { ensureTsLoaderRegistered } = await import("../bin/ts-loader-registration");
-    await ensureTsLoaderRegistered(rootPath);
+    await dependencies.ensureTsLoaderRegistered(rootPath);
   }
 
   const { default: config } = await import(`file://${configPath}`);

package/src/api/context.ts

@@ -14,7 +14,7 @@ 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";
+import { type WebSocketConnection } from "../stream/ws";
 
 // oxlint-disable-next-line @typescript-eslint/no-empty-interface -- Context 확장 타입
 export interface ContextExtend {}
@@ -41,8 +41,8 @@ export type Context = BaseContext & {
 } & ContextExtend;
 
 export type WebSocketContext<
-  TOut extends WebSocketEventMap = WebSocketEventMap,
-  TIn extends WebSocketEventMap = WebSocketEventMap,
+  TOut extends object = object,
+  TIn extends object = object,
 > = BaseContext & {
   transport: "ws";
   ws: WebSocketConnection<TOut, TIn>;

package/src/api/decorators.ts

@@ -120,6 +120,8 @@ export type ExtendedApi = {
 };
 type DecoratorTarget = { constructor: { name: string } };
 
+const decoratorTypesByTarget = new WeakMap<DecoratorTarget, Map<string, symbol>>();
+
 const DECORATOR_TYPES = {
   API: Symbol("api"),
   STREAM: Symbol("stream"),
@@ -128,13 +130,16 @@ const DECORATOR_TYPES = {
 } as const;
 
 function checkSingleDecorator(target: DecoratorTarget, propertyKey: string, decoratorType: symbol) {
-  const method = target[propertyKey as keyof typeof target] as { __decoratorType?: symbol };
-  if (method?.__decoratorType && method?.__decoratorType !== decoratorType) {
+  const decoratorTypes = decoratorTypesByTarget.get(target) ?? new Map<string, symbol>();
+  const existingDecoratorType = decoratorTypes.get(propertyKey);
+
+  if (existingDecoratorType && existingDecoratorType !== 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, @stream, @websocket, or @upload decorator on the same method.`,
     );
   } else {
-    method.__decoratorType = decoratorType;
+    decoratorTypes.set(propertyKey, decoratorType);
+    decoratorTypesByTarget.set(target, decoratorTypes);
   }
 }
 
@@ -165,7 +170,8 @@ export function api(options: ApiDecoratorOptions = {}) {
 
     // 기존 동일한 메서드가 있는지 확인 후 있는 경우 override
     const existingApi = registeredApis.find(
-      (api) => api.modelName === modelName && api.methodName === methodName,
+      (registeredApi) =>
+        registeredApi.modelName === modelName && registeredApi.methodName === methodName,
     );
     if (existingApi) {
       // 기존의 path와 새로운 path가 다르다면(=빈 스트링이 아니었는데 다른 스트링으로 바뀌게 된다면) 에러를 터뜨려줍니다.
@@ -237,11 +243,13 @@ export function stream(options: StreamDecoratorOptions) {
     const { events: _, type: _type, ...apiOptions } = options;
     const optionsWithDefaults = {
       ...apiOptions,
-      httpMethod: "GET" as HTTPMethods,
+      httpMethod:
+        /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ "GET" as HTTPMethods,
     };
 
     const existingApi = registeredApis.find(
-      (api) => api.modelName === modelName && api.methodName === methodName,
+      (registeredApi) =>
+        registeredApi.modelName === modelName && registeredApi.methodName === methodName,
     );
     if (existingApi) {
       // 기존의 path와 새로운 path가 다르다면(=빈 스트링이 아니었는데 다른 스트링으로 바뀌게 된다면) 에러를 터뜨려줍니다.
@@ -318,11 +326,13 @@ export function websocket(options: WebSocketDecoratorOptions) {
     const { outEvents: _outEvents, inEvents: _inEvents, ...apiOptions } = options;
     const optionsWithDefaults = {
       ...apiOptions,
-      httpMethod: "GET" as HTTPMethods,
+      httpMethod:
+        /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ "GET" as HTTPMethods,
     };
 
     const existingApi = registeredApis.find(
-      (api) => api.modelName === modelName && api.methodName === methodName,
+      (registeredApi) =>
+        registeredApi.modelName === modelName && registeredApi.methodName === methodName,
     );
     if (existingApi) {
       assertNoConflictingPath("websocket", modelName, methodName, existingApi.path, path);
@@ -454,7 +464,8 @@ export function upload(options: UploadDecoratorOptions = { consume: "buffer" })
 
     // registeredApis에서 해당 API 찾아서 uploadOptions 추가
     const existingApi = registeredApis.find(
-      (api) => api.modelName === modelName && api.methodName === methodName,
+      (registeredApi) =>
+        registeredApi.modelName === modelName && registeredApi.methodName === methodName,
     );
 
     if (existingApi) {
@@ -538,23 +549,23 @@ function assertNoConflictingPath(
  * @param existingOptions 기존의 옵션
  * @param newOptions 새로운 옵션
  */
-function assertNoConflictingOptions(
+function assertNoConflictingOptions<ExistingOptions extends object, NewOptions extends object>(
   decoratorName: string,
   modelName: string,
   methodName: string,
-  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- <아 쉽게쉽게 좀 갑시다>
-  existingOptions: Record<string, any>,
-  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- <이럴 때 아니면 any 언제 씁니까>
-  newOptions: Record<string, any>,
+  existingOptions: ExistingOptions,
+  newOptions: NewOptions,
 ) {
-  Object.keys(newOptions).forEach((key) => {
-    if (existingOptions[key] && !isEqual(existingOptions[key], newOptions[key])) {
+  const existingEntries = new Map(Object.entries(existingOptions));
+  Object.entries(newOptions).forEach(([key, newValue]) => {
+    const existingValue = existingEntries.get(key);
+    if (existingValue && !isEqual(existingValue, newValue)) {
       // 이것이 무슨 상황이냐면요, api.options가 덮어씌워지는 상황입니다.
       // 가령 @api({ resourceName: "Users" }) 데코레이터가 붙어있는 메서드에
       // @stream({ resourceName: "Posts" }) 같은 것이 붙어 있는 상황입니다.
       // 이렇게 되면 두 데코레이터가 같은 api의 options 속 같은 필드를 건드리게 되므로, 에러를 터뜨려줍니다.
       throw new Error(
-        `@${decoratorName} decorator on ${modelName}.${methodName} has conflicting options: ${key}. The decorator is trying to override the existing option(${JSON.stringify(existingOptions[key])}) with the new option(${JSON.stringify(newOptions[key])}).`,
+        `@${decoratorName} decorator on ${modelName}.${methodName} has conflicting options: ${key}. The decorator is trying to override the existing option(${JSON.stringify(existingValue)}) with the new option(${JSON.stringify(newValue)}).`,
       );
     }
   });

package/src/api/http-validator.ts

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+
+import { type z } from "zod";
+
+import { type LoadedTypes } from "../syncer/module-loader";
+import { isObjectValue } from "../utils/runtime-value";
+import { fastifyCaster } from "./caster";
+import { getZodObjectFromApi } from "./code-converters";
+import { type NormalizedZodCompilerPolicy } from "./config";
+import { type ExtendedApi } from "./decorators";
+
+export type HttpRequestValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | Date
+  | null
+  | undefined
+  | HttpRequestValue[]
+  | { [key: string]: HttpRequestValue };
+export type HttpRequestParameters = Record<string, HttpRequestValue>;
+export type HttpValidator = z.ZodType<object>;
+type FastifyHttpValidator = ReturnType<typeof fastifyCaster>;
+export type HttpValidatorRegistry = {
+  fingerprint: string;
+  validators: ReadonlyMap<string, HttpValidator>;
+};
+
+export function getHttpValidatorRouteKey(api: ExtendedApi): string {
+  return JSON.stringify([api.modelName, api.methodName, api.options.httpMethod ?? "GET", api.path]);
+}
+
+export function getHttpValidatorRouteIdentifier(api: ExtendedApi): string {
+  return createHash("sha256").update(getHttpValidatorRouteKey(api)).digest("hex");
+}
+
+function stableJson<Value>(value: Value): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableJson(item)).join(",")}]`;
+  }
+  if (isObjectValue(value) && value !== null) {
+    return `{${Object.entries(value)
+      .toSorted(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function getHttpValidatorFingerprint(apis: readonly ExtendedApi[]): string {
+  const metadata = apis
+    .filter((api) => api.websocketOptions === undefined)
+    .map((api) => ({
+      key: getHttpValidatorRouteKey(api),
+      parameters: api.parameters,
+      typeParameters: api.typeParameters,
+    }))
+    .toSorted((left, right) => left.key.localeCompare(right.key));
+  return createHash("sha256").update(stableJson(metadata)).digest("hex");
+}
+
+export function assertHttpValidatorRegistry(
+  apis: readonly ExtendedApi[],
+  registry: HttpValidatorRegistry,
+): void {
+  const expectedApis = apis.filter((api) => api.websocketOptions === undefined);
+  const expectedFingerprint = getHttpValidatorFingerprint(expectedApis);
+  if (registry.fingerprint !== expectedFingerprint) {
+    throw new Error(
+      `HTTP validator registry fingerprint mismatch: expected ${expectedFingerprint}, received ${registry.fingerprint}`,
+    );
+  }
+
+  const expectedKeys = new Set(expectedApis.map(getHttpValidatorRouteKey));
+  if (registry.validators.size !== expectedKeys.size) {
+    throw new Error(
+      `HTTP validator registry coverage mismatch: expected ${expectedKeys.size}, received ${registry.validators.size}`,
+    );
+  }
+  for (const key of expectedKeys) {
+    if (!registry.validators.has(key)) {
+      throw new Error(`HTTP validator registry is missing ${key}`);
+    }
+  }
+}
+
+export interface HttpValidatorDependencies {
+  createSchema(api: ExtendedApi, types: LoadedTypes): z.ZodObject;
+  applyCaster(schema: z.ZodObject): FastifyHttpValidator;
+  compileJit(
+    validator: FastifyHttpValidator,
+    options: { eager: true },
+  ): Promise<FastifyHttpValidator>;
+}
+
+export const defaultHttpValidatorDependencies: HttpValidatorDependencies = {
+  createSchema: getZodObjectFromApi,
+  applyCaster: fastifyCaster,
+  async compileJit(validator, options) {
+    const { jit } = await import("zod-compiler/jit");
+    return jit(validator, options);
+  },
+};
+
+export async function createHttpValidator(
+  options: {
+    api: ExtendedApi;
+    policy: NormalizedZodCompilerPolicy;
+    types: LoadedTypes;
+    aotRegistry?: HttpValidatorRegistry;
+    allowAotSourceFallback?: boolean;
+  },
+  dependencies: HttpValidatorDependencies = defaultHttpValidatorDependencies,
+): Promise<HttpValidator> {
+  if (options.policy.api === "aot") {
+    const routeKey = getHttpValidatorRouteKey(options.api);
+    const compiled = options.aotRegistry?.validators.get(routeKey);
+    if (compiled !== undefined) {
+      return compiled;
+    }
+    if (options.allowAotSourceFallback === true) {
+      // source dev에서는 build registry를 실행하지 않으므로 cached plain validator로 대체합니다.
+    } else {
+      throw new Error(`HTTP validator registry is missing ${routeKey}`);
+    }
+  }
+
+  // Generic type parameter 처리 중 공유 references가 바뀌므로 route마다 사본을 넘깁니다.
+  const validator = dependencies.applyCaster(
+    dependencies.createSchema(options.api, { ...options.types }),
+  );
+  if (options.policy.api !== "jit") {
+    return validator;
+  }
+
+  const originalParse = validator.parse;
+  const originalSafeParse = validator.safeParse;
+  const compiled = await dependencies.compileJit(validator, { eager: true });
+
+  // upstream JIT는 컴파일 실패를 숨기므로 공개 메서드 설치 여부를 직접 확인합니다.
+  if (compiled.parse === originalParse || compiled.safeParse === originalSafeParse) {
+    throw new Error(
+      `validation.zodCompiler.api JIT compilation failed for ${getHttpValidatorRouteKey(options.api)}`,
+    );
+  }
+
+  return compiled;
+}