@fuzionx/framework 0.1.29 → 0.1.31

package/lib/middleware/apiAuth.js

@@ -0,0 +1,79 @@
+/**
+ * apiAuth — JWT Bearer 토큰 인증 미들웨어
+ *
+ * Authorization: Bearer <token> → 검증 → ctx.user
+ *
+ * @see docs/framework/14-authentication.md
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.secret] - JWT 시크릿
+ * @param {string} [opts.model='User']
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+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);
+
+        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;
+            }
+
+            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();
+    };
+}
+
+/**
+ * JWT 디코드 + HMAC-SHA256 서명 검증
+ * @private
+ */
+function decodeJwtPayload(token, secret) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3) return null;
+
+        const [headerB64, payloadB64, signatureB64] = parts;
+
+        const signingInput = `${headerB64}.${payloadB64}`;
+        const expectedSig = createHmac('sha256', secret)
+            .update(signingInput)
+            .digest();
+
+        const actualSig = Buffer.from(signatureB64, 'base64url');
+        if (expectedSig.length !== actualSig.length) return null;
+        if (!timingSafeEqual(expectedSig, actualSig)) return null;
+
+        const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+
+        if (payload.exp !== undefined && Date.now() / 1000 > payload.exp) return null;
+        if (payload.nbf !== undefined && Date.now() / 1000 < payload.nbf) return null;
+
+        return payload;
+    } catch {
+        return null;
+    }
+}

package/lib/middleware/auth.js

@@ -0,0 +1,42 @@
+/**
+ * auth — 세션 인증 미들웨어
+ *
+ * ctx.session.userId → db.User.find() → ctx.user
+ *
+ * @see docs/framework/14-authentication.md
+ *
+ * @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;
+        }
+
+        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();
+    };
+}

package/lib/middleware/bodyParser.js

@@ -0,0 +1,19 @@
+/**
+ * bodyParser — JSON/Form body 파싱 미들웨어
+ *
+ * Bridge가 이미 파싱한 body를 보장.
+ * 추가 파싱이 필요한 경우 처리.
+ *
+ * @see docs/framework/12-middleware.md
+ */
+export function bodyParser() {
+    return async (ctx, next) => {
+        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();
+    };
+}

package/lib/middleware/cors.js

@@ -0,0 +1,47 @@
+/**
+ * cors — CORS 미들웨어
+ *
+ * @see docs/framework/12-middleware.md
+ *
+ * @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 === '*') {
+            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');
+
+        if (ctx.method === 'OPTIONS') {
+            ctx.header('Access-Control-Max-Age', String(maxAge));
+            ctx.status(204).end();
+            return;
+        }
+
+        await next();
+    };
+}

package/lib/middleware/csrf.js

@@ -0,0 +1,32 @@
+/**
+ * csrf — CSRF 보호 미들웨어
+ *
+ * GET/HEAD/OPTIONS 는 통과, 나머지는 토큰 검증.
+ *
+ * @see docs/framework/12-middleware.md
+ *
+ * @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();
+    };
+}

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 {}
                 }
             }
         }