@fuzionx/framework 0.1.2

package/lib/helpers/Logger.js

@@ -0,0 +1,105 @@
+/**
+ * Logger — Bridge tracing 통합 로거
+ *
+ * Bridge(Rust) logInfo/logWarn/logError/logDebug N-API에 위임.
+ * Bridge 없으면 JS console 폴백.
+ *
+ * @see docs/framework/13-logging.md
+ * @see packages/fuzionx/lib/logger.js (Core 래퍼 참조)
+ */
+import { format } from 'node:util';
+
+export default class Logger {
+    /**
+     * @param {object} [opts]
+     * @param {string} [opts.level='info'] - 최소 출력 레벨
+     * @param {object} [opts.bridge] - Bridge N-API 인스턴스
+     * @param {boolean} [opts.json=false] - JSON 포맷 (Bridge 없을 때)
+     * @param {string} [opts.prefix='app'] - Bridge target 이름
+     */
+    constructor(opts = {}) {
+        this.level = opts.level || 'info';
+        this._bridge = opts.bridge || null;
+        this._json = opts.json || false;
+        this._prefix = opts.prefix || 'app';
+        this._levels = { error: 0, warn: 1, info: 2, debug: 3 };
+        this._minLevel = this._levels[this.level] ?? 2;
+    }
+
+    /**
+     * @param {string} message
+     * @param {object} [context]
+     */
+    error(message, context) { this._log('error', message, context); }
+    warn(message, context) { this._log('warn', message, context); }
+    info(message, context) { this._log('info', message, context); }
+    debug(message, context) { this._log('debug', message, context); }
+
+    /**
+     * 자식 로거 생성 (prefix 상속)
+     * @param {string} prefix
+     * @returns {Logger}
+     */
+    child(prefix) {
+        return new Logger({
+            level: this.level,
+            bridge: this._bridge,
+            json: this._json,
+            prefix: this._prefix ? `${this._prefix}:${prefix}` : prefix,
+        });
+    }
+
+    /** @private */
+    _log(level, message, context) {
+        if (this._levels[level] > this._minLevel) return;
+
+        const msg = context
+            ? `${message} ${JSON.stringify(context)}`
+            : message;
+
+        // ── Bridge N-API 위임 ──
+        // Core logger.js 참조: bridge.logInfo(target, msg), bridge.logWarn(target, msg, location?)
+        if (this._bridge) {
+            try {
+                if (level === 'info' && typeof this._bridge.logInfo === 'function') {
+                    this._bridge.logInfo(this._prefix, msg);
+                    return;
+                }
+                if (level === 'warn' && typeof this._bridge.logWarn === 'function') {
+                    this._bridge.logWarn(this._prefix, msg);
+                    return;
+                }
+                if (level === 'error' && typeof this._bridge.logError === 'function') {
+                    this._bridge.logError(this._prefix, msg);
+                    return;
+                }
+                if (level === 'debug' && typeof this._bridge.logDebug === 'function') {
+                    this._bridge.logDebug(this._prefix, msg);
+                    return;
+                }
+            } catch {} // Bridge 호출 실패 시 JS 폴백
+        }
+
+        // ── JS 폴백 ──
+        const timestamp = new Date().toISOString();
+
+        if (this._json) {
+            const entry = {
+                timestamp,
+                level,
+                target: this._prefix,
+                message,
+                ...(context || {}),
+            };
+            console[level === 'debug' ? 'log' : level](JSON.stringify(entry));
+        } else {
+            const levelTag = level.toUpperCase().padEnd(5);
+            const fullMsg = `${timestamp}  ${levelTag}  [${this._prefix}] ${message}`;
+            if (context && Object.keys(context).length > 0) {
+                console[level === 'debug' ? 'log' : level](fullMsg, context);
+            } else {
+                console[level === 'debug' ? 'log' : level](fullMsg);
+            }
+        }
+    }
+}

package/lib/helpers/MediaHelper.js

