@fuzionx/framework 0.1.2

package/lib/services/Service.js

@@ -0,0 +1,261 @@
+/**
+ * Service — 비즈니스 로직 기본 클래스
+ *
+ * 컨트롤러는 얇게, 비즈니스 로직은 서비스에.
+ * 트랜잭션, 캐싱, 병렬 실행, 재시도, 뮤텍스 지원.
+ *
+ * @see docs/framework/07-service-layer.md
+ * @see docs/framework/class-design.mm.md (Service)
+ */
+import Base from '../core/Base.js';
+import { ServiceError } from '../core/AppError.js';
+
+/** @type {Map<string, { value: *, expires: number }>} 전역 캐시 스토어 */
+const _cache = new Map();
+
+/** @type {Map<string, Promise>} 전역 뮤텍스 락 */
+const _locks = new Map();
+
+export default class Service extends Base {
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  트랜잭션
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * SQL 트랜잭션 실행
+     * @param {Function} callback - (trx) => Promise<T>
+     * @returns {Promise<T>}
+     */
+    async transaction(callback) {
+        const cm = this.app?._connectionManager;
+        if (!cm) throw new Error('Database not configured for transactions');
+
+        const conn = cm.get();
+        if (conn.type === 'knex' && conn.db) {
+            return conn.db.transaction(callback);
+        }
+        throw new Error('SQL database not configured for transactions');
+    }
+
+    /**
+     * MongoDB 트랜잭션 실행
+     * @param {string} connName - MongoDB 연결명
+     * @param {Function} callback - (session) => Promise<T>
+     * @returns {Promise<T>}
+     */
+    async mongoTransaction(connName, callback) {
+        const cm = this.app?._connectionManager;
+        if (!cm) throw new Error('Database not configured');
+
+        const conn = cm.get(connName);
+        if (conn.type !== 'mongo' || !conn.mongoose) {
+            throw new Error(`MongoDB connection '${connName}' not found`);
+        }
+
+        const session = await conn.mongoose.startSession();
+        try {
+            session.startTransaction();
+            const result = await callback(session);
+            await session.commitTransaction();
+            return result;
+        } catch (err) {
+            await session.abortTransaction();
+            throw err;
+        } finally {
+            session.endSession();
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  캐시
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * TTL 기반 인메모리 캐시로 감싸기
+     *
+     * @param {string} key - 캐시 키
+     * @param {number} ttl - TTL (초)
+     * @param {Function} fn - 캐시 미스 시 실행할 함수
+     * @returns {Promise<*>}
+     *
+     * @example
+     * const stats = await this.withCache('dashboard:stats', 300, async () => {
+     *     return this.db.Order.raw('SELECT SUM(total) ...');
+     * });
+     */
+    async withCache(key, ttl, fn) {
+        const cached = _cache.get(key);
+        if (cached && cached.expires > Date.now()) {
+            return cached.value;
+        }
+
+        const value = await fn();
+        _cache.set(key, {
+            value,
+            expires: Date.now() + (ttl * 1000),
+        });
+        return value;
+    }
+
+    /**
+     * 캐시 키 무효화
+     * @param {string} key
+     */
+    invalidateCache(key) {
+        _cache.delete(key);
+    }
+
+    /**
+     * 전체 캐시 초기화
+     */
+    clearCache() {
+        _cache.clear();
+    }
+
+    /**
+     * 캐시 존재 여부
+     * @param {string} key
+     * @returns {boolean}
+     */
+    hasCache(key) {
+        const cached = _cache.get(key);
+        return cached ? cached.expires > Date.now() : false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  병렬 실행
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 여러 함수를 병렬 실행
+     *
+     * @param {Array<Function>} tasks - () => Promise 형태의 함수 배열
+     * @param {object} [opts]
+     * @param {boolean} [opts.failFast=false] - true면 하나 실패 시 전체 reject
+     * @returns {Promise<Array>} 결과 배열 (failFast=false 시 에러도 포함)
+     *
+     * @example
+     * const [users, orders, stats] = await this.runParallel([
+     *     () => this.db.User.count(),
+     *     () => this.db.Order.where('status', 'active').get(),
+     *     () => this.calculateStats(),
+     * ]);
+     */
+    async runParallel(tasks, opts = {}) {
+        const promises = tasks.map(fn => fn());
+
+        if (opts.failFast) {
+            return Promise.all(promises);
+        }
+
+        const results = await Promise.allSettled(promises);
+        return results.map(r => {
+            if (r.status === 'fulfilled') return r.value;
+            // 실패 시 에러 객체 반환 (throw하지 않음)
+            return r.reason;
+        });
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  재시도
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 재시도 + 지수 백오프
+     *
+     * @param {Function} fn - 실행할 함수
+     * @param {object} [opts]
+     * @param {number} [opts.retries=3] - 재시도 횟수
+     * @param {number} [opts.delay=1000] - 초기 지연 (ms)
+     * @param {number} [opts.backoff=2] - 백오프 배수
+     * @param {Function} [opts.shouldRetry] - (err, attempt) => boolean
+     * @returns {Promise<*>}
+     *
+     * @example
+     * const data = await this.retryable(
+     *     () => fetch('https://api.external.com/data'),
+     *     { retries: 3, delay: 1000, backoff: 2 }
+     * );
+     */
+    async retryable(fn, opts = {}) {
+        const { retries = 3, delay = 1000, backoff = 2, shouldRetry } = opts;
+        let lastError;
+        let currentDelay = delay;
+
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                return await fn();
+            } catch (err) {
+                lastError = err;
+
+                if (attempt === retries) break;
+                if (shouldRetry && !shouldRetry(err, attempt)) break;
+
+                await new Promise(r => setTimeout(r, currentDelay));
+                currentDelay *= backoff;
+            }
+        }
+
+        throw lastError;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  뮤텍스
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 동시 실행 방지 (in-process lock)
+     *
+     * 같은 key에 대해 동시에 1개만 실행.
+     * 이전 실행 완료 후 다음 실행.
+     *
+     * @param {string} key - 락 키
+     * @param {Function} fn - 실행할 함수
+     * @returns {Promise<*>}
+     *
+     * @example
+     * await this.mutex('order:process:' + orderId, async () => {
+     *     const order = await this.db.Order.findOrFail(orderId);
+     *     await order.update({ status: 'processing' });
+     * });
+     */
+    async mutex(key, fn) {
+        // 이전 락이 있으면 대기
+        while (_locks.has(key)) {
+            await _locks.get(key);
+        }
+
+        // 새 락 설정
+        let releaseLock;
+        const lockPromise = new Promise(resolve => { releaseLock = resolve; });
+        _locks.set(key, lockPromise);
+
+        try {
+            return await fn();
+        } finally {
+            _locks.delete(key);
+            releaseLock();
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  에러
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 에러 생성 헬퍼
+     * @param {string} message
+     * @param {number} [status=400]
+     * @returns {ServiceError}
+     */
+    error(message, status = 400) {
+        return new ServiceError(message, status);
+    }
+}
+
+/**
+ * 캐시 스토어 접근 (테스트용)
+ * @returns {Map}
+ */
+export { _cache, _locks };

package/lib/services/Storage.js

@@ -0,0 +1,112 @@
+/**
+ * Storage — 파일 저장 추상화 (Local / S3)
+ *
+ * put(path, tempPath) — 임시파일 → 최종 위치 이동.
+ * Local: file.move(tempPath, fullPath)
+ * S3: Node.js 스트리밍 업로드 (큐 Task 권장)
+ *
+ * @see docs/framework/15-file-upload.md
+ * @see docs/framework/class-design.mm.md (Storage)
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export default class Storage {
+    /**
+     * @param {object} opts
+     * @param {string} [opts.driver='local'] - 'local' | 's3'
+     * @param {string} [opts.basePath='./storage'] - 로컬 저장 경로
+     * @param {object} [opts.s3] - S3 설정 { bucket, region, credentials }
+     * @param {import('./FileHelper.js').default} [opts.fileHelper] - FileHelper 인스턴스
+     */
+    constructor(opts = {}) {
+        this.driver = opts.driver || 'local';
+        this.basePath = opts.basePath || './storage';
+        this._s3 = opts.s3 || null;
+        this._file = opts.fileHelper || null;
+    }
+
+    /**
+     * 임시파일 → 최종 위치 이동
+     * @param {string} filePath - 상대 경로 (e.g. 'uploads/avatar.jpg')
+     * @param {string} tempPath - 임시 파일 경로 (/tmp/fuzionx_upload_xxx)
+     * @returns {Promise<string>} - 저장된 URL 또는 경로
+     */
+    async put(filePath, tempPath) {
+        if (this.driver === 's3') {
+            return this._s3Put(filePath, tempPath);
+        }
+        const fullPath = path.join(this.basePath, filePath);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        // FileHelper로 이동 (Bridge file.move → Rust 직접)
+        if (this._file) {
+            await this._file.move(tempPath, fullPath);
+        } else {
+            // 폴백: fs.rename (cross-device 시 copy+unlink)
+            await fs.rename(tempPath, fullPath).catch(async () => {
+                await fs.copyFile(tempPath, fullPath);
+                await fs.unlink(tempPath);
+            });
+        }
+        return fullPath;
+    }
+
+    /**
+     * 파일 읽기
+     * @param {string} filePath
+     * @returns {Promise<Buffer>}
+     */
+    async get(filePath) {
+        if (this.driver === 's3') {
+            return this._s3Get(filePath);
+        }
+        return fs.readFile(path.join(this.basePath, filePath));
+    }
+
+    /**
+     * 파일 삭제
+     * @param {string} filePath
+     * @returns {Promise<void>}
+     */
+    async delete(filePath) {
+        if (this.driver === 's3') {
+            return this._s3Delete(filePath);
+        }
+        await fs.unlink(path.join(this.basePath, filePath));
+    }
+
+    /**
+     * 파일 존재 여부
+     * @param {string} filePath
+     * @returns {Promise<boolean>}
+     */
+    async exists(filePath) {
+        try {
+            if (this.driver === 's3') {
+                return this._s3Exists(filePath);
+            }
+            await fs.access(path.join(this.basePath, filePath));
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * 파일 URL (public 접근용)
+     * @param {string} filePath
+     * @returns {string}
+     */
+    url(filePath) {
+        if (this.driver === 's3' && this._s3) {
+            return `https://${this._s3.bucket}.s3.${this._s3.region}.amazonaws.com/${filePath}`;
+        }
+        return `/storage/${filePath}`;
+    }
+
+    // ── S3 스텁 (Phase 5+ 구현) ──
+    async _s3Put(filePath, tempPath) { throw new Error('S3 driver not implemented'); }
+    async _s3Get(filePath) { throw new Error('S3 driver not implemented'); }
+    async _s3Delete(filePath) { throw new Error('S3 driver not implemented'); }
+    async _s3Exists(filePath) { throw new Error('S3 driver not implemented'); }
+}

package/lib/view/OpenAPI.js

@@ -0,0 +1,231 @@
+/**
+ * OpenAPI — OpenAPI 3.0 spec 빌더 + Swagger UI
+ *
+ * 라우트 정의 + Joi 스키마에서 OpenAPI spec 자동 생성.
+ *
+ * @see docs/framework/21-openapi.md
+ */
+
+/**
+ * Joi 스키마를 JSON Schema로 변환 (간단 버전)
+ * @param {object} joiSchema
+ * @returns {object}
+ */
+function joiToJsonSchema(joiSchema) {
+    if (!joiSchema) return {};
+
+    // Joi는 describe()로 메타 추출 가능
+    if (typeof joiSchema.describe === 'function') {
+        return convertJoiDescribe(joiSchema.describe());
+    }
+
+    // 이미 plain object면 그대로
+    return joiSchema;
+}
+
+function convertJoiDescribe(desc) {
+    if (!desc) return {};
+
+    if (desc.type === 'object') {
+        const properties = {};
+        const required = [];
+
+        if (desc.keys) {
+            for (const [key, child] of Object.entries(desc.keys)) {
+                properties[key] = convertJoiDescribe(child);
+                if (child.flags?.presence === 'required') {
+                    required.push(key);
+                }
+            }
+        }
+
+        return {
+            type: 'object',
+            properties,
+            ...(required.length ? { required } : {}),
+        };
+    }
+
+    const result = { type: desc.type || 'string' };
+
+    if (desc.flags?.description) result.description = desc.flags.description;
+    if (desc.rules) {
+        for (const rule of desc.rules) {
+            if (rule.name === 'min') result.minLength = rule.args.limit;
+            if (rule.name === 'max') result.maxLength = rule.args.limit;
+        }
+    }
+    if (desc.allow) result.enum = desc.allow;
+    if (desc.flags?.default !== undefined) result.default = desc.flags.default;
+
+    return result;
+}
+
+export default class OpenAPI {
+    /**
+     * @param {object} opts
+     * @param {string} [opts.title='FuzionX API']
+     * @param {string} [opts.version='1.0.0']
+     * @param {string} [opts.description]
+     * @param {Array} [opts.servers]
+     */
+    constructor(opts = {}) {
+        this.title = opts.title || 'FuzionX API';
+        this.version = opts.version || '1.0.0';
+        this.description = opts.description || '';
+        this.servers = opts.servers || [];
+        this._spec = null;
+    }
+
+    /**
+     * 라우트 목록에서 OpenAPI spec 빌드
+     * @param {Array} routes - Router.getRoutes() 결과
+     * @returns {object} - OpenAPI 3.0 spec
+     */
+    build(routes) {
+        const paths = {};
+
+        for (const route of routes) {
+            if (!route.docs) continue;
+
+            const openApiPath = route.path.replace(/:(\w+)/g, '{$1}');
+
+            if (!paths[openApiPath]) paths[openApiPath] = {};
+
+            const method = route.method.toLowerCase();
+            const operation = {
+                summary: route.docs.summary || '',
+                tags: route.docs.tags || [],
+            };
+
+            if (route.docs.description) {
+                operation.description = route.docs.description;
+            }
+            if (route.docs.deprecated) {
+                operation.deprecated = true;
+            }
+
+            // parameters (query + params)
+            const parameters = [];
+
+            if (route.validate?.params) {
+                const schema = joiToJsonSchema(route.validate.params);
+                if (schema.properties) {
+                    for (const [name, prop] of Object.entries(schema.properties)) {
+                        parameters.push({
+                            name,
+                            in: 'path',
+                            required: true,
+                            schema: prop,
+                        });
+                    }
+                }
+            }
+
+            if (route.validate?.query) {
+                const schema = joiToJsonSchema(route.validate.query);
+                if (schema.properties) {
+                    for (const [name, prop] of Object.entries(schema.properties)) {
+                        parameters.push({
+                            name,
+                            in: 'query',
+                            required: schema.required?.includes(name) || false,
+                            schema: prop,
+                        });
+                    }
+                }
+            }
+
+            if (parameters.length) operation.parameters = parameters;
+
+            // requestBody (body)
+            if (route.validate?.body) {
+                const schema = joiToJsonSchema(route.validate.body);
+                operation.requestBody = {
+                    content: {
+                        'application/json': { schema },
+                    },
+                };
+            }
+
+            // responses
+            operation.responses = route.docs.responses || { '200': { description: 'OK' } };
+
+            // security
+            if (route.middleware?.includes('auth') || route.middleware?.includes('apiAuth')) {
+                const scheme = route.middleware.includes('apiAuth') ? 'bearer' : 'session';
+                operation.security = [{ [scheme]: [] }];
+            }
+
+            paths[openApiPath][method] = operation;
+        }
+
+        this._spec = {
+            openapi: '3.0.3',
+            info: {
+                title: this.title,
+                version: this.version,
+                ...(this.description ? { description: this.description } : {}),
+            },
+            ...(this.servers.length ? { servers: this.servers } : {}),
+            paths,
+            components: {
+                securitySchemes: {
+                    bearer: {
+                        type: 'http',
+                        scheme: 'bearer',
+                        bearerFormat: 'JWT',
+                    },
+                    session: {
+                        type: 'apiKey',
+                        in: 'cookie',
+                        name: 'sid',
+                    },
+                },
+            },
+        };
+
+        return this._spec;
+    }
+
+    /**
+     * 캐시된 spec 반환 (JSON)
+     */
+    toJSON() {
+        return this._spec;
+    }
+
+    /**
+     * YAML 포맷 (간단 변환)
+     */
+    toYAML() {
+        return jsonToSimpleYaml(this._spec);
+    }
+}
+
+function jsonToSimpleYaml(obj, indent = 0) {
+    const spaces = ' '.repeat(indent);
+    let result = '';
+
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined) continue;
+
+        if (Array.isArray(value)) {
+            result += `${spaces}${key}:\n`;
+            for (const item of value) {
+                if (typeof item === 'object') {
+                    result += `${spaces}  -\n${jsonToSimpleYaml(item, indent + 4)}`;
+                } else {
+                    result += `${spaces}  - ${item}\n`;
+                }
+            }
+        } else if (typeof value === 'object') {
+            result += `${spaces}${key}:\n${jsonToSimpleYaml(value, indent + 2)}`;
+        } else {
+            const v = typeof value === 'string' ? `'${value}'` : value;
+            result += `${spaces}${key}: ${v}\n`;
+        }
+    }
+
+    return result;
+}

package/lib/view/View.js

@@ -0,0 +1,72 @@
+/**
+ * View — 뷰 렌더링 (테마 + Tera SSR)
+ *
+ * ctx.theme에 따른 테마 경로 해석.
+ * Bridge Tera SSR 또는 JS 폴백.
+ *
+ * @see docs/framework/03-views-templates.md
+ */
+export default class View {
+    /**
+     * @param {object} opts
+     * @param {string} opts.viewsPath - 뷰 파일 루트 경로
+     * @param {string} [opts.theme='default'] - 기본 테마
+     * @param {object} [opts.bridge] - Bridge SSR 인스턴스 (Tera)
+     * @param {object} [opts.globals] - 모든 뷰에 주입되는 전역 변수
+     */
+    constructor(opts = {}) {
+        this.viewsPath = opts.viewsPath || '';
+        this.theme = opts.theme || 'default';
+        this._bridge = opts.bridge || null;
+        this._globals = opts.globals || {};
+    }
+
+    /**
+     * 전역 변수 추가
+     * @param {string} key
+     * @param {*} value
+     */
+    share(key, value) {
+        this._globals[key] = value;
+    }
+
+    /**
+     * 템플릿 렌더링
+     *
+     * 테마 경로 해석 (03-views-templates.md):
+     * 'pages/users/index' → {theme}/pages/users/index.html
+     *
+     * @param {string} template - 'users/index' 등
+     * @param {object} [data] - 템플릿 변수
+     * @param {string} [theme] - 테마 오버라이드 (ctx.theme에서 전달)
+     * @returns {string} - 렌더링된 HTML
+     */
+    render(template, data = {}, theme) {
+        const activeTheme = theme || data.theme || this.theme;
+        const mergedData = { ...this._globals, ...data, theme: activeTheme };
+
+        // Bridge Tera SSR이 있으면 위임
+        if (this._bridge) {
+            const templatePath = `${activeTheme}/${template}.html`;
+            try {
+                return this._bridge.render(templatePath, mergedData);
+            } catch {
+                // SSR 실패 시 폴백
+            }
+        }
+
+        // 폴백: 간단한 변수 치환
+        return this._simpleRender(template, mergedData);
+    }
+
+    /**
+     * @private 간단 치환 (Bridge 없을 때)
+     */
+    _simpleRender(template, data) {
+        let html = `<!-- template: ${template} -->`;
+        for (const [key, value] of Object.entries(data)) {
+            html += `\n<!-- ${key}: ${JSON.stringify(value)} -->`;
+        }
+        return html;
+    }
+}