@fuzionx/framework 0.1.2

package/lib/middleware/index.js

@@ -0,0 +1,286 @@
+/**
+ * 내장 미들웨어 — bodyParser, cors, auth, apiAuth, csrf
+ *
+ * @see docs/framework/12-middleware.md
+ * @see docs/framework/14-authentication.md
+ */
+
+/**
+ * JSON/Form body 파싱 미들웨어
+ * Bridge가 이미 파싱한 body를 보장. 추가 파싱이 필요한 경우 처리.
+ */
+export function bodyParser() {
+    return async (ctx, next) => {
+        // Bridge가 body를 이미 파싱했으므로 ctx.body는 rawReq.body에서 가져옴
+        // 추가 파싱이 필요하면 여기서 처리
+        if (typeof ctx.body === 'string' && ctx.body) {
+            const ct = ctx.get('content-type') || '';
+            if (ct.includes('application/json')) {
+                try { ctx.body = JSON.parse(ctx.body); } catch {}
+            }
+        }
+        await next();
+    };
+}
+
+/**
+ * CORS 미들웨어
+ * @param {object} [opts]
+ * @param {string|string[]} [opts.origin='*']
+ * @param {string} [opts.methods='GET,POST,PUT,PATCH,DELETE,OPTIONS']
+ * @param {string} [opts.headers='Content-Type,Authorization']
+ * @param {boolean} [opts.credentials=false]
+ * @param {number} [opts.maxAge=86400]
+ */
+export function cors(opts = {}) {
+    const origin = opts.origin || '*';
+    const methods = opts.methods || 'GET,POST,PUT,PATCH,DELETE,OPTIONS';
+    const headers = opts.headers || 'Content-Type,Authorization';
+    const credentials = opts.credentials || false;
+    const maxAge = opts.maxAge || 86400;
+
+    return async (ctx, next) => {
+        const reqOrigin = ctx.get('origin') || '*';
+        let allowOrigin;
+
+        if (credentials && origin === '*') {
+            // W3C 스펙: credentials:true일 때 origin:'*' 사용 불가 → request origin 미러링
+            allowOrigin = reqOrigin !== '*' ? reqOrigin : '';
+        } else {
+            allowOrigin = origin === '*' ? '*' : (
+                Array.isArray(origin)
+                    ? (origin.includes(reqOrigin) ? reqOrigin : origin[0])
+                    : origin
+            );
+        }
+
+        ctx.header('Access-Control-Allow-Origin', allowOrigin);
+        ctx.header('Access-Control-Allow-Methods', methods);
+        ctx.header('Access-Control-Allow-Headers', headers);
+        if (credentials) ctx.header('Access-Control-Allow-Credentials', 'true');
+
+        // Preflight OPTIONS
+        if (ctx.method === 'OPTIONS') {
+            ctx.header('Access-Control-Max-Age', String(maxAge));
+            ctx.status(204).end();
+            return;
+        }
+
+        await next();
+    };
+}
+
+/**
+ * 세션 인증 미들웨어
+ * ctx.session.userId → db.User.find() → ctx.user
+ * @param {object} [opts]
+ * @param {string} [opts.sessionKey='userId']
+ * @param {string} [opts.model='User']
+ * @param {string} [opts.redirectTo='/login']
+ */
+export function auth(opts = {}) {
+    const sessionKey = opts.sessionKey || 'userId';
+    const modelName = opts.model || 'User';
+    const redirectTo = opts.redirectTo || null;
+
+    return async (ctx, next) => {
+        const userId = ctx._rawSession?.[sessionKey] || ctx.get('x-test-user-id');
+
+        if (!userId) {
+            if (redirectTo) {
+                ctx.redirect(redirectTo);
+            } else {
+                ctx.status(401).json({ error: { message: 'Unauthorized', status: 401 } });
+            }
+            return;
+        }
+
+        // DB 조회 (ModelRegistry 사용)
+        if (ctx.app?.db?.[modelName]) {
+            try {
+                ctx.user = await ctx.app.db[modelName].find(userId);
+            } catch {
+                ctx.user = { id: userId };
+            }
+        } else {
+            ctx.user = { id: userId };
+        }
+
+        await next();
+    };
+}
+
+/**
+ * JWT Bearer 토큰 인증 미들웨어
+ * Authorization: Bearer <token> → 검증 → ctx.user
+ * @param {object} [opts]
+ * @param {string} [opts.secret] - JWT 시크릿 (config에서도 읽음)
+ * @param {string} [opts.model='User']
+ */
+export function apiAuth(opts = {}) {
+    const modelName = opts.model || 'User';
+
+    return async (ctx, next) => {
+        const authHeader = ctx.get('authorization') || '';
+
+        if (!authHeader.startsWith('Bearer ')) {
+            ctx.status(401).json({ error: { message: 'Token required', status: 401 } });
+            return;
+        }
+
+        const token = authHeader.slice(7);
+
+        // JWT 검증 — Bridge crypto 사용 가능 시 위임
+        try {
+            const secret = opts.secret || ctx.app?.config?.get('app.auth.secret', 'fuzionx');
+            const payload = decodeJwtPayload(token, secret);
+
+            if (!payload || !payload.sub) {
+                ctx.status(401).json({ error: { message: 'Invalid token', status: 401 } });
+                return;
+            }
+
+            // DB에서 유저 조회
+            if (ctx.app?.db?.[modelName]) {
+                ctx.user = await ctx.app.db[modelName].find(payload.sub);
+            } else {
+                ctx.user = { id: payload.sub, ...payload };
+            }
+        } catch {
+            ctx.status(401).json({ error: { message: 'Invalid token', status: 401 } });
+            return;
+        }
+
+        await next();
+    };
+}
+
+/**
+ * CSRF 보호 미들웨어
+ * GET/HEAD/OPTIONS 는 통과, 나머지는 토큰 검증
+ * @param {object} [opts]
+ * @param {string} [opts.headerName='x-csrf-token']
+ * @param {string} [opts.sessionKey='_csrfToken']
+ */
+export function csrf(opts = {}) {
+    const headerName = opts.headerName || 'x-csrf-token';
+    const sessionKey = opts.sessionKey || '_csrfToken';
+
+    return async (ctx, next) => {
+        // 안전한 메서드는 통과
+        if (['GET', 'HEAD', 'OPTIONS'].includes(ctx.method)) {
+            await next();
+            return;
+        }
+
+        const token = ctx.get(headerName);
+        const expected = ctx._rawSession?.[sessionKey];
+
+        if (!token || !expected || token !== expected) {
+            ctx.status(403).json({ error: { message: 'CSRF token mismatch', status: 403 } });
+            return;
+        }
+
+        await next();
+    };
+}
+
+/**
+ * JWT 디코드 + HMAC-SHA256 서명 검증
+ * @param {string} token - JWT 토큰
+ * @param {string} secret - HMAC 시크릿 키
+ * @returns {object|null} - 검증된 payload 또는 null
+ * @private
+ */
+function decodeJwtPayload(token, secret) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3) return null;
+
+        const [headerB64, payloadB64, signatureB64] = parts;
+
+        // ── HMAC-SHA256 서명 검증 ──
+        const { createHmac, timingSafeEqual } = require('node:crypto');
+        const signingInput = `${headerB64}.${payloadB64}`;
+        const expectedSig = createHmac('sha256', secret)
+            .update(signingInput)
+            .digest();
+
+        // base64url → Buffer
+        const actualSig = Buffer.from(signatureB64, 'base64url');
+
+        // 길이 불일치 시 즉시 거부 (timingSafeEqual은 길이 같아야 함)
+        if (expectedSig.length !== actualSig.length) return null;
+        if (!timingSafeEqual(expectedSig, actualSig)) return null;
+
+        // ── payload 디코드 ──
+        const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+
+        // 만료 체크
+        if (payload.exp !== undefined && Date.now() / 1000 > payload.exp) return null;
+
+        // nbf (Not Before) 체크
+        if (payload.nbf !== undefined && Date.now() / 1000 < payload.nbf) return null;
+
+        return payload;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 세션 로드/저장 미들웨어
+ * Bridge sessionGet/sessionSet 사용.
+ *
+ * @see docs/framework/12-middleware.md — "session: 세션 로드/저장"
+ */
+export function session(opts = {}) {
+    return async (ctx, next) => {
+        // Session은 Context 생성 시 rawReq.session에서 이미 로드됨
+        // Bridge가 rawReq에 session 데이터를 포함하여 전달
+
+        await next();
+
+        // 요청 완료 후 — 소비된 flash 데이터 정리
+        // flash는 getFlash() 호출 시 로컬에서 삭제되지만,
+        // Bridge 세션 저장소에서도 제거해야 함
+        const bridge = ctx.app?._bridge;
+        const sessionId = ctx._sessionId;
+        if (sessionId && bridge?.sessionSet && ctx._rawSession) {
+            // _flash가 비었으면 세션에서 제거
+            if (ctx._rawSession._flash && Object.keys(ctx._rawSession._flash).length === 0) {
+                delete ctx._rawSession._flash;
+            }
+            try {
+                bridge.sessionSet(sessionId, ctx._rawSession);
+            } catch {}
+        }
+    };
+}
+
+/**
+ * 테마 미들웨어 — 도메인 → 테마 매핑
+ *
+ * @see docs/framework/03-views-templates.md
+ * @see docs/framework/12-middleware.md — "theme: 도메인 → 테마 매핑"
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.default='default'] - 기본 테마
+ * @param {object} [opts.mapping] - { 'domain.com': 'theme1' }
+ */
+export function theme(opts = {}) {
+    const defaultTheme = opts.default || 'default';
+    const mapping = opts.mapping || {};
+
+    return async (ctx, next) => {
+        // YAML 설정에서 매핑 읽기
+        const configMapping = ctx.app?.config?.get('themes.mapping') || mapping;
+        const configDefault = ctx.app?.config?.get('themes.default') || defaultTheme;
+
+        const host = ctx.host?.split(':')[0] || ''; // 포트 제거
+        ctx.theme = configMapping[host] || configDefault;
+
+        await next();
+    };
+}
+

