@fuzionx/framework 0.1.30 → 0.1.31

package/lib/middleware/index.js

@@ -1,282 +1,13 @@
 /**
- * 내장 미들웨어 — bodyParser, cors, auth, apiAuth, csrf
+ * 내장 미들웨어 — 배럴 re-export
  *
  * @see docs/framework/12-middleware.md
  * @see docs/framework/14-authentication.md
  */
-import { createHmac, timingSafeEqual } from 'node:crypto';
-
-/**
- * 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 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';
-
-    return async (ctx, next) => {
-        // 앱별 테마 결정 — 도메인→앱 라우팅은 Application._resolveApp()에서 처리
-        const configDefault = ctx.app?.config?.get('app.themes.default') || defaultTheme;
-        ctx.theme = configDefault;
-
-        await next();
-    };
-}
-
+export { bodyParser } from './bodyParser.js';
+export { cors } from './cors.js';
+export { auth } from './auth.js';
+export { apiAuth } from './apiAuth.js';
+export { csrf } from './csrf.js';
+export { session } from './session.js';
+export { theme } from './theme.js';

package/lib/middleware/session.js

@@ -0,0 +1,27 @@
+/**
+ * session — 세션 로드/저장 미들웨어
+ *
+ * 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 데이터 정리
+        const bridge = ctx.app?._bridge;
+        const sessionId = ctx._sessionId;
+        if (sessionId && bridge?.sessionSet && ctx._rawSession) {
+            if (ctx._rawSession._flash && Object.keys(ctx._rawSession._flash).length === 0) {
+                delete ctx._rawSession._flash;
+            }
+            try {
+                bridge.sessionSet(sessionId, ctx._rawSession);
+            } catch {}
+        }
+    };
+}

package/lib/middleware/theme.js

@@ -0,0 +1,20 @@
+/**
+ * theme — 도메인 → 테마 매핑 미들웨어
+ *
+ * @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';
+
+    return async (ctx, next) => {
+        const configDefault = ctx.app?.config?.get('app.themes.default') || defaultTheme;
+        ctx.theme = configDefault;
+
+        await next();
+    };
+}

package/lib/schedule/Job.js

@@ -18,6 +18,10 @@ export default class Job extends Base {
 
     /**
      * Job 실행 (서브클래스에서 오버라이드)
+     *
+     * 메인 스레드에서 실행되므로 this.db, this.service() 등 접근 가능.
+     * CPU-intensive 작업은 this.worker.run() 또는 this.worker.exec()으로 위임.
+     *
      * @returns {Promise<void>}
      */
     async handle() {

package/lib/schedule/Queue.js

@@ -1,20 +1,26 @@
 /**
  * Queue — Task 큐 관리 (Memory/Redis)
  *
+ * AutoLoader가 shared/jobs/ 에서 Task 클래스를 자동 스캔·등록.
+ * handle(data)은 메인 스레드에서 실행되므로 this.db, this.service() 등
+ * 앱 컨텍스트에 접근 가능합니다.
+ *
+ * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
+ *
  * @see docs/framework/10-scheduler-queue.md
- * @see docs/framework/class-design.mm.md (Queue)
+ * @see lib/schedule/WorkerPool.js
  */
 export default class Queue {
     /**
-     * @param {import('./Application.js').default} app
+     * @param {import('../core/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._tasks = new Map();  // name → TaskClass
+        this._queue = [];
         this._processing = false;
     }
 
@@ -55,24 +61,30 @@ export default class Queue {
             const TaskClass = this._tasks.get(job.name);
 
             if (!TaskClass) {
-                this.app?.logger?.error?.(`Task '${job.name}' not registered`);
+                this.app?.logger?.error?.(`[Queue] Task '${job.name}' not registered`);
                 continue;
             }
 
+            const timeout = TaskClass.timeout || 30000;
             const task = new TaskClass(this.app);
+
             try {
-                await task.handle(job.data);
+                await Promise.race([
+                    task.handle(job.data),
+                    new Promise((_, reject) =>
+                        setTimeout(() => reject(new Error(`Task timeout (${timeout}ms)`)), timeout)
+                    ),
+                ]);
             } 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);
+                    try { await task.failed(job.data, err); } catch {}
                 }
             }
         }

package/lib/schedule/Scheduler.js

@@ -1,38 +1,47 @@
 /**
- * Scheduler — Job 스케줄 관리 (마스터 프로세스)
+ * Scheduler — 정기 실행 작업 관리 (cron 스케줄)
+ *
+ * AutoLoader가 shared/jobs/ 에서 Job 클래스를 자동 스캔·등록.
+ * handle()은 메인 스레드에서 실행되므로 this.db, this.service() 등
+ * 앱 컨텍스트에 접근 가능합니다.
+ *
+ * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
  *
  * @see docs/framework/10-scheduler-queue.md
- * @see docs/framework/class-design.mm.md (Scheduler)
+ * @see lib/schedule/WorkerPool.js
  */
 export default class Scheduler {
+    /**
+     * @param {import('../core/Application.js').default} app
+     */
     constructor(app) {
         this.app = app;
+        /** @type {Array<{JobClass: typeof import('./Job.js').default}>} */
         this._jobs = [];
+        /** @type {Array<NodeJS.Timeout>} */
         this._timers = [];
-        this._running = false;
     }
 
     /**
-     * Job 등록
+     * Job 클래스 등록 (AutoLoader에서 호출)
      * @param {typeof import('./Job.js').default} JobClass
      */
     register(JobClass) {
-        this._jobs.push(JobClass);
+        if (!JobClass.schedule) return;
+        if (JobClass.enabled === false) return;
+        this._jobs.push({ JobClass });
     }
 
     /**
-     * 모든 스케줄 시작
+     * 등록된 모든 Job 시작
      */
     start() {
-        if (this._running) return;
-        this._running = true;
-
-        for (const JobClass of this._jobs) {
-            // enabled === false면 스킵 (10-scheduler-queue.md)
-            if (JobClass.enabled === false) continue;
-
-            const interval = this._parseCron(JobClass.schedule);
-            if (!interval) continue;
+        for (const { JobClass } of this._jobs) {
+            const interval = this._parseSchedule(JobClass.schedule);
+            if (!interval) {
+                this.app?.logger?.warn?.(`[Scheduler] Invalid schedule: ${JobClass.name} → '${JobClass.schedule}'`);
+                continue;
+            }
 
             const timeout = JobClass.timeout || 30000;
 
@@ -46,7 +55,11 @@ export default class Scheduler {
                         ),
                     ]);
                 } catch (err) {
-                    await job.onError(err);
+                    if (typeof job.onError === 'function') {
+                        try { await job.onError(err); } catch {}
+                    } else {
+                        this.app?.logger?.error?.(`[Scheduler] ${JobClass.name} failed: ${err.message}`);
+                    }
                 }
             };
 
@@ -62,12 +75,18 @@ export default class Scheduler {
             } else {
                 const timer = setInterval(runJob, interval);
                 this._timers.push(timer);
+                // 즉시 첫 실행
+                runJob();
             }
+
+            this.app?.logger?.info?.(
+                `[Scheduler] ${JobClass.name} registered (${JobClass.schedule}, interval=${interval}ms)`
+            );
         }
     }
 
     /**
-     * 모든 스케줄 정지
+     * 모든 타이머 정지
      */
     stop() {
         for (const timer of this._timers) {
@@ -75,87 +94,77 @@ export default class Scheduler {
             clearTimeout(timer);
         }
         this._timers = [];
-        this._running = false;
+    }
+
+    // ── Schedule 파싱 ──
+
+    /**
+     * 간편 스케줄 → ms 변환
+     *
+     * 지원 포맷:
+     *   'every:5s'  → 5000ms
+     *   'every:5m'  → 300000ms
+     *   'every:1h'  → 3600000ms
+     *   'daily:HH:MM'      → 24h (첫 실행은 _calcInitialDelay)
+     *   'weekly:DAY:HH:MM' → 7d  (첫 실행은 _calcInitialDelay)
+     */
+    _parseSchedule(schedule) {
+        if (!schedule) return null;
+
+        // every:Ns/Nm/Nh
+        const everyMatch = schedule.match(/^every:(\d+)(s|m|h)$/i);
+        if (everyMatch) {
+            const val = parseInt(everyMatch[1], 10);
+            const unit = everyMatch[2].toLowerCase();
+            if (unit === 's') return val * 1000;
+            if (unit === 'm') return val * 60000;
+            if (unit === 'h') return val * 3600000;
+        }
+
+        // daily:HH:MM → 24시간 간격
+        if (/^daily:\d{2}:\d{2}$/.test(schedule)) {
+            return 24 * 60 * 60 * 1000;
+        }
+
+        // weekly:DAY:HH:MM → 7일 간격
+        if (/^weekly:\w+:\d{2}:\d{2}$/.test(schedule)) {
+            return 7 * 24 * 60 * 60 * 1000;
+        }
+
+        return null;
     }
 
     /**
-     * daily/weekly 스케줄의 첫 실행까지 지연(ms) 계산
-     * @param {string} schedule
-     * @returns {number} 0이면 즉시 setInterval, >0이면 setTimeout 필요
-     * @private
+     * daily/weekly 스케줄의 첫 실행 지연시간 계산
      */
     _calcInitialDelay(schedule) {
         const now = new Date();
 
-        // 'daily:HH:MM'
+        // daily:HH:MM
         const dailyMatch = schedule.match(/^daily:(\d{2}):(\d{2})$/);
         if (dailyMatch) {
-            const [, h, m] = dailyMatch;
             const target = new Date(now);
-            target.setHours(Number(h), Number(m), 0, 0);
+            target.setHours(parseInt(dailyMatch[1], 10), parseInt(dailyMatch[2], 10), 0, 0);
             if (target <= now) target.setDate(target.getDate() + 1);
             return target - now;
         }
 
-        // 'weekly:day:HH:MM'
+        // weekly:DAY:HH:MM
         const weeklyMatch = schedule.match(/^weekly:(\w+):(\d{2}):(\d{2})$/);
         if (weeklyMatch) {
             const days = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
-            const [, day, h, m] = weeklyMatch;
-            const targetDay = days[day.toLowerCase()] ?? 0;
+            const targetDay = days[weeklyMatch[1].toLowerCase()];
+            if (targetDay === undefined) return 0;
+
             const target = new Date(now);
-            target.setHours(Number(h), Number(m), 0, 0);
+            target.setHours(parseInt(weeklyMatch[2], 10), parseInt(weeklyMatch[3], 10), 0, 0);
+
             let diff = targetDay - now.getDay();
             if (diff < 0 || (diff === 0 && target <= now)) diff += 7;
             target.setDate(target.getDate() + diff);
             return target - now;
         }
 
-        return 0; // every:*, cron → 즉시 setInterval
-    }
-
-    /**
-     * 간단 cron 파서 — 간격(ms) 또는 다음 실행까지 지연(ms) 반환
-     * 지원:
-     *   'every:30s' / 'every:5m' / 'every:1h'
-     *   'daily:02:00' — 매일 HH:MM
-     *   'weekly:mon:09:00' — 매주 요일 HH:MM
-     *   '* * * * *' — 매분 (60초)
-     *   5-field cron — 분 단위 간격 근사
-     * @private
-     */
-    _parseCron(schedule) {
-        if (!schedule) return null;
-
-        // 'every:30s' → 30000ms
-        const everyMatch = schedule.match(/^every:(\d+)([smh])$/);
-        if (everyMatch) {
-            const [, num, unit] = everyMatch;
-            const multiplier = { s: 1000, m: 60000, h: 3600000 };
-            return Number(num) * multiplier[unit];
-        }
-
-        // 'daily:HH:MM' → 24h interval
-        const dailyMatch = schedule.match(/^daily:(\d{2}):(\d{2})$/);
-        if (dailyMatch) {
-            return 86400000;
-        }
-
-        // 'weekly:day:HH:MM' → 7일 간격
-        const weeklyMatch = schedule.match(/^weekly:\w+:\d{2}:\d{2}$/);
-        if (weeklyMatch) {
-            return 604800000;
-        }
-
-        // 5-field cron: '*/5 * * * *' → 분 단위 추출
-        const cronMatch = schedule.match(/^\*\/(\d+)\s/);
-        if (cronMatch) {
-            return Number(cronMatch[1]) * 60000;
-        }
-
-        // '* * * * *' → 60000ms (매분)
-        if (schedule.match(/^[\d*\/,-]+(\s[\d*\/,-]+){4}$/)) return 60000;
-
-        return null;
+        return 0; // every:* → 즉시 시작
     }
 }