@fuzionx/framework 0.1.2

package/lib/core/Context.js

@@ -0,0 +1,429 @@
+/**
+ * Context — 요청/응답 통합 API
+ *
+ * Bridge rawReq → Context 변환.
+ * 미들웨어/핸들러에 전달되는 단일 객체.
+ *
+ * Session은 Bridge sessionSet/Destroy/Renew N-API에 위임.
+ * Cookie는 rawReq.headers.cookie 파싱 + Set-Cookie 헤더 생성.
+ *
+ * @see docs/framework/06-context.md
+ * @see packages/fuzionx/lib/context.js (Core SessionProto 참조)
+ */
+import AppError, { ValidationError } from '../core/AppError.js';
+
+export default class Context {
+    /**
+     * @param {object} rawReq - Bridge에서 전달된 raw 요청 객체
+     * @param {import('./Application.js').default} app
+     */
+    constructor(rawReq, app) {
+        // ── 요청 프로퍼티 ──
+        this.method = rawReq.method || 'GET';
+        this.url = rawReq.url || '/';
+        this.path = rawReq.path || this.url.split('?')[0];
+        this.query = rawReq.query || {};
+        this.params = rawReq.params || {};
+        this.headers = rawReq.headers || {};
+        this.body = rawReq.body || null;
+        this.ip = rawReq.remoteIp || '';
+        this.files = rawReq.files || null;
+        this.formFields = rawReq.formFields || null;
+        this.handlerId = rawReq.handlerId;
+
+        // 파생 속성 (06-context.md)
+        this.protocol = this.headers['x-forwarded-proto'] || 'http';
+        this.host = this.headers['host'] || '';
+
+        // ── 프레임워크 주입 ──
+        this.app = app;
+        this.user = null;
+        this._sessionId = rawReq.sessionId || null;
+        this._rawSession = rawReq.session || {};
+        // ── Cookie (parseCookies 먼저 — _detectLocale에서 참조) ──
+        this.cookies = this._parseCookies();
+
+        this.session = this._createSession(rawReq, app);
+        this.locale = this._detectLocale(rawReq);
+
+        // i18n — ctx.t() + ctx.t.all() (18-i18n.md)
+        this.t = this._createT();
+
+        // ── lazy 캐시 ──
+        this._json = undefined;
+        this._setCookies = []; // Set-Cookie 헤더 배열
+
+        // ── 응답 상태 ──
+        this._statusCode = 200;
+        this._headers = {};
+        this._body = '';
+        this._sent = false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Request 유틸
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** lazy JSON 파싱 */
+    get getJson() {
+        if (this._json !== undefined) return this._json;
+        if (typeof this.body === 'object' && this.body !== null) {
+            this._json = this.body;
+        } else if (typeof this.body === 'string' && this.body) {
+            try { this._json = JSON.parse(this.body); }
+            catch { this._json = null; }
+        } else {
+            this._json = null;
+        }
+        return this._json;
+    }
+
+    /** 헤더 값 가져오기 (case-insensitive) */
+    get(name) {
+        return this.headers[name.toLowerCase()];
+    }
+
+    /** Content-Type 확인 */
+    is(type) {
+        const ct = this.get('content-type') || '';
+        const map = {
+            json: 'application/json',
+            html: 'text/html',
+            form: 'application/x-www-form-urlencoded',
+            multipart: 'multipart/form-data',
+        };
+        return ct.includes(map[type] || type);
+    }
+
+    /**
+     * Accept 협상 (06-context.md)
+     * @param {...string} types - 'json', 'html', 'text'
+     * @returns {string|false} 매칭된 타입 또는 false
+     */
+    accepts(...types) {
+        const accept = this.get('accept') || '*/*';
+        const mimeMap = {
+            json: 'application/json',
+            html: 'text/html',
+            text: 'text/plain',
+            xml: 'application/xml',
+        };
+        for (const type of types) {
+            const mime = mimeMap[type] || type;
+            if (accept.includes(mime) || accept.includes('*/*')) return type;
+        }
+        return false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Cookie (06-context.md)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 쿠키 읽기/쓰기
+     * @overload cookie(name) → 읽기
+     * @overload cookie(name, value, opts?) → 쓰기
+     */
+    cookie(name, value, opts) {
+        if (arguments.length === 1) {
+            return this.cookies[name] ?? null;
+        }
+        // 쓰기 → Set-Cookie 헤더
+        const o = opts || {};
+        let str = `${name}=${encodeURIComponent(String(value))}`;
+        if (o.maxAge != null) str += `; Max-Age=${o.maxAge}`;
+        if (o.path) str += `; Path=${o.path}`;
+        else str += '; Path=/';
+        if (o.domain) str += `; Domain=${o.domain}`;
+        if (o.httpOnly !== false) str += '; HttpOnly';
+        if (o.secure) str += '; Secure';
+        if (o.sameSite) str += `; SameSite=${o.sameSite}`;
+        this._setCookies.push(str);
+        return this;
+    }
+
+    /** 쿠키 삭제 */
+    clearCookie(name, opts) {
+        return this.cookie(name, '', { ...opts, maxAge: 0 });
+    }
+
+    /** @private */
+    _parseCookies() {
+        const header = this.headers?.cookie || this.headers?.Cookie || '';
+        if (!header) return {};
+        const result = {};
+        for (const pair of header.split(';')) {
+            const [k, ...v] = pair.trim().split('=');
+            if (k) result[k.trim()] = decodeURIComponent(v.join('='));
+        }
+        return result;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Response 메서드
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    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._headers['Content-Type'] = 'text/html; charset=utf-8';
+        this._sent = true;
+        return this;
+    }
+
+    html(content) {
+        return this.send(content);
+    }
+
+    text(content) {
+        this._body = String(content);
+        this._headers['Content-Type'] = 'text/plain; 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;
+    }
+
+    back() {
+        const referer = this.get('referer') || '/';
+        return this.redirect(referer);
+    }
+
+    end() {
+        this._body = '';
+        this._sent = true;
+        return this;
+    }
+
+    header(key, value) {
+        this._headers[key] = value;
+        return this;
+    }
+
+    /** setHeader alias (06-context.md) */
+    setHeader(key, value) {
+        return this.header(key, value);
+    }
+
+    error(statusCode, message) {
+        throw new AppError(message, statusCode);
+    }
+
+    /**
+     * 파일 다운로드 (06-context.md)
+     * @param {string} filePath
+     * @param {string} [filename]
+     */
+    download(filePath, filename) {
+        const name = filename || filePath.split('/').pop();
+        this._headers['Content-Disposition'] = `attachment; filename="${name}"`;
+        this._body = filePath; // Application에서 파일 전송 처리
+        this._sent = true;
+        return this;
+    }
+
+    /**
+     * 스트리밍 응답 (06-context.md)
+     * 대용량 응답 시 ReadableStream/Buffer를 직접 전송.
+     * @param {ReadableStream|Buffer} readableStream
+     * @param {string} [contentType='application/octet-stream']
+     */
+    stream(readableStream, contentType = 'application/octet-stream') {
+        this._headers['Content-Type'] = contentType;
+        this._streamBody = readableStream;
+        this._sent = true;
+        return this;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Validate
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    validate(schema) {
+        if (schema && typeof schema.validate === 'function') {
+            const { error, value } = schema.validate(this.body, { abortEarly: false, stripUnknown: true });
+            if (error) {
+                const fields = {};
+                for (const detail of error.details) {
+                    fields[detail.path.join('.')] = detail.message;
+                }
+                throw new ValidationError('Validation failed', fields);
+            }
+            return value;
+        }
+        return this.body;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  i18n (Bridge 연동)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** @private Setup i18n t() function with .all() support */
+    _createT() {
+        const self = this;
+        const t = (key, vars) => {
+            const locale = vars?.locale || self.locale;
+            if (self.app?.i18n) {
+                return self.app.i18n.translate(locale, key, vars);
+            }
+            return vars?.default || key;
+        };
+        // ctx.t.all() — 현재 locale 전체 번역 데이터 (18-i18n.md)
+        t.all = () => {
+            if (self.app?.i18n?.getAll) {
+                return self.app.i18n.getAll(self.locale);
+            }
+            return {};
+        };
+        return t;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  View 렌더링
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    render(view, data) {
+        // 글로벌 변수 주입 (03-views-templates.md)
+        const globals = {
+            session: this._rawSession,
+            auth: { user: this.user },
+            config: this.app?.config?._raw || {},
+            request: { url: this.url, method: this.method, path: this.path, ip: this.ip },
+            csrf_token: this._rawSession?._csrfToken || '',
+            flash: this.session?.getFlash() || {},
+            theme: this.theme || this.app?.config?.get('themes.default', 'default') || 'default',
+            locale: this.locale,
+            ...data,
+        };
+
+        // Bridge SSR (i18n.render → bridge.ssrRenderString)
+        if (this.app?._bridge && typeof this.app._bridge.ssrRenderString === 'function') {
+            try {
+                const html = this.app._bridge.ssrRenderString(view, globals, this.locale);
+                return this.html(html);
+            } catch {} // Bridge SSR 실패 시 View 폴백
+        }
+
+        if (this.app?._view) {
+            const html = this.app._view.render(view, globals);
+            return this.html(html);
+        }
+        return this.send(`View '${view}' not found`);
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Session + Flash (Bridge sessionSet/Destroy/Renew)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** @private */
+    _createSession(rawReq, app) {
+        const data = rawReq.session || {};
+        const flash = { ...(data._flash || {}) };
+        delete data._flash;
+        const sessionId = rawReq.sessionId || null;
+        const bridge = app?._bridge || null;
+
+        return {
+            /** 세션 값 조회 */
+            get: (key) => key ? (data[key] ?? null) : { ...data },
+
+            /** 세션 값 설정 — Bridge sessionSet 연동 */
+            set: (key, value) => {
+                data[key] = value;
+                // Core SessionProto 참조: bridge.sessionSet(id, { ...data })
+                if (sessionId && bridge?.sessionSet) {
+                    try { bridge.sessionSet(sessionId, { ...data }); } catch {}
+                }
+            },
+
+            /** 세션 삭제 — Bridge sessionDestroy 연동 */
+            destroy: () => {
+                Object.keys(data).forEach(k => delete data[k]);
+                if (sessionId && bridge?.sessionDestroy) {
+                    try { bridge.sessionDestroy(sessionId); } catch {}
+                }
+            },
+
+            /** 세션 갱신 — Bridge sessionRenew 연동 */
+            renew: () => {
+                if (sessionId && bridge?.sessionRenew) {
+                    try { return bridge.sessionRenew(sessionId); } catch {}
+                }
+                return null;
+            },
+
+            /** 플래시 메시지 설정 */
+            flash: (key, value) => {
+                if (!data._flash) data._flash = {};
+                data._flash[key] = value;
+                // 플래시도 세션에 영속화
+                if (sessionId && bridge?.sessionSet) {
+                    try { bridge.sessionSet(sessionId, { ...data }); } catch {}
+                }
+            },
+
+            /** 플래시 메시지 조회 (1회 후 삭제) */
+            getFlash: (key) => {
+                if (key) {
+                    const val = flash[key];
+                    delete flash[key];
+                    return val ?? null;
+                }
+                const all = { ...flash };
+                Object.keys(flash).forEach(k => delete flash[k]);
+                return all;
+            },
+        };
+    }
+
+    /** locale 감지 (5단계 우선순위) — 06-context.md */
+    _detectLocale(rawReq) {
+        if (rawReq.locale) return rawReq.locale;
+        if (this.query?.lang) return this.query.lang;
+        // 쿠키 fuzionx.lang
+        const cookieLang = this.cookies?.['fuzionx.lang'];
+        if (cookieLang) return cookieLang;
+        if (this._rawSession?.locale) return this._rawSession.locale;
+        const al = this.headers?.['accept-language'];
+        if (al) {
+            const first = al.split(',')[0]?.split('-')[0];
+            if (first) return first;
+        }
+        return this.app?.config?.get('app.i18n.default_locale', 'ko') || 'ko';
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  응답 변환
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** Bridge 응답 포맷 { status, body, headers } */
+    toResponse() {
+        // Set-Cookie 헤더 병합
+        if (this._setCookies.length > 0) {
+            this._headers['Set-Cookie'] = this._setCookies;  // 배열 → Bridge 다중 헤더
+        }
+        return {
+            status: this._statusCode,
+            body: this._streamBody || this._body,
+            headers: this._headers,
+            stream: !!this._streamBody,
+        };
+    }
+}

package/lib/database/ConnectionManager.js

@@ -0,0 +1,192 @@
+/**
+ * ConnectionManager — DB 연결 관리 싱글톤
+ *
+ * 드라이버별 연결 생성/캐싱/종료.
+ * SQLite (기본), MariaDB, PostgreSQL, MongoDB 지원.
+ *
+ * @see docs/framework/02-database-orm.md
+ * @see docs/framework/17-config.md
+ */
+import { createRequire } from 'node:module';
+
+const _require = createRequire(import.meta.url);
+
+/**
+ * optional dependency 안전 로드
+ * @private
+ */
+function tryRequire(name) {
+    try { return _require(name); } catch { return null; }
+}
+
+export default class ConnectionManager {
+    constructor() {
+        /** @type {Map<string, object>} name → connection */
+        this._connections = new Map();
+        /** @type {Map<string, object>} name → config */
+        this._configs = new Map();
+        /** @type {string} default connection name */
+        this._default = 'main';
+    }
+
+    /**
+     * 설정으로 초기화
+     * @param {object} dbConfig - fuzionx.yaml database 섹션
+     */
+    configure(dbConfig) {
+        this._default = dbConfig.default || 'main';
+        const connections = dbConfig.connections || {};
+        for (const [name, cfg] of Object.entries(connections)) {
+            this._configs.set(name, cfg);
+        }
+    }
+
+    /**
+     * 연결 가져오기 (lazy 생성)
+     * @param {string} [name] - connection name (default: _default)
+     * @returns {object} driver connection instance
+     */
+    get(name) {
+        const connName = name || this._default;
+        if (this._connections.has(connName)) {
+            return this._connections.get(connName);
+        }
+
+        const config = this._configs.get(connName);
+        if (!config) {
+            throw new Error(`DB connection '${connName}' not configured. Check fuzionx.yaml database.connections.`);
+        }
+
+        const conn = this._createConnection(connName, config);
+        this._connections.set(connName, conn);
+        return conn;
+    }
+
+    /**
+     * 드라이버 타입 조회
+     * @param {string} [name]
+     * @returns {string} 'sqlite' | 'mariadb' | 'postgres' | 'mongodb'
+     */
+    getDriver(name) {
+        const connName = name || this._default;
+        const config = this._configs.get(connName);
+        return config?.driver || 'sqlite';
+    }
+
+    /**
+     * 드라이버별 연결 생성
+     * @private
+     */
+    _createConnection(name, config) {
+        const driver = (config.driver || 'sqlite').toLowerCase();
+
+        switch (driver) {
+            case 'sqlite': {
+                const Database = tryRequire('better-sqlite3');
+                if (!Database) return this._createStub('sqlite', config);
+
+                const dbPath = config.database || config.path || ':memory:';
+                const db = new Database(dbPath, {
+                    verbose: config.verbose ? console.log : undefined,
+                });
+                db.pragma('journal_mode = WAL');
+                db.pragma('foreign_keys = ON');
+                return { type: 'sqlite', db, config };
+            }
+
+            case 'mariadb':
+            case 'mysql': {
+                const knex = tryRequire('knex');
+                if (!knex) return this._createStub('knex', config, 'mariadb');
+
+                const knexInit = typeof knex === 'function' ? knex : knex.default;
+                const db = knexInit({
+                    client: 'mysql2',
+                    connection: {
+                        host: config.host || '127.0.0.1',
+                        port: config.port || 3306,
+                        user: config.user || 'root',
+                        password: config.password || '',
+                        database: config.database || '',
+                        charset: config.charset || 'utf8mb4',
+                    },
+                    pool: config.pool || { min: 2, max: 10 },
+                });
+                return { type: 'knex', driver: 'mariadb', db, config };
+            }
+
+            case 'postgres':
+            case 'postgresql': {
+                const knex = tryRequire('knex');
+                if (!knex) return this._createStub('knex', config, 'postgres');
+
+                const knexInit = typeof knex === 'function' ? knex : knex.default;
+                const db = knexInit({
+                    client: 'pg',
+                    connection: {
+                        host: config.host || '127.0.0.1',
+                        port: config.port || 5432,
+                        user: config.user || 'postgres',
+                        password: config.password || '',
+                        database: config.database || '',
+                    },
+                    pool: config.pool || { min: 2, max: 10 },
+                });
+                return { type: 'knex', driver: 'postgres', db, config };
+            }
+
+            case 'mongodb':
+            case 'mongo': {
+                const mongoose = tryRequire('mongoose');
+                if (!mongoose) return this._createStub('mongo', config);
+                return { type: 'mongo', mongoose, config };
+            }
+
+            default:
+                throw new Error(`Unsupported DB driver: '${driver}'. Supported: sqlite, mariadb, postgres, mongodb.`);
+        }
+    }
+
+    /**
+     * 드라이버 미설치 stub
+     * @private
+     */
+    _createStub(type, config, driver) {
+        return { type, driver: driver || type, db: null, config, _stub: true };
+    }
+
+    /**
+     * 모든 연결 종료 (graceful shutdown)
+     */
+    async closeAll() {
+        for (const [name, conn] of this._connections) {
+            try {
+                if (conn.type === 'sqlite' && conn.db) {
+                    conn.db.close();
+                } else if (conn.type === 'knex' && conn.db) {
+                    await conn.db.destroy();
+                } else if (conn.type === 'mongo' && conn.mongoose) {
+                    await conn.mongoose.disconnect();
+                }
+            } catch (err) {
+                console.error(`[ConnectionManager] Error closing '${name}':`, err.message);
+            }
+        }
+        this._connections.clear();
+    }
+
+    /**
+     * 특정 연결 종료
+     * @param {string} name
+     */
+    async close(name) {
+        const conn = this._connections.get(name);
+        if (!conn) return;
+        try {
+            if (conn.type === 'sqlite' && conn.db) conn.db.close();
+            else if (conn.type === 'knex' && conn.db) await conn.db.destroy();
+            else if (conn.type === 'mongo' && conn.mongoose) await conn.mongoose.disconnect();
+        } catch {}
+        this._connections.delete(name);
+    }
+}

package/lib/database/MariaModel.js

@@ -0,0 +1,29 @@
+/**
+ * MariaModel — MariaDB/MySQL 모델 서브클래스
+ *
+ * Knex + mysql2 기반.
+ * SqlModel의 공통 SQL 로직을 상속하며,
+ * MariaDB 고유 기능(FULLTEXT, JSON 등)은 raw()로 접근.
+ *
+ * @see docs/framework/02-database-orm.md
+ *
+ * @example
+ * import { MariaModel } from '@fuzionx/framework';
+ *
+ * export default class User extends MariaModel {
+ *     static table = 'users';
+ *     static connection = 'main';
+ *     static timestamps = true;
+ *     static columns = {
+ *         id:    { type: 'increments' },
+ *         name:  { type: 'string', length: 100 },
+ *         email: { type: 'string', length: 150, unique: true },
+ *     };
+ * }
+ */
+import SqlModel from './SqlModel.js';
+
+export default class MariaModel extends SqlModel {
+    static driver = 'mariadb';
+    static connection = 'main';
+}