package/lib/realtime/RoomManager.js

@@ -0,0 +1,85 @@
+/**
+ * RoomManager — 전체 룸 상태 관리 (Primary 프로세스)
+ *
+ * @see docs/framework/class-design.mm.md (RoomManager)
+ */
+export default class RoomManager {
+    constructor() {
+        /** @type {Map<string, Set<string>>} roomName → Set<socketId> */
+        this._rooms = new Map();
+    }
+
+    /**
+     * 룸에 참가
+     * @param {string} room
+     * @param {string} socketId
+     */
+    join(room, socketId) {
+        if (!this._rooms.has(room)) {
+            this._rooms.set(room, new Set());
+        }
+        this._rooms.get(room).add(socketId);
+    }
+
+    /**
+     * 룸에서 퇴장
+     * @param {string} room
+     * @param {string} socketId
+     */
+    leave(room, socketId) {
+        const members = this._rooms.get(room);
+        if (!members) return;
+        members.delete(socketId);
+        if (members.size === 0) {
+            this._rooms.delete(room);
+        }
+    }
+
+    /**
+     * 소켓이 속한 모든 룸에서 퇴장
+     * @param {string} socketId
+     */
+    leaveAll(socketId) {
+        for (const [room, members] of this._rooms) {
+            members.delete(socketId);
+            if (members.size === 0) {
+                this._rooms.delete(room);
+            }
+        }
+    }
+
+    /**
+     * 룸 멤버 조회
+     * @param {string} room
+     * @returns {string[]}
+     */
+    members(room) {
+        const members = this._rooms.get(room);
+        return members ? [...members] : [];
+    }
+
+    /**
+     * 룸 존재 여부
+     * @param {string} room
+     * @returns {boolean}
+     */
+    has(room) {
+        return this._rooms.has(room) && this._rooms.get(room).size > 0;
+    }
+
+    /**
+     * 전체 룸 목록
+     * @returns {string[]}
+     */
+    rooms() {
+        return [...this._rooms.keys()];
+    }
+
+    /**
+     * 룸 수
+     * @returns {number}
+     */
+    get size() {
+        return this._rooms.size;
+    }
+}