@@ -0,0 +1,38 @@
+/**
+ * MediaHelper — Bridge media N-API 래퍼
+ *
+ * @see docs/framework/19-utilities.md — "3. Media (app.media)"
+ * @see packages/fuzionx/lib/media.js (Core 래퍼)
+ */
+export default class MediaHelper {
+    constructor(bridge) { this._bridge = bridge; }
+
+    resize(input, output, width, height, format = 'webp', quality = 80) {
+        if (this._bridge?.mediaResize) return this._bridge.mediaResize(input, output, width, height, format, quality);
+        throw new Error('Media operations require Bridge (Rust). Install @fuzionx/bridge.');
+    }
+
+    resizeMultiple(input, outputDir, baseName, specs) {
+        if (this._bridge?.mediaResizeMultiple) return this._bridge.mediaResizeMultiple(input, outputDir, baseName, JSON.stringify(specs));
+        throw new Error('Media operations require Bridge (Rust).');
+    }
+
+    imageInfo(filePath) {
+        if (this._bridge?.mediaGetImageInfo) return this._bridge.mediaGetImageInfo(filePath);
+        throw new Error('Image info requires Bridge (Rust).');
+    }
+
+    toWebp(input, output, quality = 80) {
+        return this.resize(input, output, 0, 0, 'webp', quality);
+    }
+
+    videoThumbnail(input, output, atSeconds = 1, width = 640, format = 'jpeg') {
+        if (this._bridge?.mediaVideoThumbnail) return this._bridge.mediaVideoThumbnail(input, output, atSeconds, width, format);
+        throw new Error('Video operations require ffmpeg + Bridge.');
+    }
+
+    videoInfo(filePath) {
+        if (this._bridge?.mediaVideoInfo) return this._bridge.mediaVideoInfo(filePath);
+        throw new Error('Video info requires ffprobe + Bridge.');
+    }
+}

package/lib/http/Controller.js

@@ -0,0 +1,34 @@
+/**
+ * Controller — HTTP 요청 핸들러 기본 클래스
+ *
+ * 싱글톤: 부트 시 1회 생성. 핸들러 메서드는 ctx만으로 동작.
+ *
+ * @see docs/framework/01-routing-controllers.md
+ * @see docs/framework/class-design.mm.md (Controller)
+ */
+import Base from '../core/Base.js';
+
+export default class Controller extends Base {
+    /** @type {string[]} 이 컨트롤러 전체에 적용할 미들웨어 */
+    static middleware = [];
+
+    /**
+     * 프레임워크 내부 — 컨트롤러 스캔 시 프로토타입 메서드를 static 레퍼런스로 자동 등록
+     * @param {typeof Controller} ControllerClass
+     */
+    static register(ControllerClass) {
+        const proto = ControllerClass.prototype;
+        const baseNames = new Set(Object.getOwnPropertyNames(Base.prototype));
+        for (const method of Object.getOwnPropertyNames(proto)) {
+            if (method === 'constructor') continue;
+            // Base 메서드/getter 전체 스킵 (service, emit, dispatch, ws, crypto, i18n)
+            if (baseNames.has(method)) continue;
+
+            ControllerClass[method] = {
+                __handler__: true,
+                controller: ControllerClass,
+                method,
+            };
+        }
+    }
+}

package/lib/http/ErrorHandler.js

