@fuzionx/core 0.1.0 → 0.1.2

package/bin/ruxy-reload.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
-# ruxy reload — YAML 설정 핫 리로드
+# fuzionx reload — YAML 설정 핫 리로드
 #
 # 사용법:
-#   ./ruxy-reload.sh           # 이름으로 PID 검색
-#   ./ruxy-reload.sh <PID>     # 직접 PID 지정
+#   ./fuzionx-reload.sh           # 이름으로 PID 검색
+#   ./fuzionx-reload.sh <PID>     # 직접 PID 지정
 #
 # SIGHUP을 보내면 서버가 YAML을 다시 읽고 보안 설정을 재적용합니다.
 # 서버 재시작 없이 CORS, rate-limit, HSTS, CSP, IP filter, 세션 설정 반영.
@@ -13,12 +13,12 @@ set -e
 if [ -n "$1" ]; then
     PID="$1"
 else
-    # node 프로세스 중 ruxy 관련 검색
-    PID=$(pgrep -f "ruxy|fusion" | head -1)
+    # node 프로세스 중 fuzionx 관련 검색
+    PID=$(pgrep -f "fuzionx|fusion" | head -1)
 fi
 
 if [ -z "$PID" ]; then
-    echo "❌ ruxy 프로세스를 찾을 수 없습니다."
+    echo "❌ fuzionx 프로세스를 찾을 수 없습니다."
     echo "   사용법: $0 <PID>"
     exit 1
 fi

package/index.js

@@ -1 +1 @@
-export { createApp, RuxyApp } from './lib/app.js';
+export { createApp, FuzionXApp } from './lib/app.js';

package/lib/app.js

@@ -1,12 +1,17 @@
 import { createRequire } from 'module';
 import path from 'path';
+import cluster from 'cluster';
+import os from 'os';
 import { Router } from './router.js';
-import { runMiddlewareChain } from './middleware.js';
+import { runMiddlewareChain, runErrorChain } from './middleware.js';
 import { createReq, createRes } from './context.js';
 import { createSession } from './session.js';
 import { createI18n } from './i18n.js';
 import { createWs } from './ws.js';
 import { createCrypto } from './crypto.js';
+import { createFile } from './file.js';
+import { createHash } from './hash.js';
+import { createMedia } from './media.js';
 import { createLogger, interceptConsole } from './logger.js';
 
 const require = createRequire(import.meta.url);
@@ -34,7 +39,7 @@ function loadBridge() {
     throw new Error('fuzionx-bridge native module을 찾을 수 없습니다. npm install @fuzionx/core를 실행해 주세요.');
 }
 
