@fuzionx/core 0.1.0

package/bin/ruxy-reload.sh

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

package/index.js

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

package/lib/app.js

@@ -0,0 +1,251 @@
+import { createRequire } from 'module';
+import path from 'path';
+import { Router } from './router.js';
+import { runMiddlewareChain } 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 { 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: 의존성)
+    try { return require('fuzionx-bridge'); } catch (_) {}
+
+    // 3. .node 파일 직접 로드
+    const dir = path.dirname(new URL(import.meta.url).pathname);
+    const variants = [
+        path.resolve(dir, '../../fuzionx-bridge.linux-x64-gnu.node'),
+        path.resolve(dir, '../../../crates/fuzionx-bridge/fuzionx-bridge.linux-x64-gnu.node'),
+    ];
+    for (const p of variants) {
+        try { return require(p); } catch (_) {}
+    }
+    throw new Error('fuzionx-bridge native module을 찾을 수 없습니다. npm install @fuzionx/core를 실행해 주세요.');
+}
+
+export class RuxyApp {
+    /**
+     * @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;
+
+        // 헬퍼 모듈
+        this.crypto = createCrypto(this._bridge);
+        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());
+    }
+
+    /**
+     * 템플릿 파일 렌더링 (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();
+        this._router.build();
+
+        this._bridge.startFusionServer(port, (rawReq) => this._handleRequest(rawReq));
+
+        // ── Graceful Shutdown (SIGTERM/SIGINT) ──
+        let shutdownCalled = false;
+        const gracefulShutdown = (signal) => {
+            if (shutdownCalled) return;
+            shutdownCalled = true;
+            console.log(`[ruxy] ${signal} received — graceful shutdown`);
+            this._bridge.stopFusionServer();
+            setTimeout(() => process.exit(0), 2000);
+        };
+        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('[ruxy] SIGHUP — config hot-reload complete');
+            } catch (e) {
+                console.error('[ruxy] SIGHUP reload failed:', e.message);
+            }
+        });
+
+        // ── Idle Cleanup은 Rust uv_timer에서 자동 실행 (YAML websocket.check_interval/timeout) ──
+
+        // ── Error Recovery ──
+        process.on('uncaughtException', (err) => {
+            console.error('[ruxy] uncaughtException:', err.message);
+        });
+        process.on('unhandledRejection', (reason) => {
+            console.error('[ruxy] unhandledRejection:', reason);
+        });
+
+        if (callback) setTimeout(() => callback(), 100);
+        return this;
+    }
+
+    /** 요청 처리 — 미들웨어 체인 → 라우트 핸들러 */
+    _handleRequest(rawReq) {
+        const req = createReq(rawReq, this);
+        const res = createRes();
+
+        const route = this._router.getHandler(rawReq.handlerId);
+
+        // 경로 매치 미들웨어 필터
+        const applicable = this._middlewares.filter(m =>
+            m.path === null || req.url.startsWith(m.path)
+        );
+
+        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 });
+            });
+        }
+
+        try {
+            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 (_) {
+                    res.status(500).json({ error: 'Internal Server Error' });
+                }
+            } else {
+                res.status(500).json({ error: err.message || 'Internal Server Error' });
+            }
+        }
+
+        return res._toFusionResponse();
+    }
+}
+
+export function createApp(options) {
+    return new RuxyApp(options);
+}

package/lib/context.js

@@ -0,0 +1,150 @@
+/**
+ * Context — Fusion raw req 객체를 Express 스타일 req/res로 변환.
+ */
+
+/**
+ * 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) {
+                try {
+                    _jsonCache = req.body ? JSON.parse(req.body) : null;
+                } catch (_) {
+                    _jsonCache = 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) => {
+        if (!app.i18n) return key;
+        // Accept-Language 또는 기본 로케일
+        const locale = req.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;
+}
+
+/**
+ * Response 래퍼 생성
+ */
+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;
+        },
+
+        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;
+        },
+
+        /** Fusion 응답 포맷으로 변환 */
+        _toFusionResponse() {
+            return {
+                status: res._statusCode,
+                body: res._body,
+                headers: res._headers,
+            };
+        },
+    };
+
+    return res;
+}

package/lib/crypto.js

