@fuzionx/core 0.1.43 → 0.1.45

package/lib/app.js

@@ -1,433 +1,433 @@
-import { createRequire } from 'module';
-import path from 'path';
-import cluster from 'cluster';
-import os from 'os';
-import { Router } from './router.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);
-
-/**
- * fuzionx-bridge native module 로드.
- * 순서: @fuzionx/bridge (npm) → fuzionx-bridge (로컬 dev) → .node 파일 직접
- */
-function loadBridge() {
-    // 1. npm 설치된 @fuzionx/bridge
-    try { return require('@fuzionx/bridge'); } catch (_) {}
-
-    // 2. 로컬 개발 환경 (file: 또는 workspace 의존성)
-    try { return require('fuzionx-bridge'); } catch (_) {}
-
-    throw new Error(
-        'fuzionx-bridge native module을 찾을 수 없습니다. ' +
-        'npm install @fuzionx/bridge 또는 package.json에 workspace 의존성을 추가하세요.'
-    );
-}
-
-export class FuzionXApp {
-    /**
-     * @param {object} options
-     * @param {string} options.config - YAML 설정 파일 경로
-     * @param {number} [options.port=3000] - 서버 포트
-     */
-    constructor(options = {}) {
-        this._bridge = loadBridge();
-        this._router = new Router(this._bridge);
-        this._middlewares = [];
-        this._errorHandlers = [];
-        this._options = options;
-        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 후 초기화
-    }
-
-    /** YAML boot — 설정 파일 로드 */
-    _boot() {
-        if (this._booted) return;
-        const configPath = this._options.config;
-        if (!configPath) {
-            throw new Error('config 옵션이 필요합니다 (YAML 파일 경로)');
-        }
-        this._bridge.bootSystem({ configPath: path.resolve(configPath) });
-        this._booted = true;
-        this.i18n = createI18n(this._bridge);
-
-        // 통합 로거 초기화
-        this.logger = createLogger(this._bridge);
-
-        // console.* 가로채기 (YAML intercept_console 설정에 따름)
-        const cfg = this._bridge.getConfig();
-        if (cfg.interceptConsole !== false) {
-            this._restoreConsole = interceptConsole(this._bridge);
-        }
-
-        // 앱 로그 파일 초기화 (YAML logging.file.enabled 시)
-        if (cfg.logFilePath) {
-            try {
-                this._bridge.initAppFileLogger(cfg.logFilePath);
-            } catch (e) {
-                // 파일 로거 실패해도 서버는 계속 동작
-                this.logger.warn(`앱 파일 로거 초기화 실패: ${e.message}`);
-            }
-        }
-    }
-
-    /** WebSocket 매니저 (lazy init — listen() 전에도 사용 가능) */
-    get ws() {
-        this._boot();
-        if (!this._ws) {
-            this._ws = createWs(this._bridge);
-        }
-        return this._ws;
-    }
-
-    /** 서버 설정값 */
-    get config() {
-        this._boot();
-        return this._bridge.getConfig();
-    }
-
-    /** 앱 커스텀 설정값 */
-    get appConfig() {
-        this._boot();
-        return this._bridge.getAppConfig();
-    }
-
-    /** ASP (Alloy Stealth Protocol) 설정값 */
-    get aspConfig() {
-        this._boot();
-        return JSON.parse(this._bridge.getAspConfig());
-    }
-
-    /**
-     * Tera SSR 파일 렌더링 ({% extends %}, {% block %}, {% include %} 완전 지원)
-     * @param {string} templateDir - 테마 디렉토리 (views/{theme}/)
-     * @param {string} templateName - 템플릿 이름 (pages/home.html)
-     * @param {object} [context={}] - 템플릿 변수
-     * @param {string} [locale='ko'] - 로케일
-     * @returns {string} 렌더링된 HTML
-     */
-    renderFile(templateDir, templateName, context = {}, locale = 'ko') {
-        this._boot();
-        return this._bridge.ssrRenderFile(templateDir, templateName, JSON.stringify(context), locale);
-    }
-
-    /**
-     * 경량 템플릿 파일 렌더링 (bridge에서 파일 읽기 + {{key}} 치환)
-     * @param {string} filePath - 템플릿 파일 경로
-     * @param {object} [context={}] - 치환 변수
-     * @returns {string} 렌더링된 HTML
-     */
-    render(filePath, context = {}) {
-        this._boot();
-        return this._bridge.renderTemplateFile(filePath, JSON.stringify(context));
-    }
-
-    // ── HTTP Method 라우트 등록 ──
-
-    get(routePath, ...handlers) { this._router.add('GET', routePath, handlers); return this; }
-    post(routePath, ...handlers) { this._router.add('POST', routePath, handlers); return this; }
-    put(routePath, ...handlers) { this._router.add('PUT', routePath, handlers); return this; }
-    delete(routePath, ...handlers) { this._router.add('DELETE', routePath, handlers); return this; }
-    patch(routePath, ...handlers) { this._router.add('PATCH', routePath, handlers); return this; }
-
-    /**
-     * 미들웨어 등록
-     * @param {string|Function} pathOrHandler
-     * @param {...Function} handlers
-     */
-    use(pathOrHandler, ...handlers) {
-        if (typeof pathOrHandler === 'function') {
-            const all = [pathOrHandler, ...handlers];
-            for (const h of all) {
-                const target = h.length === 4 ? this._errorHandlers : this._middlewares;
-                target.push({ path: null, handler: h });
-            }
-        } else {
-            for (const h of handlers) {
-                const target = h.length === 4 ? this._errorHandlers : this._middlewares;
-                target.push({ path: pathOrHandler, handler: h });
-            }
-        }
-        return this;
-    }
-
-    /**
-     * Fusion 서버 시작
-     * @param {number} [port]
-     * @param {Function} [callback]
-     */
-    listen(port, callback) {
-        if (typeof port === 'function') { callback = port; port = this._port; }
-        port = port || this._port;
-
-        this._boot();
-
-        // ── 워커 수 결정 (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');
-                }
-                const shutdownTimeout = this._appConfig?.shutdown_timeout || 5000;
-                setTimeout(() => process.exit(0), shutdownTimeout);
-            };
-            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) setImmediate(() => callback());
-            return this;
-        }
-
-        // ── Worker (또는 단일 프로세스): Fusion 서버 시작 ──
-        if (cluster.isWorker) {
-            // 워커 프로세스는 독립적으로 boot 필요
-            this._boot();
-        }
-
-        this._router.build();
-        this._buildMiddlewareCache();
-        this._bridge.startFusionServer(port, (rawReq) => this._handleRequest(rawReq));
-
-        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(`[fuzionx] ${signal} received — graceful shutdown (PID=${process.pid})`);
-            this._bridge.stopFusionServer();
-            const shutdownTimeout = this._appConfig?.shutdown_timeout || 5000;
-            setTimeout(() => process.exit(0), shutdownTimeout);
-        };
-        process.once('SIGTERM', () => gracefulShutdown('SIGTERM'));
-        process.once('SIGINT', () => gracefulShutdown('SIGINT'));
-
-        // ── Hot Reload (SIGHUP) ──
-        process.on('SIGHUP', () => {
-            try {
-                this._bridge.reloadConfig();
-                this._bridge.reloadFusionConfig();
-                console.log(`[fuzionx] SIGHUP — config hot-reload complete (PID=${process.pid})`);
-            } catch (e) {
-                console.error(`[fuzionx] SIGHUP reload failed (PID=${process.pid}):`, e.message);
-            }
-        });
-
-        // ── Idle Cleanup은 Rust uv_timer에서 자동 실행 (YAML websocket.check_interval/timeout) ──
-
-        // ── Error Recovery ──
-        process.on('uncaughtException', (err) => {
-            console.error('[fuzionx] uncaughtException:', err.message, err.stack);
-            // 불안정 상태 방지: 짧은 유예 후 프로세스 종료
-            setTimeout(() => process.exit(1), 1000);
-        });
-        process.on('unhandledRejection', (reason) => {
-            console.error('[fuzionx] unhandledRejection:', reason);
-        });
-
-        if (callback) setImmediate(() => callback());
-        return this;
-    }
-
-    /**
-     * 미들웨어 체인 사전 계산.
-     * 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);
-            }
-        }
-
-        this._globalChain = globalMw;
-        this._chainCache = new Map();
-
-        // 에러 핸들러도 사전 계산
-        this._errorChain = this._errorHandlers.map(m => m.handler);
-
-        // 각 라우트별 체인 캐시
-        for (const route of this._router._routes) {
-            const chain = [...globalMw];
-            for (const m of pathMw) {
-                if (route.path === m.path ||
-                    route.path.startsWith(m.path.endsWith('/') ? m.path : 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 {
-            result = runMiddlewareChain(chain, req, res);
-        } catch (err) {
-            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 {
-            console.error('[fuzionx] Handler error:', err.message || err);
-            if (!res._sent) {
-                res.status(500).json({ error: err.message || 'Internal Server Error' });
-            }
-        }
-    }
-
-    /** 비동기 응답 전송 — 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 FuzionXApp(options);
-}
+import { createRequire } from 'module';
+import path from 'path';
+import cluster from 'cluster';
+import os from 'os';
+import { Router } from './router.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);
+
+/**
+ * fuzionx-bridge native module 로드.
+ * 순서: @fuzionx/bridge (npm) → fuzionx-bridge (로컬 dev) → .node 파일 직접
+ */
+function loadBridge() {
+    // 1. npm 설치된 @fuzionx/bridge
+    try { return require('@fuzionx/bridge'); } catch (_) {}
+
+    // 2. 로컬 개발 환경 (file: 또는 workspace 의존성)
+    try { return require('fuzionx-bridge'); } catch (_) {}
+
+    throw new Error(
+        'fuzionx-bridge native module을 찾을 수 없습니다. ' +
+        'npm install @fuzionx/bridge 또는 package.json에 workspace 의존성을 추가하세요.'
+    );
+}
+
+export class FuzionXApp {
+    /**
+     * @param {object} options
+     * @param {string} options.config - YAML 설정 파일 경로
+     * @param {number} [options.port=3000] - 서버 포트
+     */
+    constructor(options = {}) {
+        this._bridge = loadBridge();
+        this._router = new Router(this._bridge);
+        this._middlewares = [];
+        this._errorHandlers = [];
+        this._options = options;
+        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 후 초기화
+    }
+
+    /** YAML boot — 설정 파일 로드 */
+    _boot() {
+        if (this._booted) return;
+        const configPath = this._options.config;
+        if (!configPath) {
+            throw new Error('config 옵션이 필요합니다 (YAML 파일 경로)');
+        }
+        this._bridge.bootSystem({ configPath: path.resolve(configPath) });
+        this._booted = true;
+        this.i18n = createI18n(this._bridge);
+
+        // 통합 로거 초기화
+        this.logger = createLogger(this._bridge);
+
+        // console.* 가로채기 (YAML intercept_console 설정에 따름)
+        const cfg = this._bridge.getConfig();
+        if (cfg.interceptConsole !== false) {
+            this._restoreConsole = interceptConsole(this._bridge);
+        }
+
+        // 앱 로그 파일 초기화 (YAML logging.file.enabled 시)
+        if (cfg.logFilePath) {
+            try {
+                this._bridge.initAppFileLogger(cfg.logFilePath);
+            } catch (e) {
+                // 파일 로거 실패해도 서버는 계속 동작
+                this.logger.warn(`앱 파일 로거 초기화 실패: ${e.message}`);
+            }
+        }
+    }
+
+    /** WebSocket 매니저 (lazy init — listen() 전에도 사용 가능) */
+    get ws() {
+        this._boot();
+        if (!this._ws) {
+            this._ws = createWs(this._bridge);
+        }
+        return this._ws;
+    }
+
+    /** 서버 설정값 */
+    get config() {
+        this._boot();
+        return this._bridge.getConfig();
+    }
+
+    /** 앱 커스텀 설정값 */
+    get appConfig() {
+        this._boot();
+        return this._bridge.getAppConfig();
+    }
+
+    /** ASP (Alloy Stealth Protocol) 설정값 */
+    get aspConfig() {
+        this._boot();
+        return JSON.parse(this._bridge.getAspConfig());
+    }
+
+    /**
+     * Tera SSR 파일 렌더링 ({% extends %}, {% block %}, {% include %} 완전 지원)
+     * @param {string} templateDir - 테마 디렉토리 (views/{theme}/)
+     * @param {string} templateName - 템플릿 이름 (pages/home.html)
+     * @param {object} [context={}] - 템플릿 변수
+     * @param {string} [locale='ko'] - 로케일
+     * @returns {string} 렌더링된 HTML
+     */
+    renderFile(templateDir, templateName, context = {}, locale = 'ko') {
+        this._boot();
+        return this._bridge.ssrRenderFile(templateDir, templateName, JSON.stringify(context), locale);
+    }
+
+    /**
+     * 경량 템플릿 파일 렌더링 (bridge에서 파일 읽기 + {{key}} 치환)
+     * @param {string} filePath - 템플릿 파일 경로
+     * @param {object} [context={}] - 치환 변수
+     * @returns {string} 렌더링된 HTML
+     */
+    render(filePath, context = {}) {
+        this._boot();
+        return this._bridge.renderTemplateFile(filePath, JSON.stringify(context));
+    }
+
+    // ── HTTP Method 라우트 등록 ──
+
+    get(routePath, ...handlers) { this._router.add('GET', routePath, handlers); return this; }
+    post(routePath, ...handlers) { this._router.add('POST', routePath, handlers); return this; }
+    put(routePath, ...handlers) { this._router.add('PUT', routePath, handlers); return this; }
+    delete(routePath, ...handlers) { this._router.add('DELETE', routePath, handlers); return this; }
+    patch(routePath, ...handlers) { this._router.add('PATCH', routePath, handlers); return this; }
+
+    /**
+     * 미들웨어 등록
+     * @param {string|Function} pathOrHandler
+     * @param {...Function} handlers
+     */
+    use(pathOrHandler, ...handlers) {
+        if (typeof pathOrHandler === 'function') {
+            const all = [pathOrHandler, ...handlers];
+            for (const h of all) {
+                const target = h.length === 4 ? this._errorHandlers : this._middlewares;
+                target.push({ path: null, handler: h });
+            }
+        } else {
+            for (const h of handlers) {
+                const target = h.length === 4 ? this._errorHandlers : this._middlewares;
+                target.push({ path: pathOrHandler, handler: h });
+            }
+        }
+        return this;
+    }
+
+    /**
+     * Fusion 서버 시작
+     * @param {number} [port]
+     * @param {Function} [callback]
+     */
+    listen(port, callback) {
+        if (typeof port === 'function') { callback = port; port = this._port; }
+        port = port || this._port;
+
+        this._boot();
+
+        // ── 워커 수 결정 (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');
+                }
+                const shutdownTimeout = this._appConfig?.shutdown_timeout || 5000;
+                setTimeout(() => process.exit(0), shutdownTimeout);
+            };
+            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) setImmediate(() => callback());
+            return this;
+        }
+
+        // ── Worker (또는 단일 프로세스): Fusion 서버 시작 ──
+        if (cluster.isWorker) {
+            // 워커 프로세스는 독립적으로 boot 필요
+            this._boot();
+        }
+
+        this._router.build();
+        this._buildMiddlewareCache();
+        this._bridge.startFusionServer(port, (rawReq) => this._handleRequest(rawReq));
+
+        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(`[fuzionx] ${signal} received — graceful shutdown (PID=${process.pid})`);
+            this._bridge.stopFusionServer();
+            const shutdownTimeout = this._appConfig?.shutdown_timeout || 5000;
+            setTimeout(() => process.exit(0), shutdownTimeout);
+        };
+        process.once('SIGTERM', () => gracefulShutdown('SIGTERM'));
+        process.once('SIGINT', () => gracefulShutdown('SIGINT'));
+
+        // ── Hot Reload (SIGHUP) ──
+        process.on('SIGHUP', () => {
+            try {
+                this._bridge.reloadConfig();
+                this._bridge.reloadFusionConfig();
+                console.log(`[fuzionx] SIGHUP — config hot-reload complete (PID=${process.pid})`);
+            } catch (e) {
+                console.error(`[fuzionx] SIGHUP reload failed (PID=${process.pid}):`, e.message);
+            }
+        });
+
+        // ── Idle Cleanup은 Rust uv_timer에서 자동 실행 (YAML websocket.check_interval/timeout) ──
+
+        // ── Error Recovery ──
+        process.on('uncaughtException', (err) => {
+            console.error('[fuzionx] uncaughtException:', err.message, err.stack);
+            // 불안정 상태 방지: 짧은 유예 후 프로세스 종료
+            setTimeout(() => process.exit(1), 1000);
+        });
+        process.on('unhandledRejection', (reason) => {
+            console.error('[fuzionx] unhandledRejection:', reason);
+        });
+
+        if (callback) setImmediate(() => callback());
+        return this;
+    }
+
+    /**
+     * 미들웨어 체인 사전 계산.
+     * 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);
+            }
+        }
+
+        this._globalChain = globalMw;
+        this._chainCache = new Map();
+
+        // 에러 핸들러도 사전 계산
+        this._errorChain = this._errorHandlers.map(m => m.handler);
+
+        // 각 라우트별 체인 캐시
+        for (const route of this._router._routes) {
+            const chain = [...globalMw];
+            for (const m of pathMw) {
+                if (route.path === m.path ||
+                    route.path.startsWith(m.path.endsWith('/') ? m.path : 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 {
+            result = runMiddlewareChain(chain, req, res);
+        } catch (err) {
+            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 {
+            console.error('[fuzionx] Handler error:', err.message || err);
+            if (!res._sent) {
+                res.status(500).json({ error: err.message || 'Internal Server Error' });
+            }
+        }
+    }
+
+    /** 비동기 응답 전송 — 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 FuzionXApp(options);
+}