@@ -0,0 +1,135 @@
+/**
+ * ErrorHandler — 기본 에러 핸들러 (JSON/HTML 분기 + 테마 에러 페이지)
+ *
+ * @see docs/framework/08-error-handling.md
+ * @see docs/framework/03-views-templates.md (에러 페이지)
+ */
+import AppError, { ValidationError } from '../core/AppError.js';
+
+export default class ErrorHandler {
+    /**
+     * @param {object} opts
+     * @param {boolean} [opts.isDev=false] - dev 모드에서 스택 노출
+     * @param {Function} [opts.logger] - 에러 로깅 함수
+     * @param {import('./View.js').default} [opts.view] - 뷰 렌더러 (테마 에러 페이지용)
+     */
+    constructor(opts = {}) {
+        this.isDev = opts.isDev ?? false;
+        this.logger = opts.logger || console.error;
+        this._view = opts.view || null;
+    }
+
+    /**
+     * 에러 처리 — ctx에 응답 세팅
+     * @param {Error} err
+     * @param {import('./Context.js').default} ctx
+     */
+    handle(err, ctx) {
+        const status = err.status || 500;
+
+        // 500 에러는 로깅
+        if (status >= 500) {
+            this.logger(err);
+        }
+
+        // JSON 응답 요청이면 JSON으로
+        const wantsJson = ctx.get('accept')?.includes('application/json')
+            || ctx.is('json')
+            || ctx.path?.startsWith('/api');
+
+        if (wantsJson) {
+            return this._jsonResponse(err, ctx, status);
+        }
+
+        return this._htmlResponse(err, ctx, status);
+    }
+
+    /** @private */
+    _jsonResponse(err, ctx, status) {
+        const body = {
+            error: {
+                message: err.message,
+                status,
+            },
+        };
+
+        // ValidationError → 필드 에러 포함
+        if (err instanceof ValidationError) {
+            body.error.fields = err.fields;
+        }
+
+        // dev 모드에서 스택 노출
+        if (this.isDev && status >= 500) {
+            body.error.stack = err.stack;
+        }
+
+        // 추가 데이터
+        if (err.data && !(err instanceof ValidationError)) {
+            body.error.data = err.data;
+        }
+
+        ctx.status(status).json(body);
+    }
+
+    /**
+     * HTML 에러 응답 — 테마 에러 페이지 지원
+     *
+     * 검색 순서 (03-views-templates.md):
+     * 1. views/{theme}/errors/{code}.html
+     * 2. views/{theme}/errors/default.html
+     * 3. 프레임워크 내장 에러 페이지
+     *
+     * @private
+     */
+    _htmlResponse(err, ctx, status) {
+        const errorData = {
+            error: {
+                code: status,
+                message: err.message,
+                stack: this.isDev ? err.stack : null,
+            },
+            request: { url: ctx.url, method: ctx.method },
+            config: { debug: this.isDev },
+        };
+
+        // 테마 에러 페이지 시도 (View 렌더러가 있을 때)
+        const view = this._view || ctx.app?._view;
+        if (view) {
+            const theme = ctx.theme || ctx.app?.config?.get('themes.default', 'default') || 'default';
+            // 1. views/{theme}/errors/{code}.html
+            try {
+                const html = view.render(`errors/${status}`, errorData);
+                if (html && !html.startsWith('<!-- template:')) {
+                    ctx.status(status).html(html);
+                    return;
+                }
+            } catch {}
+            // 2. views/{theme}/errors/default.html
+            try {
+                const html = view.render('errors/default', errorData);
+                if (html && !html.startsWith('<!-- template:')) {
+                    ctx.status(status).html(html);
+                    return;
+                }
+            } catch {}
+        }
+
+        // 3. 프레임워크 내장 에러 페이지 (XSS 방지)
+        const esc = (s) => String(s)
+            .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+        const title = status >= 500 ? 'Server Error' : esc(err.message);
+
+        ctx.status(status).html(
+            `<!DOCTYPE html><html><head><meta charset="utf-8"><title>${status}</title>` +
+            `<style>body{font-family:system-ui,-apple-system,sans-serif;max-width:600px;margin:80px auto;` +
+            `padding:0 20px;color:#333}h1{color:#e74c3c;}pre{background:#f5f5f5;padding:16px;border-radius:8px;` +
+            `overflow-x:auto;font-size:13px;}</style></head>` +
+            `<body><h1>${status} — ${title}</h1>` +
+            `<p>요청: ${esc(ctx.method)} ${esc(ctx.url)}</p>` +
+            `${this.isDev && err.stack ? `<pre>${esc(err.stack)}</pre>` : ''}` +
+            `</body></html>`
+        );
+    }
+}

package/lib/http/Middleware.js