@@ -0,0 +1,42 @@
+/**
+ * Crypto — fuzionx-bridge ASP crypto N-API를 래핑하는 헬퍼.
+ * app.crypto로 접근.
+ */
+
+export function createCrypto(bridge) {
+    return {
+        /** UUID v4 생성 */
+        uuid: () => bridge.cryptoUuid(),
+
+        /** MD5 해시 */
+        md5: (input) => bridge.cryptoMd5(input),
+
+        /** SHA-256 해시 */
+        sha256: (input) => bridge.cryptoSha256(input),
+
+        /** AES-256-GCM 암호화 */
+        encrypt: (key, plaintext) => bridge.cryptoEncryptAes(key, plaintext),
+
+        /** 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/i18n.js

@@ -0,0 +1,37 @@
+/**
+ * I18n — fuzionx-bridge i18n N-API를 래핑하는 헬퍼.
+ * app.i18n으로 접근, req.t()는 context.js에서 구현.
+ */
+
+export function createI18n(bridge) {
+    return {
+        /** 번역 조회 */
+        translate: (locale, key) => bridge.i18NTranslate(locale, key),
+
+        /** 로케일 목록 */
+        get locales() {
+            return bridge.i18NGetLocales();
+        },
+
+        /** 현재 로케일 변경 */
+        setLocale: (locale) => bridge.i18NSetLocale(locale),
+
+        /** 누락 키 업데이트 (auto_complete) */
+        updateMissing: (key, value) => bridge.i18NUpdateMissingKey(key, value),
+
+        /** auto_complete 활성화 여부 */
+        get autoComplete() {
+            return bridge.i18NIsAutoComplete();
+        },
+
+        /**
+         * SSR 템플릿 렌더링
+         * @param {string} template - Tera 템플릿 문자열
+         * @param {object} context - 템플릿 변수
+         * @param {string} [locale='en'] - 로케일
+         */
+        render: (template, context = {}, locale = 'en') => {
+            return bridge.ssrRenderString(template, context, locale);
+        },
+    };
+}

package/lib/logger.js

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Ruxy Bridge 통합 로거.
+ *
+ * Rust tracing과 Node.js console을 일원화한다.
+ * - createLogger(bridge): app.logger 객체 생성
+ * - interceptConsole(bridge): console.* 가로채기
+ *
+ * @module logger
+ */
+
+import { format } from 'node:util';
+
+/**
+ * JS 호출 스택에서 실제 호출 위치(파일:라인)를 추출한다.
+ * error/warn 레벨에서만 사용 (new Error().stack 비용 고려).
+ *
+ * @param {number} depth - 스택 프레임 깊이 (기본 3: Error → getCallSite → logWarn → 실제 호출)
+ * @returns {string} 파일:라인 문자열 (예: "server.js:42") 또는 빈 문자열
+ */
+function getCallSite(depth = 3) {
+    const stack = new Error().stack;
+    if (!stack) return '';
+
+    const lines = stack.split('\n');
+    // depth번째 라인이 실제 호출자
+    const line = lines[depth] || '';
+
+    // "    at Object.<anonymous> (/app/server.js:42:5)" 패턴
+    const matchParen = line.match(/\((.+):(\d+):\d+\)/);
+    if (matchParen) return `${matchParen[1]}:${matchParen[2]}`;
+
+    // "    at /app/server.js:42:5" 패턴 (익명 호출)
+    const matchDirect = line.match(/at (.+):(\d+):\d+/);
+    if (matchDirect) return `${matchDirect[1]}:${matchDirect[2]}`;
+
+    return '';
+}
+
+/**
+ * Rust N-API bridge를 통한 로거 객체를 생성한다.
+ *
+ * @param {object} bridge - fuzionx-bridge N-API 모듈
+ * @returns {{ info: Function, warn: Function, error: Function, debug: Function }}
+ *
+ * @example
+ * const logger = createLogger(bridge);
+ * logger.info('서버 시작');
+ * logger.error('DB 연결 실패');  // → [server.js:42] DB 연결 실패
+ */
+export function createLogger(bridge) {
+    return {
+        /**
+         * INFO 레벨 로그.
+         * @param {...any} args - 로그 메시지 (util.format 지원)
+         */
+        info(...args) {
+            bridge.logInfo('app', format(...args));
+        },
+
+        /**
+         * WARN 레벨 로그 (호출 위치 자동 추출).
+         * @param {...any} args - 로그 메시지
+         */
+        warn(...args) {
+            const location = getCallSite(2); // Error → warn → 호출자
+            bridge.logWarn('app', format(...args), location || undefined);
+        },
+
+        /**
+         * ERROR 레벨 로그 (호출 위치 자동 추출).
+         * @param {...any} args - 로그 메시지
+         */
+        error(...args) {
+            const location = getCallSite(2); // Error → error → 호출자
+            bridge.logError('app', format(...args), location || undefined);
+        },
+
+        /**
+         * DEBUG 레벨 로그.
+         * @param {...any} args - 로그 메시지
+         */
+        debug(...args) {
+            bridge.logDebug('app', format(...args));
+        },
+    };
+}
+
+/**
+ * console.log/warn/error/debug를 가로채서 Rust tracing으로 전달한다.
+ *
+ * @param {object} bridge - fuzionx-bridge N-API 모듈
+ * @returns {Function} 원래 console을 복원하는 함수
+ *
+ * @example
+ * const restore = interceptConsole(bridge);
+ * console.log('hello');  // → tracing::info [console] hello
+ * restore();             // 원래 console 복원
+ */
+export function interceptConsole(bridge) {
+    // 원본 보존
+    const orig = {
+        log: console.log,
+        info: console.info,
+        warn: console.warn,
+        error: console.error,
+        debug: console.debug,
+    };
+
+    console.log = (...args) => {
+        bridge.logInfo('console', format(...args));
+    };
+
+    console.info = (...args) => {
+        bridge.logInfo('console', format(...args));
+    };
+
+    console.warn = (...args) => {
+        const location = getCallSite(2);
+        bridge.logWarn('console', format(...args), location || undefined);
+    };
+
+    console.error = (...args) => {
+        const location = getCallSite(2);
+        bridge.logError('console', format(...args), location || undefined);
+    };
+
+    console.debug = (...args) => {
+        bridge.logDebug('console', format(...args));
+    };
+
+    /**
+     * 원래 console 함수를 복원한다.
+     */
+    return function restoreConsole() {
+        console.log = orig.log;
+        console.info = orig.info;
+        console.warn = orig.warn;
+        console.error = orig.error;
+        console.debug = orig.debug;
+    };
+}

package/lib/middleware.js

@@ -0,0 +1,26 @@
+/**
+ * Middleware — Express 스타일 동기 미들웨어 체인 엔진.
+ *
+ * Fusion 콜백은 동기 응답을 기대하므로 async를 지원하지 않음.
+ * next()를 호출하면 다음 미들웨어로 진행.
+ */
+
+/**
+ * 미들웨어 체인 실행
+ * @param {Function[]} handlers - (req, res, next) 핸들러 배열
+ * @param {object} req
+ * @param {object} res
+ */
+export function runMiddlewareChain(handlers, req, res) {
+    let index = 0;
+
+    function next(err) {
+        if (err) throw err;
+        if (res._sent || index >= handlers.length) return;
+
+        const handler = handlers[index++];
+        handler(req, res, next);
+    }
+
+    next();
+}

package/lib/router.js

@@ -0,0 +1,55 @@
+/**
+ * Router — fuzionx-bridge의 registerRoute/buildRoutes를 래핑하는 라우트 매니저.
+ * Express 스타일 path를 Rust 라우터 형식({param})으로 변환.
+ */
+export class Router {
+    constructor(bridge) {
+        this._bridge = bridge;
+        this._routes = [];       // { method, path, handlers }
+        this._handlerMap = {};   // handlerId → handlers[]
+        this._nextId = 1;
+        this._built = false;
+    }
+
+    /**
+     * 라우트 추가
+     * @param {string} method - HTTP 메서드
+     * @param {string} routePath - Express 스타일 경로 (예: /api/users/:id)
+     * @param {Function[]} handlers - 핸들러 배열
+     */
+    add(method, routePath, handlers) {
+        if (this._built) {
+            throw new Error('라우트는 listen() 호출 전에 등록해야 합니다');
+        }
+
+        // Express :param → Rust {param} 변환
+        const rustPath = routePath.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}');
+        const handlerId = this._nextId++;
+
+        this._routes.push({ method, path: rustPath, handlerId, handlers });
+        this._handlerMap[handlerId] = handlers;
+
+        return handlerId;
+    }
+
+    /** 모든 등록된 라우트를 fuzionx-bridge에 등록하고 빌드 */
+    build() {
+        if (this._built) return;
+
+        for (const route of this._routes) {
+            this._bridge.registerRoute(route.method, route.path, route.handlerId);
+        }
+        this._bridge.buildRoutes();
+        this._built = true;
+    }
+
+    /**
+     * handlerId로 핸들러 배열 조회
+     * @param {number} handlerId
+     * @returns {Function[]|null}
+     */
+    getHandler(handlerId) {
+        if (handlerId < 0) return null;
+        return this._handlerMap[handlerId] || null;
+    }
+}

package/lib/session.js

@@ -0,0 +1,18 @@
+/**
+ * Session — fuzionx-bridge 세션 N-API를 래핑하는 헬퍼.
+ * context.js에서 req.session으로 사용됨.
+ */
+
+export function createSession(bridge) {
+    return {
+        /** 세션 데이터 조회 (전체) */
+        get: (sessionId) => bridge.sessionGet(sessionId),
+        /** 세션 데이터 저장 (data: HashMap, ttl: optional) */
+        set: (sessionId, data, ttlSecs) => bridge.sessionSet(sessionId, data, ttlSecs),
+        destroy: (sessionId) => bridge.sessionDestroy(sessionId),
+        renew: (sessionId, ttlSecs) => bridge.sessionRenew(sessionId, ttlSecs),
+        exists: (sessionId) => bridge.sessionExists(sessionId),
+        load: (sessionId) => bridge.sessionLoad(sessionId),
+        cleanup: () => bridge.sessionCleanup(),
+    };
+}

package/lib/ws.js

@@ -0,0 +1,190 @@
+/**
+ * WebSocket — 네임스페이스 기반 WS 매니저.
+ *
+ * 사용법:
+ *   app.ws('/chat').on('connect', (socket) => { ... });
+ *   app.ws('/chat').on('message', (socket, data) => { ... });
+ *   app.ws('/chat').on('disconnect', (socket) => { ... });
+ *
+ *   // 기본 네임스페이스 ("/")
+ *   app.ws.on('message', (socket, data) => { ... });
+ */
+
+/**
+ * 개별 WebSocket 연결을 나타내는 래퍼.
+ */
+class RuxySocket {
+    constructor(sessionId, bridge) {
+        this._bridge = bridge;
+        this.sessionId = sessionId;
+    }
+
+    /** 이 소켓에 메시지 전송 */
+    send(data) {
+        const msg = typeof data === 'string' ? data : JSON.stringify(data);
+        this._bridge.wsSendTo(this.sessionId, msg);
+    }
+
+    /** 전체 연결에 브로드캐스트 */
+    broadcast(data) {
+        const msg = typeof data === 'string' ? data : JSON.stringify(data);
+        this._bridge.wsBroadcast(msg);
+    }
+
+    /** 자신을 제외하고 브로드캐스트 */
+    broadcastExcluding(data) {
+        const msg = typeof data === 'string' ? data : JSON.stringify(data);
+        this._bridge.wsBroadcastExcluding(msg, this.sessionId);
+    }
+
+    /** 여러 세션에 전송 */
+    sendToMany(sessionIds, data) {
+        const msg = typeof data === 'string' ? data : JSON.stringify(data);
+        this._bridge.wsSendToMany(sessionIds, msg);
+    }
+
+    /** 메타데이터 매칭 세션에 전송 */
+    sendToMatch(key, value, data) {
+        const msg = typeof data === 'string' ? data : JSON.stringify(data);
+        this._bridge.wsSendToMetadataMatch(key, value, msg);
+    }
+
+    /** 메타데이터 설정 */
+    setMetadata(key, value) {
+        this._bridge.wsSetMetadata(this.sessionId, key, value);
+    }
+
+    /** 메타데이터 조회 */
+    getMetadata(key) {
+        return this._bridge.wsGetMetadata(this.sessionId, key);
+    }
+
+    /** 연결 끊기 */
+    disconnect() {
+        this._bridge.wsDisconnect(this.sessionId);
+    }
+
+    /** JSON 직렬화 */
+    toJSON() {
+        return { sessionId: this.sessionId };
+    }
+}
+
+/**
+ * 네임스페이스별 핸들러 레지스트리.
+ */
+class WsNamespace {
+    constructor(path) {
+        this.path = path;
+        this._handlers = { connect: null, message: null, disconnect: null };
+    }
+
+    /**
+     * 이벤트 핸들러 등록.
+     * @param {'connect'|'message'|'disconnect'} event
+     * @param {Function} handler
+     * @returns {WsNamespace} 체이닝 지원
+     */
+    on(event, handler) {
+        if (!['connect', 'message', 'disconnect'].includes(event)) {
+            throw new Error(`Unknown WS event: ${event}`);
+        }
+        this._handlers[event] = handler;
+        return this;
+    }
+}
+
+export function createWs(bridge) {
+    /** @type {Map<string, WsNamespace>} */
+    const namespaces = new Map();
+    let _initialized = false;
+
+    /**
+     * 내부: TSFN 콜백을 bridge에 한 번만 등록.
+     * 모든 네임스페이스의 이벤트가 여기로 들어옴 → path로 dispatch.
+     */
+    function ensureInitialized() {
+        if (_initialized) return;
+        _initialized = true;
+
+        // connect 이벤트 디스패쳐
+        bridge.wsOnConnect((namespace, sessionId) => {
+            const ns = namespaces.get(namespace);
+            if (ns && ns._handlers.connect) {
+                ns._handlers.connect(new RuxySocket(sessionId, bridge));
+            }
+        });
+
+        // message 이벤트 디스패쳐
+        bridge.wsOnMessage((namespace, sessionId, message) => {
+            const ns = namespaces.get(namespace);
+            if (ns && ns._handlers.message) {
+                ns._handlers.message(new RuxySocket(sessionId, bridge), message);
+            }
+        });
+
+        // disconnect 이벤트 디스패쳐
+        bridge.wsOnDisconnect((namespace, sessionId) => {
+            const ns = namespaces.get(namespace);
+            if (ns && ns._handlers.disconnect) {
+                ns._handlers.disconnect(new RuxySocket(sessionId, bridge));
+            }
+        });
+    }
+
+    /**
+     * 네임스페이스를 가져오거나 생성.
+     * @param {string} path
+     * @returns {WsNamespace}
+     */
+    function getOrCreateNs(path) {
+        ensureInitialized();
+        if (!namespaces.has(path)) {
+            namespaces.set(path, new WsNamespace(path));
+        }
+        return namespaces.get(path);
+    }
+
+    // Proxy: ws('/chat') → 네임스페이스, ws.on() → 기본 "/" 네임스페이스
+    const wsProxy = new Proxy(function wsFunc(path) {
+        return getOrCreateNs(path);
+    }, {
+        get(target, prop) {
+            // ws.on('event', handler) → 기본 "/" 네임스페이스
+            if (prop === 'on') {
+                const defaultNs = getOrCreateNs('/');
+                return defaultNs.on.bind(defaultNs);
+            }
+
+            // ws.broadcast, ws.sendTo 등 글로벌 유틸
+            switch (prop) {
+                case 'broadcast':
+                    return (data) => bridge.wsBroadcast(typeof data === 'string' ? data : JSON.stringify(data));
+                case 'broadcastExcluding':
+                    return (data, excludeSessionId) => bridge.wsBroadcastExcluding(typeof data === 'string' ? data : JSON.stringify(data), excludeSessionId);
+                case 'broadcastLocal':
+                    return (data) => bridge.wsBroadcastLocal(typeof data === 'string' ? data : JSON.stringify(data));
+                case 'broadcastExcludingLocal':
+                    return (data, excludeSessionId) => bridge.wsBroadcastExcludingLocal(typeof data === 'string' ? data : JSON.stringify(data), excludeSessionId);
+                case 'sendTo':
+                    return (sessionId, data) => bridge.wsSendTo(sessionId, typeof data === 'string' ? data : JSON.stringify(data));
+                case 'sendToMany':
+                    return (sessionIds, data) => bridge.wsSendToMany(sessionIds, typeof data === 'string' ? data : JSON.stringify(data));
+                case 'onlineCount':
+                    return bridge.wsGetOnlineCount();
+                case 'sessionIds':
+                    return bridge.wsGetSessionIds();
+                case 'removeInactive':
+                    return (seconds) => bridge.wsRemoveInactive(seconds);
+                case 'disconnect':
+                    return (sessionId) => bridge.wsDisconnect(sessionId);
+                case 'namespaces':
+                    return namespaces;
+                default:
+                    return Reflect.get(target, prop);
+            }
+        },
+    });
+
+    return wsProxy;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@fuzionx/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Express-style Node.js framework powered by FuzionX native bridge — 167K RPS single process",
+  "main": "index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": "./index.js"
+  },
+  "keywords": ["framework", "http", "server", "rust", "native", "high-performance", "fuzionx", "napi"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/saytohenry/fuzionx"
+  },
+  "dependencies": {
+    "@fuzionx/bridge": "^0.1.0"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "bin/",
+    "types/"
+  ]
+}

