@fuzionx/framework 0.1.20 → 0.1.22

package/lib/core/Application.js

@@ -245,6 +245,18 @@ export default class Application {
     async boot() {
         if (this._booted) return;
 
+        // 0. Bridge 초기화 — boot 로직 전에 bridge 확보
+        //    Helper(crypto/hash/media/file/i18n/logger/view)가 boot 중 bridge 필요
+        if (FuzionXApp && !this._coreApp) {
+            this._coreApp = new FuzionXApp({
+                config: this.configPath
+                    ? path.resolve(this.baseDir, this.configPath)
+                    : undefined,
+            });
+            this._bridge = this._coreApp._bridge;
+            this._propagateBridge();
+        }
+
         // 1. .env 로드 (17-config.md)
         this.config.loadEnv(this.baseDir);
         // .env 로드 후 캐시 클리어 (새로운 환경변수 반영)
@@ -307,6 +319,21 @@ export default class Application {
         await this.emit('booted');
     }
 
+    /**
+     * Bridge 참조를 모든 Helper 인스턴스에 전파
+     * @private
+     */
+    _propagateBridge() {
+        if (!this._bridge) return;
+        if (this._view) this._view._bridge = this._bridge;
+        if (this.logger) this.logger._bridge = this._bridge;
+        if (this.crypto) this.crypto._bridge = this._bridge;
+        if (this.hash) this.hash._bridge = this._bridge;
+        if (this.media) this.media._bridge = this._bridge;
+        if (this.file) this.file._bridge = this._bridge;
+        if (this.i18n) this.i18n._bridge = this._bridge;
+    }
+
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     //  서버 시작 — Bridge 연결
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -323,34 +350,22 @@ export default class Application {
 
         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');
 
-        // Bridge 연동
-        if (FuzionXApp) {
-            if (!this._coreApp) {
-                this._coreApp = new FuzionXApp({
-                    config: this.configPath
-                        ? path.resolve(this.baseDir, this.configPath)
-                        : undefined,
-                    port,
-                });
-                // FuzionXApp 생성 후 Bridge 전파 — boot() 시점에는 null이었음
-                this._bridge = this._coreApp._bridge;
-                if (this._bridge) {
-                    if (this._view) this._view._bridge = this._bridge;
-                    if (this.logger) this.logger._bridge = this._bridge;
-                    if (this.crypto) this.crypto._bridge = this._bridge;
-                    if (this.hash) this.hash._bridge = this._bridge;
-                    if (this.media) this.media._bridge = this._bridge;
-                    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;
-            }
+        // Bridge 연동 — _coreApp은 boot()에서 이미 생성됨
+        if (this._coreApp) {
+            // boot()에서 port 없이 생성됐으므로 port 설정
+            this._coreApp._port = port;
+
+            // WS proxy 연결 (WsHandler에서 this.app.ws 사용)
+            if (!this.ws) this.ws = this._coreApp.ws;
+
             this._registerBridgeRoutes(this._coreApp);
 
             // WsHandler → Bridge WS 이벤트 연결
@@ -524,14 +539,15 @@ export default class Application {
             const eventMap = HandlerClass.buildEventMap();
             const wsNs = coreApp.ws(namespace);
 
+            // 싱글톤 인스턴스 — 연결/메시지/해제에서 동일 인스턴스 사용
+            const inst = new HandlerClass(this);
+
             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 }; }
@@ -553,7 +569,6 @@ export default class Application {
             });
 
             wsNs.on('disconnect', (socket) => {
-                const inst = new HandlerClass(this);
                 console.log(`[WS] disconnect: ${namespace} sid=${socket.sessionId}`);
                 inst.onDisconnect(socket);
             });
@@ -602,7 +617,7 @@ export default class Application {
             }, this);
 
             // Framework → async 체인 실행 후 직접 sendAsyncResponse
-            const promise = this._executeChain(middlewareFns, route, ctx, res);
+            const promise = this._executeChain(middlewareFns, route, ctx);
 
             promise.then(() => {
                 const response = ctx.toResponse();
@@ -643,7 +658,7 @@ export default class Application {
      * 미들웨어 체인 + 핸들러 실행
      * @private
      */
-    async _executeChain(middlewareFns, route, ctx, res) {
+    async _executeChain(middlewareFns, route, ctx) {
         let idx = 0;
 
         const next = async () => {
@@ -674,18 +689,7 @@ export default class Application {
             }
             if (!handled) this._errorHandler.handle(err, ctx);
         }
-
-        // Context → Bridge res 변환 (이중 응답 방지 — Core res는 _sent 사용)
-        if (!res._sent) {
-            const response = ctx.toResponse();
-            res.status(response.status);
-            if (response.headers) {
-                for (const [k, v] of Object.entries(response.headers)) {
-                    res.header(k, v);
-                }
-            }
-            res.send(response.body);
-        }
+        // 응답은 _createBridgeHandler의 .then()에서 sendAsyncResponse로 전송
     }
 
     /**

package/lib/core/AutoLoader.js

@@ -106,8 +106,13 @@ export default class AutoLoader {
      */
     static registerController(ControllerClass) {
         const proto = ControllerClass.prototype;
+        // Base 프로토타입 메서드 스킵 (Controller.register와 동일 로직)
+        const baseNames = new Set(Object.getOwnPropertyNames(
+            Object.getPrototypeOf(proto) // Base.prototype (Controller extends Base)
+        ));
         for (const method of Object.getOwnPropertyNames(proto)) {
             if (method === 'constructor') continue;
+            if (baseNames.has(method)) continue;
             if (typeof proto[method] !== 'function') continue;
             // static property로 __handler__ 디스크립터 등록
             ControllerClass[method] = {
@@ -140,7 +145,7 @@ export default class AutoLoader {
             const mod = await import(file);
             const MwClass = mod.default;
             if (!MwClass) continue;
-            const mwName = MwClass.name || extractName(file, 'Middleware').toLowerCase();
+            const mwName = MwClass.alias || extractName(file, 'Middleware').toLowerCase();
             this.app._middlewareRegistry.set(mwName, MwClass);
         }
     }

package/lib/core/Config.js

@@ -38,7 +38,8 @@ export default class Config {
 
         try {
             const content = readFileSync(configPath, 'utf-8');
-            const parsed = Config.parseYaml(content);
+            const raw = Config.parseYaml(content);
+            const parsed = Config.resolveEnvVars(raw);
 
             // _raw에 병합 (기존 opts.config 우선)
             for (const [key, value] of Object.entries(parsed)) {

package/lib/core/Context.js

@@ -175,9 +175,14 @@ export default class Context {
         return this;
     }
 
-    send(text) {
-        this._body = String(text);
-        this._headers['Content-Type'] = 'text/html; charset=utf-8';
+    send(data) {
+        if (typeof data === 'object' && data !== null) {
+            return this.json(data);
+        }
+        this._body = String(data);
+        if (!this._headers['Content-Type']) {
+            this._headers['Content-Type'] = 'text/html; charset=utf-8';
+        }
         this._sent = true;
         return this;
     }

package/lib/database/ConnectionManager.js

@@ -139,7 +139,23 @@ export default class ConnectionManager {
             case 'mongo': {
                 const mongoose = tryRequire('mongoose');
                 if (!mongoose) return this._createStub('mongo', config);
-                return { type: 'mongo', mongoose, config };
+                // Lazy connect — promise 캐싱으로 이중 연결 방지
+                const conn = { type: 'mongo', mongoose, config, _connected: false, _connectPromise: null };
+                conn.connect = () => {
+                    if (conn._connected) return Promise.resolve();
+                    if (conn._connectPromise) return conn._connectPromise;
+                    const uri = config.uri || config.url
+                        || `mongodb://${config.host || '127.0.0.1'}:${config.port || 27017}/${config.database || ''}`;
+                    conn._connectPromise = mongoose.connect(uri, config.options || {}).then(() => {
+                        conn._connected = true;
+                    });
+                    return conn._connectPromise;
+                };
+                // 즉시 연결 시작 (await 없이 — 백그라운드)
+                conn.connect().catch(err => {
+                    console.error(`[ConnectionManager] MongoDB 연결 실패: ${err.message}`);
+                });
+                return conn;
             }
 
             default:

package/lib/database/SqlModel.js

@@ -94,9 +94,10 @@ export default class SqlModel extends Model {
         }
 
         if (conn.type === 'sqlite' && conn.db) {
-            const columns = Object.keys(insertData);
+            const columns = Object.keys(insertData).map(c => SqlQueryBuilder._sanitizeName(c));
             const placeholders = columns.map(() => '?').join(', ');
-            const sql = `INSERT INTO ${this.table} (${columns.join(', ')}) VALUES (${placeholders})`;
+            const safeTable = SqlQueryBuilder._sanitizeName(this.table);
+            const sql = `INSERT INTO ${safeTable} (${columns.join(', ')}) VALUES (${placeholders})`;
             const result = conn.db.prepare(sql).run(...Object.values(insertData));
             const id = result.lastInsertRowid;
             return new this({ ...insertData, [this.primaryKey]: Number(id) });
@@ -207,9 +208,11 @@ export default class SqlModel extends Model {
         const conn = this.constructor.getConnection();
 
         if (conn.type === 'sqlite' && conn.db) {
-            const columns = Object.keys(data);
+            const columns = Object.keys(data).map(c => SqlQueryBuilder._sanitizeName(c));
+            const pk = SqlQueryBuilder._sanitizeName(this.constructor.primaryKey);
+            const safeTable = SqlQueryBuilder._sanitizeName(this.constructor.table);
             const sets = columns.map(c => `${c} = ?`).join(', ');
-            const sql = `UPDATE ${this.constructor.table} SET ${sets} WHERE ${pk} = ?`;
+            const sql = `UPDATE ${safeTable} SET ${sets} WHERE ${pk} = ?`;
             conn.db.prepare(sql).run(...Object.values(data), id);
         } else if (conn.type === 'knex' && conn.db) {
             await conn.db(this.constructor.table).where(pk, id).update(data);
@@ -244,7 +247,9 @@ export default class SqlModel extends Model {
         const conn = this.constructor.getConnection();
 
         if (conn.type === 'sqlite' && conn.db) {
-            conn.db.prepare(`DELETE FROM ${this.constructor.table} WHERE ${pk} = ?`).run(id);
+            const safeTable = SqlQueryBuilder._sanitizeName(this.constructor.table);
+            const safePk = SqlQueryBuilder._sanitizeName(pk);
+            conn.db.prepare(`DELETE FROM ${safeTable} WHERE ${safePk} = ?`).run(id);
         } else if (conn.type === 'knex' && conn.db) {
             await conn.db(this.constructor.table).where(pk, id).delete();
         }

package/lib/database/SqlQueryBuilder.js

@@ -7,12 +7,26 @@
  * @see docs/framework/02-database-orm.md
  */
 import QueryBuilder from './QueryBuilder.js';
+import Pagination from './Pagination.js';
 
 export default class SqlQueryBuilder extends QueryBuilder {
     constructor(model) {
         super(model);
     }
 
+    /**
+     * SQL 식별자(컬럼명/테이블명) 유효성 검증 — SQL Injection 방지
+     * @param {string} name
+     * @returns {string}
+     * @private
+     */
+    static _sanitizeName(name) {
+        if (typeof name !== 'string' || !/^[\w.]+$/.test(name)) {
+            throw new Error(`Invalid SQL identifier: '${name}'`);
+        }
+        return name;
+    }
+
     /**
      * 결과 조회 — SQL SELECT 실행
      * @returns {Promise<Array<import('./Model.js').default>>}
@@ -117,7 +131,8 @@ export default class SqlQueryBuilder extends QueryBuilder {
 
         if (conn.type === 'sqlite' && conn.db) {
             const { whereClause, whereParams } = this._buildWhereSql();
-            const sql = `DELETE FROM ${this._model.table}${whereClause}`;
+            const safeTable = SqlQueryBuilder._sanitizeName(this._model.table);
+            const sql = `DELETE FROM ${safeTable}${whereClause}`;
             const result = conn.db.prepare(sql).run(...whereParams);
             return result.changes;
         }
@@ -141,13 +156,7 @@ export default class SqlQueryBuilder extends QueryBuilder {
         this._limit = perPage;
         this._offset = (page - 1) * perPage;
         const data = await this.get();
-        return {
-            data,
-            page,
-            perPage,
-            total,
-            lastPage: Math.ceil(total / perPage),
-        };
+        return new Pagination(data, total, page, perPage);
     }
 
     // ━━━━━━━━━━ SQLite 실행 ━━━━━━━━━━
@@ -161,13 +170,15 @@ export default class SqlQueryBuilder extends QueryBuilder {
 
         const selectColumns = mode === 'count'
             ? 'COUNT(*) as cnt'
-            : (this._selects ? this._selects.join(', ') : '*');
+            : (this._selects ? this._selects.map(c => SqlQueryBuilder._sanitizeName(c)).join(', ') : '*');
+
+        const safeTable = SqlQueryBuilder._sanitizeName(this._model.table);
 
-        let sql = `SELECT ${selectColumns} FROM ${this._model.table}${whereClause}`;
+        let sql = `SELECT ${selectColumns} FROM ${safeTable}${whereClause}`;
 
         // ORDER BY
         if (this._orders.length > 0 && mode !== 'count') {
-            const orderParts = this._orders.map(o => `${o.column} ${o.direction.toUpperCase()}`);
+            const orderParts = this._orders.map(o => `${SqlQueryBuilder._sanitizeName(o.column)} ${o.direction.toUpperCase()}`);
             sql += ` ORDER BY ${orderParts.join(', ')}`;
         }
 
@@ -204,20 +215,21 @@ export default class SqlQueryBuilder extends QueryBuilder {
         }
 
         for (const w of this._wheres) {
+            const safeKey = SqlQueryBuilder._sanitizeName(w.key);
             const prefix = parts.length > 0
                 ? (w.type === 'or' ? ' OR ' : ' AND ')
                 : '';
 
             if (w.op === 'IN') {
                 const placeholders = w.value.map(() => '?').join(', ');
-                parts.push(`${prefix}${w.key} IN (${placeholders})`);
+                parts.push(`${prefix}${safeKey} IN (${placeholders})`);
                 params.push(...w.value);
             } else if (w.op === 'IS NULL') {
-                parts.push(`${prefix}${w.key} IS NULL`);
+                parts.push(`${prefix}${safeKey} IS NULL`);
             } else if (w.op === 'IS NOT NULL') {
-                parts.push(`${prefix}${w.key} IS NOT NULL`);
+                parts.push(`${prefix}${safeKey} IS NOT NULL`);
             } else {
-                parts.push(`${prefix}${w.key} ${w.op} ?`);
+                parts.push(`${prefix}${safeKey} ${w.op} ?`);
                 params.push(w.value);
             }
         }
@@ -233,8 +245,8 @@ export default class SqlQueryBuilder extends QueryBuilder {
     _buildUpdateSql(data) {
         const { whereClause, whereParams } = this._buildWhereSql();
         const columns = Object.keys(data);
-        const sets = columns.map(c => `${c} = ?`).join(', ');
-        const sql = `UPDATE ${this._model.table} SET ${sets}${whereClause}`;
+        const sets = columns.map(c => `${SqlQueryBuilder._sanitizeName(c)} = ?`).join(', ');
+        const sql = `UPDATE ${SqlQueryBuilder._sanitizeName(this._model.table)} SET ${sets}${whereClause}`;
         const params = [...Object.values(data), ...whereParams];
         return { sql, params };
     }

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/http/Middleware.js

@@ -8,7 +8,7 @@ import Base from '../core/Base.js';
 
 export default class Middleware extends Base {
     /** @type {string} 미들웨어 등록 이름 (라우트에서 참조) */
-    static name = '';
+    static alias = '';
 
     /**
      * 미들웨어 핸들러 (서브클래스에서 오버라이드)

package/lib/middleware/index.js

@@ -4,6 +4,7 @@
  * @see docs/framework/12-middleware.md
  * @see docs/framework/14-authentication.md
  */
+import { createHmac, timingSafeEqual } from 'node:crypto';
 
 /**
  * JSON/Form body 파싱 미들웨어
@@ -200,7 +201,6 @@ function decodeJwtPayload(token, secret) {
         const [headerB64, payloadB64, signatureB64] = parts;
 
         // ── HMAC-SHA256 서명 검증 ──
-        const { createHmac, timingSafeEqual } = require('node:crypto');
         const signingInput = `${headerB64}.${payloadB64}`;
         const expectedSig = createHmac('sha256', secret)
             .update(signingInput)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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.20",
+    "@fuzionx/core": "^0.1.22",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",