@@ -0,0 +1,43 @@
+/**
+ * Middleware — 기본 미들웨어 클래스
+ *
+ * @see docs/framework/12-middleware.md
+ * @see docs/framework/class-design.mm.md (Middleware)
+ */
+import Base from '../core/Base.js';
+
+export default class Middleware extends Base {
+    /** @type {string} 미들웨어 등록 이름 (라우트에서 참조) */
+    static name = '';
+
+    /**
+     * 미들웨어 핸들러 (서브클래스에서 오버라이드)
+     * @param {import('./Context.js').default} ctx
+     * @param {Function} next
+     * @param {...*} params - 파라미터화 미들웨어 인자 ('name:param1:param2')
+     */
+    async handle(ctx, next, ...params) {
+        await next();
+    }
+}
+
+/**
+ * 미들웨어 체인 실행기
+ *
+ * @param {Array<Function>} middlewares - [(ctx, next) => ...] 배열
+ * @param {import('./Context.js').default} ctx
+ * @returns {Promise<void>}
+ */
+export async function runMiddlewareChain(middlewares, ctx) {
+    let idx = 0;
+
+    async function next(err) {
+        if (err) throw err;
+        if (idx >= middlewares.length) return;
+
+        const fn = middlewares[idx++];
+        await fn(ctx, next);
+    }
+
+    await next();
+}

package/lib/http/Router.js

@@ -0,0 +1,109 @@
+/**
+ * Router / RouteGroup — 라우트 등록 DSL
+ *
+ * @see docs/framework/01-routing-controllers.md
+ * @see docs/framework/class-design.mm.md (Router/RouteGroup)
+ */
+
+export class RouteGroup {
+    /**
+     * @param {string} prefix - 그룹 접두사 ('', '/api')
+     * @param {object} [groupOpts] - 그룹 옵션 { middleware }
+     */
+    constructor(prefix = '', groupOpts = {}) {
+        this._prefix = prefix;
+        this._groupMiddleware = groupOpts.middleware || [];
+        this._routes = [];
+    }
+
+    /**
+     * @param {string} method
+     * @param {string} path
+     * @param {Function|object} handler
+     * @param {object} [opts]
+     */
+    _addRoute(method, path, handler, opts = {}) {
+        const fullPath = this._prefix + path;
+        this._routes.push({
+            method,
+            path: fullPath,
+            handler,
+            middleware: [...this._groupMiddleware, ...(opts.middleware || [])],
+            validate: opts.validate || null,
+            upload: opts.upload || null,
+            docs: opts.docs || null,
+        });
+    }
+
+    get(path, handler, opts) { this._addRoute('GET', path, handler, opts); }
+    post(path, handler, opts) { this._addRoute('POST', path, handler, opts); }
+    put(path, handler, opts) { this._addRoute('PUT', path, handler, opts); }
+    patch(path, handler, opts) { this._addRoute('PATCH', path, handler, opts); }
+    delete(path, handler, opts) { this._addRoute('DELETE', path, handler, opts); }
+
+    /**
+     * 그룹 — 중첩 라우트
+     * 인자 순서: (prefix, opts, callback) 또는 (prefix, callback, opts)
+     * @param {string} prefix
+     * @param {object|Function} optsOrCallback
+     * @param {Function|object} [callbackOrOpts]
+     */
+    group(prefix, optsOrCallback, callbackOrOpts) {
+        let opts, callback;
+        if (typeof optsOrCallback === 'function') {
+            // group('/api', (r) => {}, opts?)
+            callback = optsOrCallback;
+            opts = callbackOrOpts || {};
+        } else {
+            // group('/api', { middleware: [...] }, (r) => {})
+            opts = optsOrCallback || {};
+            callback = callbackOrOpts;
+        }
+
+        const subGroup = new RouteGroup(this._prefix + prefix, {
+            middleware: [...this._groupMiddleware, ...(opts.middleware || [])],
+        });
+        callback(subGroup);
+        this._routes.push(...subGroup._routes);
+    }
+
+    /**
+     * RESTful resource 자동 등록
+     * @param {string} name - 리소스 이름 (복수형, e.g. 'users')
+     * @param {object} controller - Controller 클래스 (메서드 레퍼런스)
+     * @param {object} [opts]
+     */
+    resource(name, controller, opts = {}) {
+        const basePath = `/${name}`;
+        const middleware = opts.middleware || [];
+        const base = { middleware };
+
+        if (controller.index) this.get(basePath, controller.index, base);
+        if (controller.store) this.post(basePath, controller.store, base);
+        if (controller.show) this.get(`${basePath}/:id`, controller.show, base);
+        if (controller.update) this.put(`${basePath}/:id`, controller.update, base);
+        if (controller.destroy) this.delete(`${basePath}/:id`, controller.destroy, base);
+    }
+}
+
+export default class Router extends RouteGroup {
+    constructor() {
+        super('');
+    }
+
+    /**
+     * 모든 등록된 라우트 반환
+     * @returns {Array<{method, path, handler, middleware, validate, upload, docs}>}
+     */
+    getRoutes() {
+        return this._routes;
+    }
+
+    /**
+     * 라우트 파일 로드 (routes/ callback 등록)
+     * @param {Function} routeCallback - (r: RouteGroup) => void
+     */
+    load(routeCallback) {
+        routeCallback(this);
+    }
+}