package/lib/realtime/WsHandler.js

@@ -0,0 +1,107 @@
+/**
+ * WsHandler — WebSocket 네임스페이스 핸들러
+ *
+ * @see docs/framework/11-websocket.md
+ * @see docs/framework/class-design.mm.md (WsHandler + EventBuilder)
+ */
+import Base from '../core/Base.js';
+
+/**
+ * EventBuilder — static events(e) DSL에서 사용
+ *
+ * @example
+ * static events(e) {
+ *     e.on('chat', this.handleChat);
+ *     e.on('typing', this.handleTyping, ['rateLimit:10']);
+ * }
+ */
+export class EventBuilder {
+    constructor() {
+        this._events = [];
+    }
+
+    /**
+     * 이벤트 핸들러 등록
+     * @param {string} type - 이벤트 타입
+     * @param {Function|object} handler - 핸들러 메서드 레퍼런스
+     * @param {string[]} [middleware] - 이벤트별 미들웨어
+     */
+    on(type, handler, middleware = []) {
+        this._events.push({ type, handler, middleware });
+    }
+}
+
+export default class WsHandler extends Base {
+    /** @type {string} 네임스페이스 경로 (e.g. '/chat') */
+    static namespace = '/';
+
+    /** @type {string[]} 핸드셰이크 미들웨어 */
+    static middleware = [];
+
+    /**
+     * 이벤트 라우팅 선언 (서브클래스에서 오버라이드)
+     * @param {EventBuilder} e
+     */
+    static events(e) {
+        // 서브클래스에서:
+        // e.on('chat', this.handleChat);
+        // e.on('typing', this.handleTyping, ['rateLimit:10']);
+    }
+
+    /**
+     * 이벤트 라우팅 맵 빌드
+     * @returns {Map<string, {handler, middleware}>}
+     */
+    static buildEventMap() {
+        const builder = new EventBuilder();
+        this.events(builder);
+        const map = new Map();
+        for (const { type, handler, middleware } of builder._events) {
+            map.set(type, { handler, middleware });
+        }
+        return map;
+    }
+
+    // ── 라이프사이클 훅 ──
+
+    /**
+     * 연결 시 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     */
+    async onConnect(socket) {}
+
+    /**
+     * 이벤트 핸들러 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     * @param {string} event
+     * @param {*} data
+     */
+    async onEvent(socket, event, data) {}
+
+    /**
+     * 연결 해제 시 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     * @param {number} code
+     * @param {string} reason
+     */
+    async onDisconnect(socket, code, reason) {}
+
+    /**
+     * 미등록 이벤트 수신 시 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     * @param {string} type
+     * @param {*} data
+     */
+    async onUnknownEvent(socket, type, data) {
+        // 기본: 무시 (서브클래스에서 오버라이드 가능)
+    }
+
+    /**
+     * 에러 시 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     * @param {Error} error
+     */
+    async onError(socket, error) {
+        this.logger?.error(`WS error in ${this.constructor.namespace}:`, error);
+    }
+}

