@fuzionx/framework 0.1.9 → 0.1.21

package/cli/templates/app/fuzionx.yaml.tpl

@@ -9,9 +9,11 @@ bridge:
     per_ip: 1000
 
 database:
-  main:
-    driver: sqlite
-    path: ./storage/database.sqlite
+  default: main
+  connections:
+    main:
+      driver: sqlite
+      database: ./storage/database.sqlite
 
 app:
   name: '{{name}}'

package/lib/core/Application.js

@@ -21,6 +21,7 @@ import HashHelper from '../helpers/HashHelper.js';
 import MediaHelper from '../helpers/MediaHelper.js';
 import FileHelper from '../helpers/FileHelper.js';
 import View from '../view/View.js';
+import OpenAPI from '../view/OpenAPI.js';
 import Scheduler from '../schedule/Scheduler.js';
 import Queue from '../schedule/Queue.js';
 import Storage from '../services/Storage.js';
@@ -59,6 +60,11 @@ export default class Application {
         this.baseDir = path.resolve(opts.baseDir || process.cwd());
         this.configPath = opts.configPath || null;
 
+        // configPath 지정 시 YAML 파일에서 database/app/themes 등 로드
+        if (this.configPath) {
+            this.config.loadYaml(path.resolve(this.baseDir, this.configPath));
+        }
+
         // Bridge 참조 (listen() 시 FuzionXApp 생성)
         this._bridge = null;
         this._coreApp = null;
@@ -271,12 +277,32 @@ export default class Application {
 
         // DB 연결 매니저 초기화 (database 섹션이 있을 때만)
         const dbConfig = this.config.get('database');
-        if (dbConfig && dbConfig.connections) {
-            this._connectionManager.configure(dbConfig);
-            SqlModel.setConnectionManager(this._connectionManager);
-            MongoModel.setConnectionManager(this._connectionManager);
+        if (dbConfig) {
+            // connections 키가 없는 레거시 형식 호환:
+            //   database.main: { driver: 'sqlite', ... }
+            //   → database.connections.main: { driver: 'sqlite', ... }
+            if (!dbConfig.connections) {
+                const connections = {};
+                for (const [key, val] of Object.entries(dbConfig)) {
+                    if (key !== 'default' && typeof val === 'object' && val !== null) {
+                        connections[key] = val;
+                    }
+                }
+                if (Object.keys(connections).length > 0) {
+                    dbConfig.connections = connections;
+                    if (!dbConfig.default) dbConfig.default = Object.keys(connections)[0];
+                }
+            }
+            if (dbConfig.connections) {
+                this._connectionManager.configure(dbConfig);
+                SqlModel.setConnectionManager(this._connectionManager);
+                MongoModel.setConnectionManager(this._connectionManager);
+            }
         }
 
+        // OpenAPI / Swagger UI 라우트 등록 (21-openapi.md)
+        this._registerDocsRoutes();
+
         this._booted = true;
         await this.emit('booted');
     }
@@ -293,12 +319,15 @@ export default class Application {
      */
     async listen(port, callback) {
         if (typeof port === 'function') { callback = port; port = undefined; }
-        port = port || this.config.get('bridge.server.port', 3000);
+        port = port ?? this.config.get('bridge.server.port') ?? this.config.get('bridge.port', 3000);
 
         if (!this._booted) await this.boot();
 
-        // 포트 사용 여부 확인 — 충돌 시 명확한 에러
-        await this._checkPort(port);
+        // 포트 사용 여부 확인 — primary에서만 (워커는 SO_REUSEPORT로 공유)
+        const cluster = await import('node:cluster');
+        if (!cluster.default?.isWorker) {
+            await this._checkPort(port);
+        }
 
         await this.emit('ready');
 
@@ -322,8 +351,14 @@ export default class Application {
                     if (this.file) this.file._bridge = this._bridge;
                     if (this.i18n) this.i18n._bridge = this._bridge;
                 }
+                // WS proxy 연결 (WsHandler에서 this.app.ws 사용)
+                this.ws = this._coreApp.ws;
             }
             this._registerBridgeRoutes(this._coreApp);
+
+            // WsHandler → Bridge WS 이벤트 연결
+            this._registerWsHandlers(this._coreApp);
+
             this._coreApp.listen(port, callback);
             // Bridge가 자체 graceful shutdown 처리 → Framework 중복 등록 불필요
         } else {
@@ -367,6 +402,83 @@ export default class Application {
         });
     }
 
+    /**
+     * OpenAPI / Swagger UI 라우트 등록 (21-openapi.md)
+     *
+     * app.docs.enabled = true 시 활성화.
+     * 라우트: GET /docs, GET /docs/openapi.json, GET /docs/openapi.yaml
+     * @private
+     */
+    _registerDocsRoutes() {
+        const docsConfig = this.config.get('app.docs');
+        if (!docsConfig || docsConfig.enabled === false) return;
+
+        const docsPath = docsConfig.path || '/docs';
+        const routes = this._router.getRoutes();
+
+        // OpenAPI spec 빌드 (1회, 캐싱)
+        this._openapi = new OpenAPI({
+            title: docsConfig.title || this.config.get('app.name', 'FuzionX') + ' API',
+            version: docsConfig.version || '1.0.0',
+            description: docsConfig.description || '',
+            servers: docsConfig.servers || [],
+        });
+        this._openapi.build(routes);
+
+        // JSON spec
+        this._router.get(`${docsPath}/openapi.json`, (ctx) => {
+            ctx.json(this._openapi.toJSON());
+        });
+
+        // YAML spec
+        this._router.get(`${docsPath}/openapi.yaml`, (ctx) => {
+            ctx.setHeader('Content-Type', 'text/yaml; charset=utf-8');
+            ctx.send(this._openapi.toYAML());
+        });
+
+        // Swagger UI HTML (CDN — 외부 의존 없음)
+        this._router.get(docsPath, (ctx) => {
+            const specUrl = `${docsPath}/openapi.json`;
+            const title = docsConfig.title || 'API Docs';
+            ctx.html(Application._swaggerHtml(title, specUrl));
+        });
+
+        this.logger.info(`[docs] Swagger UI → ${docsPath}`);
+    }
+
+    /**
+     * Swagger UI HTML 생성 (CDN 기반)
+     * @private
+     */
+    static _swaggerHtml(title, specUrl) {
+        return `<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+  <style>
+    body { margin: 0; background: #fafafa; }
+    .topbar { display: none; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: '${specUrl}',
+      dom_id: '#swagger-ui',
+      deepLinking: true,
+      presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+      layout: 'BaseLayout',
+    });
+  </script>
+</body>
+</html>`;
+    }
+
     /**
      * 싱글톤 컨트롤러 초기화
      * @private
@@ -403,6 +515,56 @@ export default class Application {
         }
     }
 
+    /**
+     * WsHandler → Bridge WS 이벤트 연결
+     * @private
+     */
+    _registerWsHandlers(coreApp) {
+        if (!this._wsHandlers || this._wsHandlers.size === 0) return;
+        if (!coreApp.ws) return;
+
+        for (const [namespace, HandlerClass] of this._wsHandlers) {
+            const eventMap = HandlerClass.buildEventMap();
+            const wsNs = coreApp.ws(namespace);
+
+            wsNs.on('connect', (socket) => {
+                const inst = new HandlerClass(this);
+                console.log(`[WS] connect: ${namespace} sid=${socket.sessionId}`);
+                inst.onConnect(socket);
+            });
+
+            wsNs.on('message', (socket, rawMessage) => {
+                const inst = new HandlerClass(this);
+                let parsed;
+                try { parsed = typeof rawMessage === 'string' ? JSON.parse(rawMessage) : rawMessage; }
+                catch { parsed = { type: 'message', data: rawMessage }; }
+                const eventType = parsed.type || 'message';
+                const eventData = parsed.data || parsed;
+                console.log(`[WS] msg: ${namespace} type=${eventType} sid=${socket.sessionId}`);
+                const entry = eventMap.get(eventType);
+                if (entry) {
+                    const result = entry.handler.call(inst, socket, eventData);
+                    if (result && typeof result.then === 'function') {
+                        result.then(r => { if (r) socket.send(JSON.stringify(r)); })
+                              .catch(e => console.error(`[WS] error: ${eventType}`, e));
+                    } else if (result) {
+                        socket.send(JSON.stringify(result));
+                    }
+                } else {
+                    inst.onEvent(socket, eventType, eventData);
+                }
+            });
+
+            wsNs.on('disconnect', (socket) => {
+                const inst = new HandlerClass(this);
+                console.log(`[WS] disconnect: ${namespace} sid=${socket.sessionId}`);
+                inst.onDisconnect(socket);
+            });
+
+            console.log(`[WS] 핸들러 등록: ${namespace} (events: ${[...eventMap.keys()].join(', ')})`);
+        }
+    }
+
     /**
      * 단일 라우트의 Bridge 핸들러 생성
      * rawReq → Context → middleware → controller → toResponse

package/lib/core/AutoLoader.js

@@ -50,6 +50,7 @@ export default class AutoLoader {
      */
     async load() {
         await this.loadModels();
+        await this.loadControllers();
         await this.loadServices();
         await this.loadMiddleware();
         await this.loadEvents();
@@ -72,6 +73,51 @@ export default class AutoLoader {
         }
     }
 
+    /**
+     * controllers/*.js → 싱글톤 인스턴스 + __handler__ static 등록
+     *
+     * 문서 01-routing-controllers.md:
+     * 프로토타입 메서드를 static 레퍼런스로 자동 등록하여
+     * 라우트에서 UserController.index 형태로 사용 가능.
+     */
+    async loadControllers() {
+        const controllerDir = path.join(this.baseDir, 'controllers');
+        const files = await scanDir(controllerDir);
+        if (!this.app._controllers) {
+            this.app._controllers = new Map();
+        }
+        for (const file of files) {
+            const mod = await import(file);
+            const ControllerClass = mod.default;
+            if (!ControllerClass) continue;
+
+            // __handler__ static 레퍼런스 자동 등록
+            AutoLoader.registerController(ControllerClass);
+
+            // 컨트롤러 이름 등록 (싱글톤 인스턴스는 boot 완료 후 생성)
+            const name = extractName(file, 'Controller');
+            this.app._controllers.set(name, ControllerClass);
+        }
+    }
+
+    /**
+     * 컨트롤러 프로토타입 메서드를 static __handler__ 레퍼런스로 등록
+     * @param {Function} ControllerClass
+     */
+    static registerController(ControllerClass) {
+        const proto = ControllerClass.prototype;
+        for (const method of Object.getOwnPropertyNames(proto)) {
+            if (method === 'constructor') continue;
+            if (typeof proto[method] !== 'function') continue;
+            // static property로 __handler__ 디스크립터 등록
+            ControllerClass[method] = {
+                __handler__: true,
+                controller: ControllerClass,
+                method,
+            };
+        }
+    }
+
     /** services/*.js → DI register */
     async loadServices() {
         const files = await scanDir(path.join(this.baseDir, 'services'));

package/lib/core/Config.js

@@ -5,6 +5,7 @@
  * dot-notation으로 접근: config.get('app.auth.secret')
  *
  * .env 자동 로드 + ${VAR:default} 환경변수 치환.
+ * YAML 파일 직접 파싱 지원 (외부 의존 없이 내장 파서 사용).
  *
  * @see docs/framework/17-config.md
  */
@@ -26,6 +27,108 @@ export default class Config {
         this._cache = new Map();
     }
 
+    /**
+     * YAML 파일에서 설정 로드.
+     * configPath가 지정된 경우 Application 생성자에서 호출.
+     * bridge 섹션은 Rust에서 파싱하므로 JS 쪽은 database/app/themes 등을 로드.
+     * @param {string} configPath - 절대 경로
+     */
+    loadYaml(configPath) {
+        if (!existsSync(configPath)) return;
+
+        try {
+            const content = readFileSync(configPath, 'utf-8');
+            const parsed = Config.parseYaml(content);
+
+            // _raw에 병합 (기존 opts.config 우선)
+            for (const [key, value] of Object.entries(parsed)) {
+                if (this._raw[key] === undefined) {
+                    this._raw[key] = value;
+                }
+            }
+
+            // 섹션 별칭 갱신
+            if (!Object.keys(this.bridge).length && parsed.bridge) this.bridge = parsed.bridge;
+            if (!Object.keys(this.database).length && parsed.database) this.database = parsed.database;
+            if (!Object.keys(this.app).length && parsed.app) this.app = parsed.app;
+
+            // 캐시 초기화
+            this._cache.clear();
+        } catch (err) {
+            console.error(`[Config] YAML 파일 로드 실패 (${configPath}):`, err.message);
+        }
+    }
+
+    /**
+     * 간이 YAML 파서 — 외부 의존 없이 fuzionx.yaml 구조 파싱.
+     * 지원: 중첩 객체, 문자열, 숫자, boolean, 배열(인라인), 인용 문자열.
+     * @param {string} content
+     * @returns {object}
+     */
+    static parseYaml(content) {
+        const result = {};
+        const lines = content.split('\n');
+        const stack = [{ indent: -1, obj: result }];
+
+        for (const rawLine of lines) {
+            // 주석/빈 줄 무시
+            const line = rawLine.replace(/#.*$/, '');
+            if (!line.trim()) continue;
+
+            const indent = line.search(/\S/);
+            const match = line.match(/^(\s*)([-\w.]+)\s*:\s*(.*)$/);
+            if (!match) continue;
+
+            const [, , key, rawValue] = match;
+
+            // 스택에서 현재 indent보다 깊거나 같은 레벨 제거
+            while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+                stack.pop();
+            }
+
+            const parent = stack[stack.length - 1].obj;
+            const value = rawValue.trim();
+
+            if (!value) {
+                // 하위 객체 시작
+                parent[key] = {};
+                stack.push({ indent, obj: parent[key] });
+            } else {
+                // 값 파싱
+                parent[key] = Config._parseYamlValue(value);
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * YAML 값 파싱 (문자열, 숫자, boolean, 배열)
+     * @private
+     */
+    static _parseYamlValue(raw) {
+        // 인용 문자열
+        const quoted = raw.match(/^(['"])(.*)\1$/);
+        if (quoted) return quoted[2];
+
+        // boolean
+        if (raw === 'true') return true;
+        if (raw === 'false') return false;
+        if (raw === 'null' || raw === '~') return null;
+
+        // 인라인 배열 [a, b, c]
+        if (raw.startsWith('[') && raw.endsWith(']')) {
+            return raw.slice(1, -1).split(',').map(s => Config._parseYamlValue(s.trim()));
+        }
+
+        // 숫자
+        const num = Number(raw);
+        if (!isNaN(num) && raw !== '') return num;
+
+        // 기본: 문자열
+        return raw;
+    }
+
     /**
      * .env 파일 로드 (17-config.md)
      * 부트 시 자동 호출. 이미 설정된 환경변수는 덮어쓰지 않음.

package/lib/core/Context.js

@@ -313,19 +313,13 @@ export default class Context {
             ...data,
         };
 
-        // Bridge SSR (i18n.render → bridge.ssrRenderString)
-        if (this.app?._bridge && typeof this.app._bridge.ssrRenderString === 'function') {
-            try {
-                const html = this.app._bridge.ssrRenderString(view, globals, this.locale);
-                return this.html(html);
-            } catch {} // Bridge SSR 실패 시 View 폴백
+        // Bridge Tera SSR — 폴백 없음
+        if (!this.app?._view) {
+            throw new Error('View not initialized — Bridge not available');
         }
 
-        if (this.app?._view) {
-            const html = this.app._view.render(view, globals);
-            return this.html(html);
-        }
-        return this.send(`View '${view}' not found`);
+        const html = this.app._view.render(view, globals);
+        return this.html(html);
     }
 
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/lib/helpers/MediaHelper.js

@@ -35,4 +35,50 @@ export default class MediaHelper {
         if (this._bridge?.mediaVideoInfo) return this._bridge.mediaVideoInfo(filePath);
         throw new Error('Video info requires ffprobe + Bridge.');
     }
+
+    /**
+     * 이미지에 워터마크를 합성한다.
+     * @param {string} targetPath - 대상 이미지 경로
+     * @param {string} watermarkPath - 워터마크 이미지 경로
+     * @param {number} [opacity=50] - 불투명도 (0-100)
+     * @param {string} [format] - 출력 포맷 (기본: 원본 확장자)
+     * @param {number} [quality=90] - 출력 품질
+     */
+    applyWatermark(targetPath, watermarkPath, opacity = 50, format, quality = 90) {
+        if (this._bridge?.mediaApplyWatermark) {
+            return this._bridge.mediaApplyWatermark(targetPath, watermarkPath, opacity, format, quality);
+        }
+        throw new Error('Watermark requires Bridge (Rust).');
+    }
+
+    /**
+     * 비디오에서 N초 간격으로 다중 썸네일을 추출한다.
+     * @param {string} inputPath - 비디오 경로
+     * @param {string} outputDir - 출력 디렉토리
+     * @param {number} [interval=5] - 초 간격
+     * @param {number} [width=320] - 썸네일 가로 크기
+     * @param {string} [format='jpeg'] - 포맷
+     * @returns {string[]} 생성된 파일 경로 목록
+     */
+    videoThumbnails(inputPath, outputDir, interval = 5, width = 320, format = 'jpeg') {
+        if (this._bridge?.mediaVideoThumbnails) {
+            return this._bridge.mediaVideoThumbnails(inputPath, outputDir, interval, width, format);
+        }
+        throw new Error('Video thumbnails requires ffmpeg + Bridge.');
+    }
+
+    /**
+     * 썸네일 목록을 스프라이트 시트(그리드)로 합성한다.
+     * @param {string[]} thumbPaths - 썸네일 경로 목록
+     * @param {string} outputPath - 출력 스프라이트 시트 경로
+     * @param {number} [cols=10] - 그리드 열 수
+     * @param {number} [thumbWidth=160] - 각 썸네일 가로
+     * @param {number} [thumbHeight=0] - 각 썸네일 세로 (0=자동)
+     */
+    videoPreviewSheet(thumbPaths, outputPath, cols = 10, thumbWidth = 160, thumbHeight = 0) {
+        if (this._bridge?.mediaVideoPreviewSheet) {
+            return this._bridge.mediaVideoPreviewSheet(thumbPaths, outputPath, cols, thumbWidth, thumbHeight);
+        }
+        throw new Error('Preview sheet requires Bridge (Rust).');
+    }
 }

package/lib/view/View.js

@@ -1,8 +1,10 @@
 /**
- * View — 뷰 렌더링 (Bridge SSR)
+ * View — 뷰 렌더링 (Bridge Tera SSR)
  *
- * ctx.theme에 따른 테마 경로 해석.
- * Bridge renderTemplateFile N-API로 렌더링.
+ * Bridge의 ssrRenderFile N-API로 Tera 파일 기반 렌더링.
+ * {% extends %}, {% block %}, {% include %}, {{ t(key="...") }} 완전 지원.
+ *
+ * Bridge 없으면 반드시 에러 — 폴백 없음.
  *
  * @see docs/framework/03-views-templates.md
  */
@@ -32,10 +34,10 @@ export default class View {
     }
 
     /**
-     * 템플릿 렌더링 — Bridge renderTemplateFile N-API 사용
+     * 템플릿 렌더링 — Bridge ssrRenderFile N-API 사용
      *
      * 테마 경로 해석 (03-views-templates.md):
-     * 'home' → {viewsPath}/{theme}/pages/home.html
+     * 'home' → ssrRenderFile(viewsPath/{theme}, 'pages/home.html', context, locale)
      *
      * @param {string} template - 'home', 'users/index' 등
      * @param {object} [data] - 템플릿 변수
@@ -43,30 +45,39 @@ export default class View {
      * @returns {string} - 렌더링된 HTML
      */
     render(template, data = {}, theme) {
+        if (!this._bridge) {
+            throw new Error('Bridge not available — cannot render view');
+        }
+
+        if (typeof this._bridge.ssrRenderFile !== 'function') {
+            throw new Error('Bridge ssrRenderFile not available — rebuild with ssr feature');
+        }
+
         const activeTheme = theme || data.theme || this.theme;
         const mergedData = { ...this._globals, ...data, theme: activeTheme };
+        const locale = data.locale || 'ko';
+
+        // Tera glob 루트: views/{theme}/
+        const templateDir = join(this.viewsPath, activeTheme);
+        const contextJson = JSON.stringify(mergedData);
 
-        // 파일 경로 해석: pages/{name}.html 우선
+        // 후보 이름: pages/{template}.html → {template}.html
         const candidates = [
-            join(this.viewsPath, activeTheme, 'pages', `${template}.html`),
-            join(this.viewsPath, activeTheme, `${template}.html`),
+            `pages/${template}.html`,
+            `${template}.html`,
         ];
 
-        // Bridge renderTemplateFile N-API 호출
-        if (this._bridge && typeof this._bridge.renderTemplateFile === 'function') {
-            const contextJson = JSON.stringify(mergedData);
-
-            for (const filePath of candidates) {
-                try {
-                    return this._bridge.renderTemplateFile(filePath, contextJson);
-                } catch {
-                    // 파일 없음 → 다음 후보
+        for (const templateName of candidates) {
+            try {
+                return this._bridge.ssrRenderFile(templateDir, templateName, contextJson, locale);
+            } catch (err) {
+                // 파일 없음 → 다음 후보 (Tera init 에러는 파일 미존재)
+                if (!err.message?.includes('not found') && !err.message?.includes('init failed')) {
+                    throw err; // 렌더링 에러는 그대로 전파
                 }
             }
-
-            throw new Error(`View '${template}' not found. Searched: ${candidates.join(', ')}`);
         }
 
-        throw new Error(`Bridge not available — cannot render view '${template}'`);
+        throw new Error(`View '${template}' not found in theme '${activeTheme}'. Searched: ${candidates.join(', ')}`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.9",
+  "version": "0.1.21",
   "type": "module",
   "description": "Full-stack MVC framework built on @fuzionx/core — Controller, Service, Model, Middleware, DI, EventBus",
   "main": "index.js",
@@ -34,7 +34,7 @@
     "url": "https://github.com/saytohenry/fuzionx"
   },
   "dependencies": {
-    "@fuzionx/core": "^0.1.9",
+    "@fuzionx/core": "^0.1.21",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",