sonamu 0.7.21 → 0.7.23

package/src/api/sonamu.ts

@@ -1,12 +1,15 @@
+import { dispose as logtapeDispose } from "@logtape/logtape";
 import assert from "assert";
 import { AsyncLocalStorage } from "async_hooks";
 import type { FSWatcher } from "chokidar";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import fs from "fs";
 import type { IncomingMessage, Server, ServerResponse } from "http";
 import os from "os";
 import path from "path";
 import type { ZodObject } from "zod";
 import { createMockSSEFactory, DB, isDaemonServer } from "..";
+import type { CacheConfig, CacheManager } from "../cache/types";
 import type { SonamuDBConfig } from "../database/db";
 import { Naite } from "../naite/naite";
 import type { StorageManager } from "../storage/storage-manager";
@@ -17,12 +20,8 @@ import type { AbsolutePath } from "../utils/path-utils";
 import type { SonamuConfig, SonamuServerOptions, SonamuTaskOptions } from "./config";
 import type { AuthContext, Context, UploadContext } from "./context";
 import type { ExtendedApi } from "./decorators";
+import { getSecrets, type SonamuSecrets } from "./secret";
 
-export type SonamuSecrets = {
-  anthropic_api_key?: string;
-  voyage_api_key?: string;
-  openai_api_key?: string;
-};
 class SonamuClass {
   public isInitialized: boolean = false;
   public asyncLocalStorage: AsyncLocalStorage<{
@@ -109,13 +108,7 @@ class SonamuClass {
     return this._config;
   }
 
-  private _secrets: SonamuSecrets | null = null;
-  set secrets(secrets: SonamuSecrets) {
-    this._secrets = secrets;
-  }
-  get secrets(): SonamuSecrets | null {
-    return this._secrets;
-  }
+  public readonly secrets: SonamuSecrets = getSecrets();
 
   private _storage: StorageManager | null = null;
   /**
@@ -128,6 +121,17 @@ class SonamuClass {
     return this._storage;
   }
 
+  private _cache: CacheManager | null = null;
+  /**
+   * CacheManager 인스턴스 (BentoCache)
+   */
+  get cache(): CacheManager {
+    if (!this._cache) {
+      throw new Error("Cache has not been initialized. Check cache config in sonamu.config.ts.");
+    }
+    return this._cache;
+  }
+
   private _workflows: WorkflowManager | null = null;
   get workflows(): WorkflowManager {
     if (this._workflows === null) {
@@ -167,24 +171,19 @@ class SonamuClass {
     const { findApiRootPath } = await import("../utils/utils");
     this.apiRootPath = apiRootPath ?? findApiRootPath();
 
+    // 설정을 로딩하는 것부터 시작
     const { loadConfig } = await import("./config");
     this.config = await loadConfig(this.apiRootPath);
     // sonamu.config.ts 기본값 설정
-    this.config.database.database = this.config.database.database ?? "postgresql";
-
-    // API 키 환경변수 로드
-    const secrets: SonamuSecrets = {};
-    if (process.env.ANTHROPIC_API_KEY) {
-      secrets.anthropic_api_key = process.env.ANTHROPIC_API_KEY;
-    }
-    if (process.env.VOYAGE_API_KEY) {
-      secrets.voyage_api_key = process.env.VOYAGE_API_KEY;
-    }
-    if (process.env.OPENAI_API_KEY) {
-      secrets.openai_api_key = process.env.OPENAI_API_KEY;
-    }
-    if (Object.keys(secrets).length > 0) {
-      this.secrets = secrets;
+    this.config.database.database = this.config.database.database ?? "pg";
+    this.config.database.defaultOptions.client = this.config.database.database ?? "pg";
+
+    // 로깅 설정
+    const { configureLogTape } = await import("../logger/configure");
+    if (this.config.logging !== false) {
+      await configureLogTape({
+        ...this.config.logging,
+      });
     }
 
     // DB 로드
@@ -201,6 +200,9 @@ class SonamuClass {
     const { EntityManager } = await import("../entity/entity-manager");
     await EntityManager.autoload(doSilent);
 
+    // Cache 초기화
+    await this.initializeCache(this.config.server.cache, forTesting);
+
     // 테스팅인 경우 싱크 없이 중단
     if (forTesting) {
       this.isInitialized = true;
@@ -214,14 +216,14 @@ class SonamuClass {
     const { Syncer } = await import("../syncer/syncer");
     this.syncer = new Syncer();
 
-    // Autoload: Models / Types / APIs
+    // Autoload: Models / Types / APIs / Workflows / Templates / SSR Routes
     await this.syncer.autoloadTypes();
     await this.syncer.autoloadModels();
     await this.syncer.autoloadApis();
     await this.syncer.autoloadWorkflows();
-
     const { TemplateManager } = await import("../template");
     await TemplateManager.autoload();
+    await this.syncer.autoloadSSRRoutes();
 
     const { isLocal, isTest } = await import("../utils/controller");
     if (isLocal()) {
@@ -232,7 +234,6 @@ class SonamuClass {
     const { isHotReloadServer } = await import("../utils/controller");
     if (isLocal() && !isTest() && isHotReloadServer() && enableSync) {
       await this.syncer.sync();
-
       await this.startWatcher();
     }
 
@@ -249,8 +250,17 @@ class SonamuClass {
     }
 
     const options = this.config.server;
-    const fastify = (await import("fastify")).default;
-    const server = fastify(options.fastify);
+    const { default: fastify } = await import("fastify");
+    const { getLogTapeFastifyLogger } = await import("@logtape/fastify");
+    const server = fastify({
+      ...options.fastify,
+      logger:
+        this.config.logging !== false
+          ? getLogTapeFastifyLogger({
+              category: this.config.logging?.fastifyCategory ?? ["fastify"],
+            })
+          : undefined,
+    });
     this.server = server;
 
     // Storage 설정 → StorageManager 생성
@@ -352,49 +362,254 @@ class SonamuClass {
     const { sonamuUIApiPlugin } = await import("../ui/api");
     server.register(sonamuUIApiPlugin);
 
-    // API 라우팅 (로컬HMR 상태와 구분)
+    // 로컬/프로덕션 환경 분기
     const { isLocal } = await import("../utils/controller");
-    if (isLocal()) {
-      server.all("*", async (request, reply) => {
-        // Sonamu UI
-        if (request.url.startsWith("/sonamu-ui")) {
-          return;
-        }
-
-        const found = this.syncer.apis.find(
-          (api) =>
-            this.config.api.route.prefix + api.path === request.url.split("?")[0] &&
-            (api.options.httpMethod ?? "GET") === request.method.toUpperCase(),
-        );
-        if (found) {
-          return this.createApiHandler(found, config)(request, reply);
-        }
-
-        if (request.url.startsWith("/api/")) {
-          const { NotFoundException } = await import("../exceptions/so-exceptions");
-          throw new NotFoundException(`존재하지 않는 API 접근입니다. ${request.url}`);
-        }
+    const webPath = path.join(this.appRootPath, "web");
+    const hasWeb = fs.existsSync(webPath);
 
-        // 일반 파일 접근시 별도의 에러 출력하지 않음
-        return;
-      });
+    if (isLocal()) {
+      // 로컬 개발 환경: Vite Dev Server + 통합 핸들러
+      if (hasWeb) {
+        await this.setupViteDevServer(server, webPath, config);
+      }
     } else {
+      // 프로덕션 환경: 개별 API 라우트 + 정적 파일 서빙
       for (const api of this.syncer.apis) {
-        // model
         if (this.syncer.models[api.modelName] === undefined) {
           throw new Error(`정의되지 않은 모델에 접근 ${api.modelName}`);
         }
 
-        // route
         server.route({
           method: api.options.httpMethod ?? "GET",
           url: this.config.api.route.prefix + api.path,
           handler: this.createApiHandler(api, config),
-        }); // END server.route
+        });
+      }
+
+      if (hasWeb) {
+        await this.setupStaticWebServer(server, webPath, config);
       }
     }
   }
 
+  // biome-ignore lint/suspicious/noExplicitAny: ViteDevServer 타입을 동적으로 로드해야 함
+  private viteServer: any = null;
+
+  private async setupViteDevServer(
+    server: FastifyInstance<Server, IncomingMessage, ServerResponse>,
+    webPath: string,
+    config: SonamuFastifyConfig,
+  ): Promise<void> {
+    // @fastify/middie 등록 (Connect-style middleware 지원)
+    await server.register((await import("@fastify/middie")).default);
+
+    const vite = await import("vite");
+
+    this.viteServer = await vite.createServer({
+      root: webPath,
+      server: {
+        middlewareMode: true,
+        hmr: {
+          server: server.server,
+        },
+      },
+      appType: "custom",
+    });
+
+    // Vite middleware 등록 (Vite 에셋 처리)
+    server.use((req, res, next) => {
+      // API와 Sonamu UI는 Fastify 라우트가 처리하도록 skip
+      if (req.url?.startsWith(this.config.api.route.prefix) || req.url?.startsWith("/sonamu-ui")) {
+        return next();
+      }
+      // 나머지는 Vite middleware로 전달
+      return this.viteServer.middlewares(req, res, next);
+    });
+
+    // API 동적 라우팅 (catch-all 전에 등록)
+    for (const api of this.syncer.apis) {
+      if (this.syncer.models[api.modelName] === undefined) {
+        throw new Error(`정의되지 않은 모델에 접근 ${api.modelName}`);
+      }
+
+      server.route({
+        method: api.options.httpMethod ?? "GET",
+        url: this.config.api.route.prefix + api.path,
+        handler: this.createApiHandler(api, config),
+      });
+    }
+
+    // Catch-all 핸들러: SSR + CSR fallback
+    server.setNotFoundHandler(async (request, reply) => {
+      const url = request.url;
+
+      // SSR 라우트 체크
+      const { matchSSRRoute } = await import("../ssr");
+      const match = matchSSRRoute(url);
+
+      if (match) {
+        console.log(`[SSR] Matched route: ${match.route.path}`);
+        // SSR 렌더링
+        try {
+          const { renderSSR } = await import("../ssr");
+          const html = await renderSSR(
+            url,
+            match.route,
+            match.params,
+            request,
+            reply,
+            config,
+            this.viteServer,
+          );
+          reply.type("text/html").send(html);
+          return;
+        } catch (e) {
+          console.error("SSR Error:", e);
+          console.log("Falling back to CSR...");
+          // fallback to CSR (아래 로직 실행)
+        }
+      }
+
+      // CSR fallback
+      try {
+        const fs = await import("node:fs/promises");
+        let template = await fs.readFile(
+          path.join(this.viteServer.config.root, "index.html"),
+          "utf-8",
+        );
+        template = await this.viteServer.transformIndexHtml(url, template);
+
+        reply.type("text/html").send(template);
+        return;
+      } catch (e) {
+        this.viteServer.ssrFixStacktrace(e as Error);
+        console.error(e);
+        reply.status(500).send((e as Error).message);
+        return;
+      }
+    });
+
+    // 서버 종료 시 Vite도 종료
+    server.addHook("onClose", async () => {
+      await this.viteServer.close();
+    });
+
+    console.log("✓ Vite dev server integrated");
+  }
+
+  private async setupStaticWebServer(
+    server: FastifyInstance<Server, IncomingMessage, ServerResponse>,
+    _webPath: string,
+    config: SonamuFastifyConfig,
+  ): Promise<void> {
+    // 경로 명확화: api/public/web, api/dist/ssr
+    const webDistPath = path.join(this.apiRootPath, "public", "web");
+    const ssrPath = path.join(this.apiRootPath, "dist", "ssr");
+
+    if (!fs.existsSync(webDistPath)) {
+      console.warn(`⚠ Web dist not found: ${webDistPath}`);
+      return;
+    }
+
+    // SSR entry 존재 여부 확인
+    const ssrEntryPath = path.join(ssrPath, "entry-server.generated.js");
+    const ssrAvailable = fs.existsSync(ssrEntryPath);
+
+    if (!ssrAvailable) {
+      console.warn(`⚠ SSR entry not found: ${ssrEntryPath}`);
+      console.warn("  SSR will be disabled. Only CSR will work.");
+    }
+
+    // SSR 라우트 로드 (production에서만, 사용자 프로젝트의 ssr/routes.ts)
+    if (ssrAvailable) {
+      const ssrRoutesPath = path.join(this.apiRootPath, "dist", "ssr", "routes.js");
+      if (fs.existsSync(ssrRoutesPath)) {
+        await import(ssrRoutesPath);
+        console.log("✓ SSR routes loaded");
+      } else {
+        console.warn(`⚠ SSR routes not found: ${ssrRoutesPath}`);
+      }
+    }
+
+    // 롤링 업데이트 대응: asset hash 불일치 시 현재 버전 직접 서빙
+    server.get("/assets/:filename", async (request, reply) => {
+      const requestedFile = (request.params as { filename: string }).filename;
+      const assetsDir = path.join(webDistPath, "assets");
+
+      // index-*.js 또는 index-*.css 요청인 경우
+      if (/^index-[a-f0-9]+\.(js|css)$/.test(requestedFile)) {
+        const ext = requestedFile.split(".").pop();
+        const files = fs.readdirSync(assetsDir);
+        const currentFile = files.find((f) => f.startsWith("index-") && f.endsWith(`.${ext}`));
+
+        if (currentFile) {
+          const filePath = path.join(assetsDir, currentFile);
+          const content = fs.readFileSync(filePath);
+          reply.type(ext === "js" ? "application/javascript" : "text/css");
+          reply.header("Cache-Control", "public, max-age=31536000, immutable");
+          return reply.send(content);
+        }
+      }
+
+      // 일반 파일 서빙
+      const filePath = path.join(assetsDir, requestedFile);
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath);
+        const ext = requestedFile.split(".").pop();
+        reply.type(ext === "js" ? "application/javascript" : ext === "css" ? "text/css" : "");
+        if (requestedFile.includes("-")) {
+          reply.header("Cache-Control", "public, max-age=31536000, immutable");
+        }
+        return reply.send(content);
+      }
+
+      reply.code(404).send("Not found");
+    });
+
+    // SPA/SSR 라우팅
+    server.setNotFoundHandler(async (request, reply) => {
+      // /api, /sonamu-ui는 404 그대로
+      if (request.url.startsWith("/api") || request.url.startsWith("/sonamu-ui")) {
+        reply.code(404).send({ error: "Not Found" });
+        return;
+      }
+
+      const url = request.url;
+
+      // SSR 라우트 체크
+      if (ssrAvailable) {
+        const { matchSSRRoute } = await import("../ssr");
+        const match = matchSSRRoute(url);
+
+        if (match) {
+          try {
+            // renderSSR 재사용 (vite 없이 호출 = production 모드)
+            const { renderSSR } = await import("../ssr/renderer");
+            const html = await renderSSR(url, match.route, match.params, request, reply, config);
+            reply.type("text/html").send(html);
+            console.log(`[SSR] Matched route: ${match.route.path}`);
+            return;
+          } catch (e) {
+            console.error("[SSR Error]", {
+              url: request.url,
+              route: match.route.path,
+              error: e instanceof Error ? e.message : String(e),
+              timestamp: new Date().toISOString(),
+            });
+            // CSR로 fallback
+          }
+        }
+      }
+
+      // CSR fallback (SSR 실패 시 또는 SSR 라우트가 아닌 경우)
+      const indexPath = path.join(webDistPath, "index.html");
+      const html = fs.readFileSync(indexPath, "utf-8");
+      reply.type("text/html").send(html);
+    });
+
+    console.log(`✓ Static web server configured with ${ssrAvailable ? "SSR" : "CSR only"} support`);
+  }
+
   createApiHandler(
     api: ExtendedApi,
     config: SonamuFastifyConfig,
@@ -450,6 +665,35 @@ class SonamuClass {
     };
   }
 
+  /**
+   * SSR용 API 호출 (HTTP 오버헤드 없이 직접 호출)
+   * createApiHandler의 로직을 재사용하되, request 파싱 대신 params 직접 사용
+   */
+  async invokeApiForSSR(
+    api: ExtendedApi,
+    // biome-ignore lint/suspicious/noExplicitAny: SSR에서 다양한 타입의 params를 받아야 함
+    params: any[],
+    config: SonamuFastifyConfig,
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<unknown> {
+    // Context 생성 (기존 메소드 재사용)
+    const context = await this.createContext(config, request, reply);
+
+    // args 생성: Context 파라미터는 주입, 나머지는 params에서 가져오기
+    const { ApiParamType } = await import("../types/types");
+    let paramsIndex = 0;
+    const args = api.parameters.map((param) => {
+      if (ApiParamType.isContext(param.type)) {
+        return context;
+      }
+      return params[paramsIndex++];
+    });
+
+    // 모델 메서드 호출 (기존 메서드 재사용)
+    return this.invokeModelMethod(api, args, context, reply);
+  }
+
   async invokeModelMethod(
     api: ExtendedApi,
     args: unknown[],
@@ -614,6 +858,29 @@ class SonamuClass {
     }
   }
 
+  private async initializeCache(config: CacheConfig | undefined, forTesting: boolean) {
+    const { setCacheManagerRef } = await import("../cache/decorator");
+
+    // 테스트 환경에서 메모리 드라이버 자동 사용
+    if (forTesting) {
+      const { createTestCacheManager } = await import("../cache/cache-manager");
+      this._cache = createTestCacheManager();
+      setCacheManagerRef(this._cache);
+      return;
+    }
+
+    // 설정이 없으면 캐시 비활성화
+    if (!config) {
+      setCacheManagerRef(null);
+      return;
+    }
+
+    // 설정에 따라 CacheManager 생성
+    const { createCacheManager } = await import("../cache/cache-manager");
+    this._cache = createCacheManager(config);
+    setCacheManagerRef(this._cache);
+  }
+
   private async initializeWorkflows(options: SonamuTaskOptions | undefined) {
     const { WorkflowManager } = await import("../tasks/workflow-manager");
     // NOTE: @sonamu-kit/tasks 안에선 knex config를 수정하기 때문에 connection이 아닌 config 째로 보냅니다.
@@ -715,9 +982,15 @@ class SonamuClass {
 
   async destroy(): Promise<void> {
     const { BaseModel } = await import("../database/base-model");
+    // 먼저 처리해야함.
     await BaseModel.destroy();
-    await this._workflows?.destroy();
-    await this.watcher?.close();
+    await Promise.allSettled([
+      this._workflows?.destroy() ?? Promise.resolve(),
+      this._cache?.disconnect() ?? Promise.resolve(),
+      this.watcher?.close() ?? Promise.resolve(),
+      logtapeDispose(),
+    ]);
   }
 }
+
 export const Sonamu = new SonamuClass();

package/src/cache/cache-manager.ts

@@ -0,0 +1,23 @@
+import { BentoCache, bentostore } from "bentocache";
+import { memoryDriver } from "bentocache/drivers/memory";
+import type { CacheConfig, CacheManager } from "./types";
+
+/**
+ * BentoCache 인스턴스를 생성합니다.
+ */
+export function createCacheManager(config: CacheConfig): CacheManager {
+  return new BentoCache(config);
+}
+
+/**
+ * 테스트 환경용 기본 CacheManager를 생성합니다.
+ * 메모리 드라이버만 사용하는 간단한 설정
+ */
+export function createTestCacheManager(): CacheManager {
+  return new BentoCache({
+    default: "memory",
+    stores: {
+      memory: bentostore().useL1Layer(memoryDriver({ maxItems: 1000 })),
+    },
+  });
+}

package/src/cache/decorator.ts

@@ -0,0 +1,116 @@
+import type { BaseFrameClass } from "../api/base-frame";
+import { BaseModelClass } from "../database/base-model";
+import type { CacheDecoratorOptions, CacheManager } from "./types";
+
+type DecoratorTarget = { constructor: { name: string } };
+
+// 캐시 매니저 참조 (Sonamu.init에서 설정됨)
+let cacheManagerRef: CacheManager | null = null;
+
+/**
+ * 캐시 매니저 참조 설정 (내부 사용)
+ */
+export function setCacheManagerRef(manager: CacheManager | null): void {
+  cacheManagerRef = manager;
+}
+
+/**
+ * 캐시 매니저 참조 가져오기 (내부 사용)
+ */
+export function getCacheManagerRef(): CacheManager | null {
+  return cacheManagerRef;
+}
+
+/**
+ * 캐시 키 생성
+ */
+function generateCacheKey(
+  modelName: string,
+  methodName: string,
+  args: unknown[],
+  keyOption?: CacheDecoratorOptions["key"],
+): string {
+  // 커스텀 키 함수 사용
+  if (typeof keyOption === "function") {
+    return keyOption(...args);
+  }
+
+  // 문자열 키 + args suffix
+  if (typeof keyOption === "string") {
+    const argsSuffix = serializeArgs(args);
+    return argsSuffix ? `${keyOption}:${argsSuffix}` : keyOption;
+  }
+
+  // 자동 생성: ModelName.methodName:serializedArgs
+  const baseKey = `${modelName}.${methodName}`;
+  const argsSuffix = serializeArgs(args);
+  return argsSuffix ? `${baseKey}:${argsSuffix}` : baseKey;
+}
+
+/**
+ * 인자 직렬화
+ */
+function serializeArgs(args: unknown[]): string {
+  if (args.length === 0) return "";
+
+  // 단일 primitive 값
+  if (args.length === 1) {
+    const arg = args[0];
+    if (arg === null || arg === undefined) return "";
+    if (typeof arg === "string" || typeof arg === "number" || typeof arg === "boolean") {
+      return String(arg);
+    }
+  }
+
+  // 복잡한 값은 JSON 직렬화
+  try {
+    return JSON.stringify(args);
+  } catch {
+    // 직렬화 실패 시 toString 사용
+    return args.map((arg) => String(arg)).join(":");
+  }
+}
+
+/**
+ * @cache 데코레이터
+ *
+ * 메서드의 결과를 캐싱합니다.
+ *
+ * @example
+ * class UserModelClass extends BaseModel {
+ *   @cache({ ttl: '10m', tags: ['user'] })
+ *   @api()
+ *   async findById(id: number) {
+ *     return this.findOne(['id', id]);
+ *   }
+ * }
+ */
+export function cache(options: CacheDecoratorOptions = {}) {
+  return (_target: DecoratorTarget, propertyKey: string, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (this: BaseModelClass | BaseFrameClass, ...args: unknown[]) {
+      const manager = cacheManagerRef;
+
+      if (!manager) {
+        throw new Error(
+          "CacheManager is not initialized. Please configure 'cache' in sonamu.config.ts.",
+        );
+      }
+
+      const modelName = this instanceof BaseModelClass ? this.modelName : this.frameName;
+      const methodName = propertyKey;
+
+      const cacheKey = generateCacheKey(modelName, methodName, args, options.key);
+      const store = options.store ? manager.use(options.store) : manager;
+
+      return store.getOrSet({
+        ...options,
+        key: cacheKey,
+        factory: () => originalMethod.apply(this, args),
+      });
+    };
+
+    return descriptor;
+  };
+}

package/src/cache/drivers.ts

@@ -0,0 +1,42 @@
+/**
+ * BentoCache 드라이버 re-export
+ *
+ * @example
+ * import { drivers, store } from 'sonamu/cache';
+ *
+ * cache: {
+ *   stores: {
+ *     main: store()
+ *       .useL1Layer(drivers.memory({ maxSize: '100mb' }))
+ *       .useL2Layer(drivers.redis({ connection }))
+ *       .useBus(drivers.redisBus({ connection }))
+ *   }
+ * }
+ */
+
+// Store builder
+export { bentostore as store } from "bentocache";
+
+import { fileDriver as _fileDriver } from "bentocache/drivers/file";
+import { knexDriver as _knexDriver } from "bentocache/drivers/knex";
+import { memoryDriver as _memoryDriver } from "bentocache/drivers/memory";
+import {
+  redisBusDriver as _redisBusDriver,
+  redisDriver as _redisDriver,
+} from "bentocache/drivers/redis";
+
+// 개별 드라이버 export
+export const memoryDriver = _memoryDriver;
+export const fileDriver = _fileDriver;
+export const redisDriver = _redisDriver;
+export const redisBusDriver = _redisBusDriver;
+export const knexDriver = _knexDriver;
+
+// 편의를 위한 drivers 객체
+export const drivers = {
+  memory: _memoryDriver,
+  file: _fileDriver,
+  redis: _redisDriver,
+  redisBus: _redisBusDriver,
+  knex: _knexDriver,
+};