package/lib/http/Validation.js

@@ -0,0 +1,124 @@
+/**
+ * Validation — 간단문법 → Joi 변환 파서
+ *
+ * 'required|min:2|max:50' → Joi.string().required().min(2).max(50)
+ *
+ * @see docs/framework/09-validation.md
+ */
+import { ValidationError } from '../core/AppError.js';
+
+/**
+ * 간단 규칙 문자열을 Joi 스키마로 변환
+ * @param {object} rules - { name: 'required|min:2', email: 'required|email' }
+ * @param {object} Joi - Joi 모듈 참조
+ * @returns {import('joi').ObjectSchema}
+ */
+export function parseRules(rules, Joi) {
+    const shape = {};
+
+    for (const [field, rule] of Object.entries(rules)) {
+        const parts = typeof rule === 'string' ? rule.split('|') : [];
+        let schema = Joi.any();
+
+        for (const part of parts) {
+            const [name, ...args] = part.split(':');
+
+            switch (name) {
+                case 'string':
+                    schema = Joi.string(); break;
+                case 'number':
+                    schema = Joi.number(); break;
+                case 'boolean':
+                    schema = Joi.boolean(); break;
+                case 'required':
+                    schema = schema.required(); break;
+                case 'optional':
+                    schema = schema.optional(); break;
+                case 'min':
+                    schema = schema.min(Number(args[0])); break;
+                case 'max':
+                    schema = schema.max(Number(args[0])); break;
+                case 'email':
+                    schema = Joi.string().email(); break;
+                case 'url':
+                    schema = Joi.string().uri(); break;
+                case 'in':
+                    schema = schema.valid(...args[0].split(',')); break;
+                case 'integer':
+                    schema = schema.integer ? schema.integer() : Joi.number().integer(); break;
+                case 'positive':
+                    schema = schema.positive ? schema.positive() : Joi.number().positive(); break;
+                case 'date':
+                    schema = Joi.date(); break;
+                case 'alpha':
+                    schema = Joi.string().alphanum(); break;
+                default:
+                    // 알 수 없는 규칙은 무시
+                    break;
+            }
+        }
+
+        shape[field] = schema;
+    }
+
+    return Joi.object(shape);
+}
+
+/**
+ * Validation 클래스 — 라우트 검증 실행기
+ */
+export default class Validation {
+    /**
+     * @param {object} Joi - Joi 인스턴스
+     */
+    constructor(Joi) {
+        this._Joi = Joi;
+    }
+
+    /**
+     * 라우트 validate 옵션 실행
+     * @param {object} ctx
+     * @param {object} validateOpts - { body: schema, query: schema, params: schema }
+     * @returns {object} - { body, query, params } 정제된 값
+     */
+    run(ctx, validateOpts) {
+        const result = {};
+
+        if (validateOpts.body) {
+            result.body = this._validate(ctx.body, validateOpts.body);
+        }
+        if (validateOpts.query) {
+            result.query = this._validate(ctx.query, validateOpts.query);
+        }
+        if (validateOpts.params) {
+            result.params = this._validate(ctx.params, validateOpts.params);
+        }
+
+        return result;
+    }
+
+    /**
+     * @private
+     */
+    _validate(data, schema) {
+        // 간단문법 객체 → Joi 변환
+        if (schema && typeof schema === 'object' && !schema.validate) {
+            schema = parseRules(schema, this._Joi);
+        }
+
+        const { error, value } = schema.validate(data, {
+            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;
+    }
+}