package/lib/schedule/Job.js

@@ -0,0 +1,34 @@
+/**
+ * Job — 정기 실행 작업 (cron 스케줄)
+ *
+ * @see docs/framework/10-scheduler-queue.md
+ * @see docs/framework/class-design.mm.md (Job)
+ */
+import Base from '../core/Base.js';
+
+export default class Job extends Base {
+    /** @type {string} cron 표현식 또는 간편 표현 (every:5m, daily:02:00) */
+    static schedule = '';
+
+    /** @type {number} 타임아웃 (ms), 기본 30초 */
+    static timeout = 30000;
+
+    /** @type {boolean} false면 스킵 */
+    static enabled = true;
+
+    /**
+     * Job 실행 (서브클래스에서 오버라이드)
+     * @returns {Promise<void>}
+     */
+    async handle() {
+        throw new Error(`${this.constructor.name}.handle() must be implemented`);
+    }
+
+    /**
+     * Job 실패 시 호출 (서브클래스에서 오버라이드)
+     * @param {Error} error
+     */
+    async onError(error) {
+        this.logger.error(`Job ${this.constructor.name} failed:`, error);
+    }
+}

package/lib/schedule/Queue.js

@@ -0,0 +1,90 @@
+/**
+ * Queue — Task 큐 관리 (Memory/Redis)
+ *
+ * @see docs/framework/10-scheduler-queue.md
+ * @see docs/framework/class-design.mm.md (Queue)
+ */
+export default class Queue {
+    /**
+     * @param {import('./Application.js').default} app
+     * @param {object} [opts]
+     * @param {string} [opts.driver='memory'] - 'memory' | 'redis'
+     */
+    constructor(app, opts = {}) {
+        this.app = app;
+        this.driver = opts.driver || 'memory';
+        this._tasks = new Map();    // 등록된 Task 클래스
+        this._queue = [];            // 메모리 큐
+        this._processing = false;
+    }
+
+    /**
+     * Task 클래스 등록
+     * @param {string} name
+     * @param {typeof import('./Task.js').default} TaskClass
+     */
+    register(name, TaskClass) {
+        this._tasks.set(name, TaskClass);
+    }
+
+    /**
+     * Task 디스패치 (큐에 추가)
+     * @param {string|Function} taskOrName
+     * @param {object} data
+     * @param {object} [opts]
+     */
+    dispatch(taskOrName, data, opts = {}) {
+        const name = typeof taskOrName === 'string' ? taskOrName : taskOrName.name;
+        this._queue.push({ name, data, opts, retries: 0 });
+
+        // auto-process (비동기)
+        if (!this._processing) {
+            this._process();
+        }
+    }
+
+    /**
+     * 큐 처리 루프
+     * @private
+     */
+    async _process() {
+        this._processing = true;
+
+        while (this._queue.length > 0) {
+            const job = this._queue.shift();
+            const TaskClass = this._tasks.get(job.name);
+
+            if (!TaskClass) {
+                this.app?.logger?.error?.(`Task '${job.name}' not registered`);
+                continue;
+            }
+
+            const task = new TaskClass(this.app);
+            try {
+                await task.handle(job.data);
+            } catch (err) {
+                job.retries++;
+                if (job.retries < (TaskClass.retries || 3)) {
+                    // 재시도
+                    const delay = TaskClass.retryDelay || 1000;
+                    setTimeout(() => {
+                        this._queue.push(job);
+                        if (!this._processing) this._process();
+                    }, delay);
+                } else {
+                    await task.failed(job.data, err);
+                }
+            }
+        }
+
+        this._processing = false;
+    }
+
+    /**
+     * 남은 큐 수
+     * @returns {number}
+     */
+    get pending() {
+        return this._queue.length;
+    }
+}