package/types/index.d.ts

@@ -0,0 +1,102 @@
+// TypeScript 타입 정의 — ruxy framework
+
+export interface RuxyOptions {
+    config: string;
+    port?: number;
+}
+
+export interface RuxyRequest {
+    method: string;
+    url: string;
+    path: string;
+    query: Record<string, string>;
+    params: Record<string, string>;
+    headers: Record<string, string>;
+    ip: string;
+    body: string;
+    json: any;
+    handlerId: number;
+    requestId: number;
+    sessionId: string | 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 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 interface SessionHelper {
+    get(key?: string): any;
+    set(key: string, value: string): void;
+    destroy(): void;
+    renew(): string | null;
+}
+
+export interface I18nHelper {
+    translate(locale: string, key: string): string | null;
+    readonly locales: string[];
+    setLocale(locale: string): void;
+    updateMissing(key: string, value: string): void;
+    readonly autoComplete: boolean;
+    render(template: string, context?: Record<string, any>, locale?: string): string;
+}
+
+export interface WsHelper {
+    broadcast(data: any): void;
+    sendTo(sessionId: string, data: any): void;
+    sendToMany(sessionIds: string[], data: any): void;
+    broadcastExcluding(excludeId: string, data: any): void;
+    sendToMatch(key: string, value: string, data: any): void;
+    readonly onlineCount: number;
+    readonly sessionIds: string[];
+    disconnect(sessionId: string): void;
+    setMetadata(sessionId: string, key: string, value: string): void;
+    getMetadata(sessionId: string, key: string): string | null;
+    removeInactive(seconds: number): number;
+}
+
+export interface CryptoHelper {
+    uuid(): string;
+    md5(input: string): string;
+    sha256(input: string): string;
+    encrypt(plaintext: string, key: string): string;
+    decrypt(ciphertext: string, key: string): string;
+    encryptCustom(plaintext: string, key: string): string;
+    decryptCustom(ciphertext: string, key: string): string;
+    getUaSlice(userAgent: string): string;
+    deriveTransportKey(sessionKey: string, uaSlice: string): string;
+}
+
+export declare class RuxyApp {
+    constructor(options?: RuxyOptions);
+
+    readonly config: Record<string, any>;
+    readonly appConfig: Record<string, any>;
+    readonly crypto: CryptoHelper;
+    readonly ws: WsHelper | null;
+    readonly i18n: I18nHelper | null;
+
+    get(path: string, ...handlers: RequestHandler[]): this;
+    post(path: string, ...handlers: RequestHandler[]): this;
+    put(path: string, ...handlers: RequestHandler[]): this;
+    delete(path: string, ...handlers: RequestHandler[]): this;
+    patch(path: string, ...handlers: RequestHandler[]): this;
+
+    use(handler: RequestHandler | ErrorHandler): this;
+    use(path: string, ...handlers: (RequestHandler | ErrorHandler)[]): this;
+
+    listen(port?: number, callback?: () => void): this;
+    listen(callback: () => void): this;
+}
+
+export declare function createApp(options?: RuxyOptions): RuxyApp;