-export class RuxyApp {
+export class FuzionXApp {
     /**
      * @param {object} options
      * @param {string} options.config - YAML 설정 파일 경로
@@ -49,8 +54,16 @@ export class RuxyApp {
         this._booted = false;
         this._port = options.port || 3000;
 
-        // 헬퍼 모듈
+        // 사전 계산된 미들웨어 체인 캐시 (handlerId → handler[])
+        this._chainCache = null;
+        this._globalChain = null;
+        this._errorChain = null;
+
+        // 헬퍼 모듈 — 직통 N-API 호출, 오버헤드 없음
         this.crypto = createCrypto(this._bridge);
+        this.file = createFile(this._bridge);
+        this.hash = createHash(this._bridge);
+        this.media = createMedia(this._bridge);  // utils-media feature 필요
         this._ws = null;  // lazy — get ws() 에서 초기화
         this.i18n = null; // boot 후 초기화
     }
@@ -163,16 +176,74 @@ export class RuxyApp {
         port = port || this._port;
 
         this._boot();
-        this._router.build();
 
+        // ── 워커 수 결정 (0=auto/cpus, 1=단일 프로세스) ──
+        const configWorkers = this._bridge.getWorkerCount();
+        const numWorkers = configWorkers > 0 ? configWorkers : os.cpus().length;
+
+        // ── Primary: cluster.fork() ──
+        if (numWorkers > 1 && cluster.isPrimary) {
+            console.log(`[fuzionx] Primary PID=${process.pid}, spawning ${numWorkers} workers on :${port}`);
+
+            for (let i = 0; i < numWorkers; i++) {
+                cluster.fork();
+            }
+
+            let shuttingDown = false;
+
+            cluster.on('exit', (worker, code) => {
+                console.log(`[fuzionx] Worker ${worker.process.pid} exited (code=${code})`);
+                if (!shuttingDown) {
+                    console.log('[fuzionx] Restarting worker...');
+                    cluster.fork();
+                }
+            });
+
+            // ── Primary Graceful Shutdown ──
+            const gracefulShutdown = (signal) => {
+                if (shuttingDown) return;
+                shuttingDown = true;
+                console.log(`[fuzionx] ${signal} received — shutting down all workers`);
+                for (const id in cluster.workers) {
+                    cluster.workers[id].process.kill('SIGTERM');
+                }
+                setTimeout(() => process.exit(0), 3000);
+            };
+            process.once('SIGTERM', () => gracefulShutdown('SIGTERM'));
+            process.once('SIGINT', () => gracefulShutdown('SIGINT'));
+
+            // ── Primary Hot Reload: SIGHUP → 모든 워커에 전파 ──
+            process.on('SIGHUP', () => {
+                console.log('[fuzionx] SIGHUP — forwarding to all workers');
+                for (const id in cluster.workers) {
+                    cluster.workers[id].process.kill('SIGHUP');
+                }
+            });
+
+            if (callback) setTimeout(() => callback(), 100);
+            return this;
+        }
+
+        // ── Worker (또는 단일 프로세스): Fusion 서버 시작 ──
+        if (cluster.isWorker) {
+            // 워커 프로세스는 독립적으로 boot 필요
+            this._boot();
+        }
+
+        this._router.build();
+        this._buildMiddlewareCache();
         this._bridge.startFusionServer(port, (rawReq) => this._handleRequest(rawReq));
 
-        // ── Graceful Shutdown (SIGTERM/SIGINT) ──
+        if (cluster.isWorker) {
+            console.log(`[fuzionx] Worker PID=${process.pid} on :${port}`);
+        }
+
+        // ── Worker Graceful Shutdown (SIGTERM/SIGINT) ──
         let shutdownCalled = false;
         const gracefulShutdown = (signal) => {
             if (shutdownCalled) return;
             shutdownCalled = true;
-            console.log(`[ruxy] ${signal} received — graceful shutdown`);
+            console.log(`[fuzionx] ${signal} received — graceful shutdown (PID=${process.pid})`);
             this._bridge.stopFusionServer();
             setTimeout(() => process.exit(0), 2000);
         };
@@ -184,9 +255,9 @@ export class RuxyApp {
             try {
                 this._bridge.reloadConfig();
                 this._bridge.reloadFusionConfig();
-                console.log('[ruxy] SIGHUP — config hot-reload complete');
+                console.log(`[fuzionx] SIGHUP — config hot-reload complete (PID=${process.pid})`);
             } catch (e) {
-                console.error('[ruxy] SIGHUP reload failed:', e.message);
+                console.error(`[fuzionx] SIGHUP reload failed (PID=${process.pid}):`, e.message);
             }
         });
 
@@ -194,58 +265,159 @@ export class RuxyApp {
 
         // ── Error Recovery ──
         process.on('uncaughtException', (err) => {
-            console.error('[ruxy] uncaughtException:', err.message);
+            console.error('[fuzionx] uncaughtException:', err.message);
         });
         process.on('unhandledRejection', (reason) => {
-            console.error('[ruxy] unhandledRejection:', reason);
+            console.error('[fuzionx] unhandledRejection:', reason);
         });
 
         if (callback) setTimeout(() => callback(), 100);
         return this;
     }
 
-    /** 요청 처리 — 미들웨어 체인 → 라우트 핸들러 */
-    _handleRequest(rawReq) {
-        const req = createReq(rawReq, this);
-        const res = createRes();
+    /**
+     * 미들웨어 체인 사전 계산.
+     * listen() 시점에 라우트별로 적용 가능한 미들웨어 + 핸들러를 합쳐서 캐시.
+     * _handleRequest()에서 .filter()/.map() 없이 O(1) 조회.
+     */
+    _buildMiddlewareCache() {
+        // 글로벌 미들웨어 (path === null)
+        const globalMw = [];
+        // 경로별 미들웨어 (path !== null)
+        const pathMw = [];
+
+        for (const m of this._middlewares) {
+            if (m.path === null) {
+                globalMw.push(m.handler);
+            } else {
+                pathMw.push(m);
+            }
+        }
 
-        const route = this._router.getHandler(rawReq.handlerId);
+        this._globalChain = globalMw;
+        this._chainCache = new Map();
 
-        // 경로 매치 미들웨어 필터
-        const applicable = this._middlewares.filter(m =>
-            m.path === null || req.url.startsWith(m.path)
-        );
+        // 에러 핸들러도 사전 계산
+        this._errorChain = this._errorHandlers.map(m => m.handler);
 
-        const chain = applicable.map(m => m.handler);
-        if (route) {
-            chain.push(...route);
-        } else {
-            chain.push((_req, _res) => {
-                _res.status(404).json({ error: 'Not Found', path: _req.url });
-            });
+        // 각 라우트별 체인 캐시
+        for (const route of this._router._routes) {
+            const chain = [...globalMw];
+            for (const m of pathMw) {
+                if (route.path.startsWith(m.path) ||
+                    route.path === m.path ||
+                    (m.path.endsWith('/') && route.path.startsWith(m.path))) {
+                    chain.push(m.handler);
+                }
+            }
+            chain.push(...route.handlers);
+            this._chainCache.set(route.handlerId, chain);
         }
 
+        // 404 fallback 체인 (글로벌 미들웨어 + 404 핸들러)
+        this._notFoundChain = [...globalMw, (_req, _res) => {
+            _res.status(404).json({ error: 'Not Found', path: _req.path });
+        }];
+    }
+
+    /** 요청 처리 — 사전 계산된 체인으로 O(1) 조회 */
+    _handleRequest(rawReq) {
+        // sync 경로: 공유 인스턴스 재사용 (할당 0)
+        const req = createReq(rawReq, this, true);
+        const res = createRes(true);
+
+        // O(1) 체인 조회 — .filter()/.map() 없음
+        const chain = this._chainCache.get(rawReq.handlerId) || this._notFoundChain;
+
+        let result;
         try {
-            runMiddlewareChain(chain, req, res);
+            result = runMiddlewareChain(chain, req, res);
         } catch (err) {
-            const errHandlers = this._errorHandlers.filter(m =>
-                m.path === null || req.url.startsWith(m.path)
-            );
-            if (errHandlers.length > 0) {
-                try {
-                    for (const eh of errHandlers) eh.handler(err, req, res, () => {});
-                } catch (_) {
+            this._handleError(err, req, res);
+            return res._toFusionResponse();
+        }
+
+        // Framework 등 외부 핸들러가 직접 { async: true } 반환 시
+        // Rust에 그대로 전달하여 pending_async 등록
+        if (result && result.async === true && typeof result.then !== 'function') {
+            return { async: true };
+        }
+
+        // 핸들러가 Promise를 리턴하면 — 비동기 경로
+        // async 핸들러는 응답 전까지 req/res가 유지되어야 하므로 새 인스턴스 생성
+        if (result && typeof result.then === 'function') {
+            const asyncReq = createReq(rawReq, this, false);
+            const asyncRes = createRes(false);
+            // sync 결과를 asyncRes에 복사 (미들웨어가 이미 설정한 값)
+            asyncRes._statusCode = res._statusCode;
+            asyncRes._body = res._body;
+            asyncRes._sent = res._sent;
+
+            result
+                .then(() => {
+                    this._sendAsyncResponse(rawReq.requestId, asyncRes);
+                })
+                .catch((err) => {
+                    this._handleError(err, asyncReq, asyncRes);
+                    this._sendAsyncResponse(rawReq.requestId, asyncRes);
+                });
+
+            return { async: true };
+        }
+
+        return res._toFusionResponse();
+    }
+
+    /** 에러 핸들링 — 에러 핸들러 체인 or 500 */
+    _handleError(err, req, res) {
+        if (this._errorChain && this._errorChain.length > 0) {
+            try {
+                runErrorChain(this._errorChain, err, req, res);
+            } catch (_) {
+                if (!res._sent) {
                     res.status(500).json({ error: 'Internal Server Error' });
                 }
-            } else {
+            }
+        } else {
+            console.error('[fuzionx] Handler error:', err.message || err);
+            if (!res._sent) {
                 res.status(500).json({ error: err.message || 'Internal Server Error' });
             }
         }
+    }
 
-        return res._toFusionResponse();
+    /** 비동기 응답 전송 — bridge.sendAsyncResponse 호출 */
+    _sendAsyncResponse(requestId, res) {
+        const resp = res._toFusionResponse();
+        const contentType = resp.headers?.['Content-Type'] || 'application/json';
+
+        // Content-Type 외 추가 헤더 → 배열 join (문자열 반복 연결 제거)
+        const headerParts = [];
+        if (resp.headers) {
+            const keys = Object.keys(resp.headers);
+            for (let i = 0; i < keys.length; i++) {
+                const k = keys[i];
+                if (k !== 'Content-Type') {
+                    headerParts.push(k + ': ' + resp.headers[k]);
+                }
+            }
+        }
+        const extraHeaders = headerParts.length > 0 ? headerParts.join('\r\n') + '\r\n' : '';
+
+        try {
+            this._bridge.sendAsyncResponse(
+                requestId,
+                resp.status,
+                resp.body,
+                contentType,
+                extraHeaders,
+            );
+        } catch (e) {
+            console.error('[fuzionx] sendAsyncResponse failed:', e.message);
+        }
     }
 }
 
 export function createApp(options) {
-    return new RuxyApp(options);
+    return new FuzionXApp(options);
 }

package/lib/context.js

@@ -1,150 +1,225 @@
 /**
  * Context — Fusion raw req 객체를 Express 스타일 req/res로 변환.
+ *
+ * 최적화:
+ *   - 프로토타입 기반 + 재사용 가능한 응답 객체
+ *   - Object.defineProperty 제거 → 함수 기반 lazy JSON
+ *   - 요청당 클로저 최소화
+ *   - _toFusionResponse()에서 할당 0
  */
 
-/**
- * Request 래퍼 생성
- * @param {object} rawReq - Fusion 콜백의 raw 요청 객체
- * @param {object} app - RuxyApp 인스턴스
- */
-export function createReq(rawReq, app) {
-    const req = {
-        method: rawReq.method,
-        url: rawReq.url,
-        path: rawReq.url,
-        query: rawReq.query || {},
-        params: rawReq.params || {},
-        headers: rawReq.headers || {},
-        ip: rawReq.remoteIp || '',
-        body: rawReq.body || '',
-        handlerId: rawReq.handlerId,
-        requestId: rawReq.requestId,
-        sessionId: rawReq.sessionId || null,
-        _app: app,
-        _rawSession: rawReq.session || null,
-    };
-
-    // req.json — lazy JSON 파싱
-    let _jsonCache = undefined;
-    Object.defineProperty(req, 'json', {
-        get() {
-            if (_jsonCache === undefined) {
+// ── req.session 프로토타입 ──
+const SessionProto = {
+    get(key) {
+        if (key) return this._data[key] || null;
+        return { ...this._data };
+    },
+    set(key, value) {
+        this._data[key] = String(value);
+        if (this._id) {
+            this._bridge.sessionSet(this._id, { ...this._data });
+        }
+    },
+    destroy() {
+        if (this._id) {
+            this._bridge.sessionDestroy(this._id);
+            this._data = {};
+        }
+    },
+    renew() {
+        if (this._id) {
+            return this._bridge.sessionRenew(this._id);
+        }
+        return null;
+    },
+};
+
+// ── req 프로토타입 ──
+const ReqProto = {
+    /** lazy JSON 파싱 — body가 이미 object면 그대로 반환 */
+    get json() {
+        if (this._json === undefined) {
+            if (typeof this.body === 'object' && this.body !== null) {
+                this._json = this.body;
+            } else {
                 try {
-                    _jsonCache = req.body ? JSON.parse(req.body) : null;
+                    this._json = this.body ? JSON.parse(this.body) : null;
                 } catch (_) {
-                    _jsonCache = null;
+                    this._json = null;
                 }
             }
-            return _jsonCache;
-        },
-    });
-
-    // req.session — 세션 헬퍼
-    const bridge = app._bridge;
-    req.session = {
-        _id: rawReq.sessionId || null,
-        _data: rawReq.session || {},
-
-        get(key) {
-            if (key) return this._data[key] || null;
-            return { ...this._data };
-        },
-
-        set(key, value) {
-            this._data[key] = String(value);
-            if (this._id) {
-                bridge.sessionSet(this._id, { ...this._data });
-            }
-        },
-
-        destroy() {
-            if (this._id) {
-                bridge.sessionDestroy(this._id);
-                this._data = {};
-            }
-        },
-
-        renew() {
-            if (this._id) {
-                return bridge.sessionRenew(this._id);
-            }
-            return null;
-        },
-    };
-
-    // req.t — i18n 번역
-    req.t = (key, defaultValue) => {
+        }
+        return this._json;
+    },
+    /** i18n 번역 */
+    t(key, defaultValue) {
+        const app = this._app;
         if (!app.i18n) return key;
-        // Accept-Language 또는 기본 로케일
-        const locale = req.headers['accept-language']?.split(',')[0]?.split('-')[0] || 'en';
+        const locale = this.headers?.['accept-language']?.split(',')[0]?.split('-')[0] || 'en';
         const result = app.i18n.translate(locale, key);
         if (result == null && defaultValue != null) {
             app.i18n.updateMissing(key, defaultValue);
             return defaultValue;
         }
         return result || defaultValue || key;
-    };
-
-    return req;
-}
+    },
+};
+
+// ── 사전 할당된 session 인스턴스 (재사용) ──
+const _sharedSession = Object.create(SessionProto);
+_sharedSession._id = null;
+_sharedSession._data = {};
+_sharedSession._bridge = null;
+
+// ── 사전 할당된 req/res 인스턴스 (단일 스레드 재사용) ──
+const _sharedReq = Object.create(ReqProto);
+_sharedReq.method = '';
+_sharedReq.url = '';
+_sharedReq.path = '';
+_sharedReq.query = null;
+_sharedReq.params = null;
+_sharedReq.headers = null;
+_sharedReq.ip = '';
+_sharedReq.body = '';
+_sharedReq.handlerId = 0;
+_sharedReq.requestId = 0;
+_sharedReq.sessionId = null;
+_sharedReq.files = null;
+_sharedReq._app = null;
+_sharedReq._json = undefined;
+_sharedReq.session = _sharedSession;
 
 /**
- * Response 래퍼 생성
+ * Request 래퍼 생성 — 프로토타입 기반 + 재사용
+ * @param {object} rawReq - Fusion 콜백의 raw 요청 객체
+ * @param {object} app - FuzionXApp 인스턴스
+ * @param {boolean} [reusable=true] - true면 공유 인스턴스 재사용 (sync용), false면 새로 생성 (async용)
  */
-export function createRes() {
-    const res = {
-        _statusCode: 200,
-        _body: '',
-        _headers: {},
-        _sent: false,
-
-        status(code) {
-            res._statusCode = code;
-            return res;
-        },
-
-        json(data) {
-            res._body = JSON.stringify(data);
-            res._headers['Content-Type'] = 'application/json';
-            res._sent = true;
-            return res;
-        },
-
-        send(text) {
-            res._body = String(text);
-            res._sent = true;
-            return res;
-        },
+export function createReq(rawReq, app, reusable = true) {
+    let req;
+    if (reusable) {
+        // sync 핸들러: 공유 인스턴스 재사용 (할당 0)
+        req = _sharedReq;
+    } else {
+        // async 핸들러: 새 인스턴스 (응답 전까지 유지 필요)
+        req = Object.create(ReqProto);
+    }
+
+    req.method = rawReq.method;
+    req.url = rawReq.url;
+    req.path = rawReq.path;
+    req.query = rawReq.query || null;
+    req.params = rawReq.params || null;
+    req.headers = rawReq.headers || null;
+    req.ip = rawReq.remoteIp || '';
+    req.body = rawReq.body || '';
+    req.handlerId = rawReq.handlerId;
+    req.requestId = rawReq.requestId;
+    req.sessionId = rawReq.sessionId || null;
+    req._app = app;
+    req._json = undefined;
+    req.files = rawReq.files || null;
+    req.formFields = rawReq.formFields || null;
+
+    // session 업데이트 (재사용)
+    if (reusable) {
+        _sharedSession._id = rawReq.sessionId || null;
+        _sharedSession._data = rawReq.session || {};
+        _sharedSession._bridge = app._bridge;
+    } else {
+        const session = Object.create(SessionProto);
+        session._id = rawReq.sessionId || null;
+        session._data = rawReq.session || {};
+        session._bridge = app._bridge;
+        req.session = session;
+    }
 
-        html(content) {
-            res._body = String(content);
-            res._headers['Content-Type'] = 'text/html; charset=utf-8';
-            res._sent = true;
-            return res;
-        },
-
-        redirect(url, code = 302) {
-            res._statusCode = code;
-            res._headers['Location'] = url;
-            res._body = '';
-            res._sent = true;
-            return res;
-        },
-
-        header(key, value) {
-            res._headers[key] = value;
-            return res;
-        },
+    return req;
+}
 
-        /** Fusion 응답 포맷으로 변환 */
-        _toFusionResponse() {
-            return {
-                status: res._statusCode,
-                body: res._body,
-                headers: res._headers,
-            };
-        },
-    };
+// ── Response 프로토타입 ──
+const ResProto = {
+    status(code) {
+        this._statusCode = code;
+        return this;
+    },
+    json(data) {
+        this._body = JSON.stringify(data);
+        this._headers['Content-Type'] = 'application/json';
+        this._sent = true;
+        return this;
+    },
+    send(text) {
+        this._body = String(text);
+        this._sent = true;
+        return this;
+    },
+    html(content) {
+        this._body = String(content);
+        this._headers['Content-Type'] = 'text/html; charset=utf-8';
+        this._sent = true;
+        return this;
+    },
+    redirect(url, code = 302) {
+        this._statusCode = code;
+        this._headers['Location'] = url;
+        this._body = '';
+        this._sent = true;
+        return this;
+    },
+    end() {
+        this._body = '';
+        this._sent = true;
+        return this;
+    },
+    header(key, value) {
+        this._headers[key] = value;
+        return this;
+    },
+    /** Fusion 응답 포맷으로 변환 — 공유 응답 객체 재사용 */
+    _toFusionResponse() {
+        _sharedResponse.status = this._statusCode;
+        _sharedResponse.body = this._body;
+        _sharedResponse.headers = this._headers;
+        return _sharedResponse;
+    },
+};
+
+// ── 사전 할당된 응답 객체 (재사용) ──
+const _sharedResponse = { status: 200, body: '', headers: null };
+const _sharedHeaders = {};
+
+// ── 사전 할당된 res 인스턴스 ──
+const _sharedRes = Object.create(ResProto);
+_sharedRes._statusCode = 200;
+_sharedRes._body = '';
+_sharedRes._headers = _sharedHeaders;
+_sharedRes._sent = false;
 
+/**
+ * Response 래퍼 생성 — 프로토타입 기반 + 재사용
+ * @param {boolean} [reusable=true] - true면 공유 인스턴스 재사용, false면 새로 생성
+ */
+export function createRes(reusable = true) {
+    if (reusable) {
+        // sync: 공유 인스턴스 리셋 후 재사용 (할당 0)
+        _sharedRes._statusCode = 200;
+        _sharedRes._body = '';
+        // headers 객체 재사용 — 이전 키 제거
+        const keys = Object.keys(_sharedHeaders);
+        for (let i = 0; i < keys.length; i++) {
+            delete _sharedHeaders[keys[i]];
+        }
+        _sharedRes._headers = _sharedHeaders;
+        _sharedRes._sent = false;
+        return _sharedRes;
+    }
+
+    // async: 새 인스턴스
+    const res = Object.create(ResProto);
+    res._statusCode = 200;
+    res._body = '';
+    res._headers = {};
+    res._sent = false;
     return res;
 }

package/lib/crypto.js

@@ -19,24 +19,5 @@ export function createCrypto(bridge) {
 
         /** AES-256-GCM 복호화 */
         decrypt: (key, ciphertext) => bridge.cryptoDecryptAes(key, ciphertext),
-
-        /** Nibble 난독화 암호화 (string key → SHA256 wrapping) */
-        encryptCustom: (key, plaintext) => bridge.cryptoEncryptCustom(key, plaintext),
-
-        /** Nibble 난독화 복호화 (string key → SHA256 wrapping) */
-        decryptCustom: (key, ciphertext) => bridge.cryptoDecryptCustom(key, ciphertext),
-
-        /** ASP Transport 암호화 (hex key → raw 32바이트 직접 사용) */
-        encryptTransport: (keyHex, plaintext) => bridge.cryptoEncryptTransport(keyHex, plaintext),
-
-        /** ASP Transport 복호화 (hex key → raw 32바이트 직접 사용) */
-        decryptTransport: (keyHex, ciphertext) => bridge.cryptoDecryptTransport(keyHex, ciphertext),
-
-        /** UA Slice 추출 */
-        getUaSlice: (userAgent, timestamp) => bridge.cryptoGetUaSlice(userAgent, timestamp),
-
-        /** ASP Transport Key 파생 */
-        deriveTransportKey: (masterSecret, domain, path, uaSlice, timestamp) =>
-            bridge.cryptoDeriveTransportKey(masterSecret, domain, path, uaSlice, timestamp),
     };
 }

package/lib/file.js

@@ -0,0 +1,34 @@
+/**
+ * FileHelper — fuzionx-bridge 파일 유틸리티 N-API 래핑.
+ * app.file로 접근.
+ *
+ * 최적화: 모든 호출은 Rust N-API 직통, JS 오버헤드 없음.
+ */
+
+export function createFile(bridge) {
+    return {
+        /** 파일 이동 (cross-device 자동 대응) */
+        move: (src, dst) => bridge.fileMoveFile(src, dst),
+
+        /** 파일 복사 — 복사된 바이트 수 반환 */
+        copy: (src, dst) => bridge.fileCopyFile(src, dst),
+
+        /** 디렉토리 재귀 생성 */
+        ensureDir: (dirPath) => bridge.fileEnsureDir(dirPath),
+
+        /** 파일 크기 (bytes) */
+        size: (filePath) => bridge.fileSize(filePath),
+
+        /** 파일 존재 여부 */
+        exists: (filePath) => bridge.fileExists(filePath),
+
+        /** 파일 삭제 */
+        remove: (filePath) => bridge.fileRemove(filePath),
+
+        /** 임시 파일 경로 생성 (UUID 기반) */
+        tempPath: (prefix) => bridge.fileTempPath(prefix || 'fuzionx'),
+
+        /** 확장자 추출 (소문자, dot 제외) — null 가능 */
+        extension: (filePath) => bridge.fileExtension(filePath),
+    };
+}

package/lib/hash.js

@@ -0,0 +1,22 @@
+/**
+ * HashHelper — fuzionx-bridge 해싱 유틸리티 N-API 래핑.
+ * app.hash로 접근.
+ *
+ * 최적화: Rust bcrypt/argon2 직통 호출, JS crypto 미사용.
+ */
+
+export function createHash(bridge) {
+    return {
+        /** bcrypt 해시 생성 (cost 기본 12) */
+        bcrypt: (password, cost) => bridge.hashBcrypt(password, cost),
+
+        /** bcrypt 해시 검증 */
+        bcryptVerify: (password, hash) => bridge.hashBcryptVerify(password, hash),
+
+        /** argon2id 해시 생성 (랜덤 salt) */
+        argon2: (password) => bridge.hashArgon2(password),
+
+        /** argon2 해시 검증 */
+        argon2Verify: (password, hash) => bridge.hashArgon2Verify(password, hash),
+    };
+}

package/lib/logger.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Ruxy Bridge 통합 로거.
+ * @fileoverview FuzionX Bridge 통합 로거.
  *
  * Rust tracing과 Node.js console을 일원화한다.
  * - createLogger(bridge): app.logger 객체 생성

package/lib/media.js

@@ -0,0 +1,75 @@
+/**
+ * MediaHelper — fuzionx-bridge 미디어(이미지+비디오) N-API 래핑.
+ * app.media로 접근.
+ *
+ * 최적화:
+ *   - 이미지 처리: Rust image+webp crate 직통 (Lanczos3 리사이즈)
+ *   - 비디오: ffmpeg CLI 호출 (Rust std::process::Command)
+ *   - JS 힙 메모리 무할당 — 파일-to-파일 처리
+ */
+
+export function createMedia(bridge) {
+    return {
+        // ── 이미지 ──
+
+        /**
+         * 이미지 리사이즈 (종횡비 유지).
+         * @param {string} input - 입력 파일 경로
+         * @param {string} output - 출력 파일 경로
+         * @param {number} width - 최대 가로
+         * @param {number} height - 최대 세로
+         * @param {string} [format='webp'] - 출력 포맷
+         * @param {number} [quality=80] - 품질 (1-100)
+         * @returns {string} 출력 경로
+         */
+        resize: (input, output, width, height, format, quality) =>
+            bridge.mediaResize(input, output, width, height, format, quality),
+
+        /**
+         * 다중 사이즈 리사이즈 (한 번의 디코드로 여러 출력).
+         * @param {string} input - 입력 파일 경로
+         * @param {string} outputDir - 출력 디렉토리
+         * @param {string} baseName - 기본 파일명
+         * @param {Array<{width:number,height:number,format?:string,quality?:number,suffix:string}>} specs
+         * @returns {string[]} 출력 경로 배열
+         */
+        resizeMultiple: (input, outputDir, baseName, specs) =>
+            bridge.mediaResizeMultiple(input, outputDir, baseName, specs),
+
+        /**
+         * 이미지 정보 조회.
+         * @returns {{width:number, height:number, format:string}}
+         */
+        imageInfo: (filePath) => bridge.mediaGetImageInfo(filePath),
+
+        /**
+         * WebP 변환.
+         * @param {string} input - 입력 경로
+         * @param {string} output - 출력 경로
+         * @param {number} [quality=80] - 품질
+         * @returns {string} 출력 경로
+         */
+        toWebp: (input, output, quality) =>
+            bridge.mediaConvertToWebp(input, output, quality),
+
+        // ── 비디오 ──
+
+        /**
+         * 비디오 썸네일 추출 (ffmpeg).
+         * @param {string} input - 비디오 경로
+         * @param {string} output - 출력 이미지 경로
+         * @param {number} [atSeconds=3] - 캡처 시점 (초)
+         * @param {number} [width=0] - 출력 가로 (0=원본)
+         * @param {string} [format='jpeg'] - 출력 포맷
+         * @returns {string} 출력 경로
+         */
+        videoThumbnail: (input, output, atSeconds, width, format) =>
+            bridge.mediaVideoThumbnail(input, output, atSeconds, width, format),
+
+        /**
+         * 비디오 정보 조회 (ffprobe).
+         * @returns {{duration:number, width:number, height:number, codec:string, fps:number}}
+         */
+        videoInfo: (filePath) => bridge.mediaVideoInfo(filePath),
+    };
+}

package/lib/middleware.js

@@ -1,8 +1,8 @@
 /**
- * Middleware — Express 스타일 동기 미들웨어 체인 엔진.
+ * Middleware — 동기 + 비동기 미들웨어 체인 엔진.
  *
- * Fusion 콜백은 동기 응답을 기대하므로 async를 지원하지 않음.
- * next()를 호출하면 다음 미들웨어로 진행.
+ * Express 호환: next()가 Promise를 반환하면 체인 전체가 async로 전파.
+ * Fusion 콜백에서 Promise가 감지되면 bridge의 sendAsyncResponse로 처리.
  */
 
 /**
@@ -10,17 +10,50 @@
  * @param {Function[]} handlers - (req, res, next) 핸들러 배열
  * @param {object} req
  * @param {object} res
+ * @returns {undefined|Promise} 비동기 핸들러가 있으면 Promise 리턴
  */
 export function runMiddlewareChain(handlers, req, res) {
     let index = 0;
+    const len = handlers.length;
 
     function next(err) {
         if (err) throw err;
-        if (res._sent || index >= handlers.length) return;
+        if (res._sent || index >= len) return;
 
         const handler = handlers[index++];
-        handler(req, res, next);
+        const result = handler(req, res, next);
+
+        // 핸들러가 Promise를 리턴하면 (async 함수) → 전파
+        // 이후 체인은 Promise 안에서 이미 next()로 실행됨
+        return result;
+    }
+
+    return next();
+}
+
+/**
+ * 에러 핸들러 체인 실행
+ * @param {Function[]} handlers - (err, req, res, next) 핸들러 배열
+ * @param {Error} err
+ * @param {object} req
+ * @param {object} res
+ */
+export function runErrorChain(handlers, err, req, res) {
+    let index = 0;
+    const len = handlers.length;
+
+    function next(nextErr) {
+        if (res._sent || index >= len) return;
+        const handler = handlers[index++];
+        try {
+            handler(nextErr || err, req, res, next);
+        } catch (e) {
+            // 에러 핸들러가 또 throw하면 다음 핸들러로
+            if (index < len) {
+                next(e);
+            }
+        }
     }
 
-    next();
+    next(err);
 }

package/lib/ws.js

@@ -13,7 +13,7 @@
 /**
  * 개별 WebSocket 연결을 나타내는 래퍼.
  */
-class RuxySocket {
+class FuzionXSocket {
     constructor(sessionId, bridge) {
         this._bridge = bridge;
         this.sessionId = sessionId;
@@ -111,7 +111,7 @@ export function createWs(bridge) {
         bridge.wsOnConnect((namespace, sessionId) => {
             const ns = namespaces.get(namespace);
             if (ns && ns._handlers.connect) {
-                ns._handlers.connect(new RuxySocket(sessionId, bridge));
+                ns._handlers.connect(new FuzionXSocket(sessionId, bridge));
             }
         });
 
@@ -119,7 +119,7 @@ export function createWs(bridge) {
         bridge.wsOnMessage((namespace, sessionId, message) => {
             const ns = namespaces.get(namespace);
             if (ns && ns._handlers.message) {
-                ns._handlers.message(new RuxySocket(sessionId, bridge), message);
+                ns._handlers.message(new FuzionXSocket(sessionId, bridge), message);
             }
         });
 
@@ -127,7 +127,7 @@ export function createWs(bridge) {
         bridge.wsOnDisconnect((namespace, sessionId) => {
             const ns = namespaces.get(namespace);
             if (ns && ns._handlers.disconnect) {
-                ns._handlers.disconnect(new RuxySocket(sessionId, bridge));
+                ns._handlers.disconnect(new FuzionXSocket(sessionId, bridge));
             }
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Express-style Node.js framework powered by FuzionX native bridge — 167K RPS single process",
   "main": "index.js",
@@ -18,7 +18,7 @@
     "url": "https://github.com/saytohenry/fuzionx"
   },
   "dependencies": {
-    "@fuzionx/bridge": "^0.1.0"
+    "@fuzionx/bridge": "^0.1.2"
   },
   "files": [
     "index.js",

package/types/index.d.ts

@@ -1,11 +1,19 @@
-// TypeScript 타입 정의 — ruxy framework
+// TypeScript 타입 정의 — fuzionx framework
 
-export interface RuxyOptions {
+export interface FuzionXOptions {
     config: string;
     port?: number;
 }
 
-export interface RuxyRequest {
+export interface UploadedFile {
+    fieldName: string;
+    originalName: string;
+    mimeType: string;
+    size: number;
+    tempPath: string;
+}
+
+export interface FuzionXRequest {
     method: string;
     url: string;
     path: string;
@@ -18,22 +26,23 @@ export interface RuxyRequest {
     handlerId: number;
     requestId: number;
     sessionId: string | null;
+    files: UploadedFile[] | null;
     session: SessionHelper;
     t: (key: string, defaultValue?: string) => string;
 }
 
-export interface RuxyResponse {
-    status(code: number): RuxyResponse;
-    json(data: any): RuxyResponse;
-    send(text: string): RuxyResponse;
-    html(content: string): RuxyResponse;
-    redirect(url: string, code?: number): RuxyResponse;
-    header(key: string, value: string): RuxyResponse;
+export interface FuzionXResponse {
+    status(code: number): FuzionXResponse;
+    json(data: any): FuzionXResponse;
+    send(text: string): FuzionXResponse;
+    html(content: string): FuzionXResponse;
+    redirect(url: string, code?: number): FuzionXResponse;
+    header(key: string, value: string): FuzionXResponse;
 }
 
 export type NextFunction = (err?: Error) => void;
-export type RequestHandler = (req: RuxyRequest, res: RuxyResponse, next: NextFunction) => void;
-export type ErrorHandler = (err: Error, req: RuxyRequest, res: RuxyResponse, next: NextFunction) => void;
+export type RequestHandler = (req: FuzionXRequest, res: FuzionXResponse, next: NextFunction) => void;
+export type ErrorHandler = (err: Error, req: FuzionXRequest, res: FuzionXResponse, next: NextFunction) => void;
 
 export interface SessionHelper {
     get(key?: string): any;
@@ -77,12 +86,64 @@ export interface CryptoHelper {
     deriveTransportKey(sessionKey: string, uaSlice: string): string;
 }
 
-export declare class RuxyApp {
-    constructor(options?: RuxyOptions);
+export interface FileHelper {
+    move(src: string, dst: string): void;
+    copy(src: string, dst: string): number;
+    ensureDir(dirPath: string): void;
+    size(filePath: string): number;
+    exists(filePath: string): boolean;
+    remove(filePath: string): boolean;
+    tempPath(prefix?: string): string;
+    extension(filePath: string): string | null;
+}
+
+export interface HashHelper {
+    bcrypt(password: string, cost?: number): string;
+    bcryptVerify(password: string, hash: string): boolean;
+    argon2(password: string): string;
+    argon2Verify(password: string, hash: string): boolean;
+}
+
+export interface ResizeSpec {
+    width: number;
+    height: number;
+    format?: string;
+    quality?: number;
+    suffix: string;
+}
+
+export interface ImageInfo {
+    width: number;
+    height: number;
+    format: string;
+}
+
+export interface VideoInfo {
+    duration: number;
+    width: number;
+    height: number;
+    codec: string;
+    fps: number;
+}
+
+export interface MediaHelper {
+    resize(input: string, output: string, width: number, height: number, format?: string, quality?: number): string;
+    resizeMultiple(input: string, outputDir: string, baseName: string, specs: ResizeSpec[]): string[];
+    imageInfo(filePath: string): ImageInfo;
+    toWebp(input: string, output: string, quality?: number): string;
+    videoThumbnail(input: string, output: string, atSeconds?: number, width?: number, format?: string): string;
+    videoInfo(filePath: string): VideoInfo;
+}
+
+export declare class FuzionXApp {
+    constructor(options?: FuzionXOptions);
 
     readonly config: Record<string, any>;
     readonly appConfig: Record<string, any>;
     readonly crypto: CryptoHelper;
+    readonly file: FileHelper;
+    readonly hash: HashHelper;
+    readonly media: MediaHelper;
     readonly ws: WsHelper | null;
     readonly i18n: I18nHelper | null;
 
@@ -99,4 +160,5 @@ export declare class RuxyApp {
     listen(callback: () => void): this;
 }
 
-export declare function createApp(options?: RuxyOptions): RuxyApp;
+export declare function createApp(options?: FuzionXOptions): FuzionXApp;
+