@fuzionx/framework 0.1.75 → 0.1.77

package/lib/middleware/apiAuth.js

@@ -3,13 +3,17 @@
  *
  * Authorization: Bearer <token> → 검증 → ctx.user
  *
+ * 인증 실패 시 ServiceError(401) throw → ErrorHandler가 Accept 협상으로 응답.
+ *
  * @see docs/framework/14-authentication.md
+ * @see docs/framework/08-error-handling.md
  *
  * @param {object} [opts]
  * @param {string} [opts.secret] - JWT 시크릿
  * @param {string} [opts.model='User']
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { ServiceError } from '../core/AppError.js';
 
 export function apiAuth(opts = {}) {
     const modelName = opts.model || 'User';
@@ -18,29 +22,27 @@ export function apiAuth(opts = {}) {
         const authHeader = ctx.get('authorization') || '';
 
         if (!authHeader.startsWith('Bearer ')) {
-            ctx.status(401).json({ error: { message: 'Token required', status: 401 } });
-            return;
+            throw new ServiceError('Token required', 401);
         }
 
         const token = authHeader.slice(7);
+        const secret = opts.secret || ctx.app?.config?.get('app.auth.secret', 'fuzionx');
 
+        let payload;
         try {
-            const secret = opts.secret || ctx.app?.config?.get('app.auth.secret', 'fuzionx');
-            const payload = decodeJwtPayload(token, secret);
+            payload = decodeJwtPayload(token, secret);
+        } catch {
+            throw new ServiceError('Invalid token', 401);
+        }
 
-            if (!payload || !payload.sub) {
-                ctx.status(401).json({ error: { message: 'Invalid token', status: 401 } });
-                return;
-            }
+        if (!payload || !payload.sub) {
+            throw new ServiceError('Invalid token', 401);
+        }
 
-            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;
+        if (ctx.app?.db?.[modelName]) {
+            ctx.user = await ctx.app.db[modelName].find(payload.sub);
+        } else {
+            ctx.user = { id: payload.sub, ...payload };
         }
 
         await next();

package/lib/middleware/auth.js

@@ -3,13 +3,20 @@
  *
  * ctx.session.userId → db.User.find() → ctx.user
  *
+ * 미인증 처리:
+ *   - redirectTo 지정 시: 해당 URL로 302 리다이렉트 (HTML 라우트용)
+ *   - 미지정 시: ServiceError(401) throw → ErrorHandler가 Accept 협상으로 응답 형식 결정
+ *
  * @see docs/framework/14-authentication.md
+ * @see docs/framework/08-error-handling.md
  *
  * @param {object} [opts]
  * @param {string} [opts.sessionKey='userId']
  * @param {string} [opts.model='User']
- * @param {string} [opts.redirectTo='/login']
+ * @param {string} [opts.redirectTo] - 미지정 시 401 throw, 지정 시 해당 URL로 redirect
  */
+import { ServiceError } from '../core/AppError.js';
+
 export function auth(opts = {}) {
     const sessionKey = opts.sessionKey || 'userId';
     const modelName = opts.model || 'User';
@@ -21,10 +28,9 @@ export function auth(opts = {}) {
         if (!userId) {
             if (redirectTo) {
                 ctx.redirect(redirectTo);
-            } else {
-                ctx.status(401).json({ error: { message: 'Unauthorized', status: 401 } });
+                return;
             }
-            return;
+            throw new ServiceError('Unauthorized', 401);
         }
 
         if (ctx.app?.db?.[modelName]) {

package/lib/middleware/csrf.js

@@ -2,13 +2,17 @@
  * csrf — CSRF 보호 미들웨어
  *
  * GET/HEAD/OPTIONS 는 통과, 나머지는 토큰 검증.
+ * 토큰 불일치 시 ServiceError(403) throw → ErrorHandler가 Accept 협상으로 응답.
  *
  * @see docs/framework/12-middleware.md
+ * @see docs/framework/08-error-handling.md
  *
  * @param {object} [opts]
  * @param {string} [opts.headerName='x-csrf-token']
  * @param {string} [opts.sessionKey='_csrfToken']
  */
+import { ServiceError } from '../core/AppError.js';
+
 export function csrf(opts = {}) {
     const headerName = opts.headerName || 'x-csrf-token';
     const sessionKey = opts.sessionKey || '_csrfToken';
@@ -23,8 +27,7 @@ export function csrf(opts = {}) {
         const expected = ctx._rawReq?.session?.[sessionKey];
 
         if (!token || !expected || token !== expected) {
-            ctx.status(403).json({ error: { message: 'CSRF token mismatch', status: 403 } });
-            return;
+            throw new ServiceError('CSRF token mismatch', 403);
         }
 
         await next();

package/lib/middleware/roleGuard.js

@@ -4,6 +4,10 @@
  * `auth()` 미들웨어 이후에 사용.
  * ctx.user.role_code가 허용된 역할 목록에 포함되는지 검사.
  *
+ * 거부 시 ServiceError throw → ErrorHandler가 Accept 협상으로 응답.
+ *   - 미인증: 401
+ *   - 권한 부족: 403
+ *
  * @example
  * // 관리자 백오피스: developer, admin만 허용
  * r.group('/api', { middleware: [auth(), roleGuard(['developer', 'admin'])] }, (r) => { ... });
@@ -12,6 +16,7 @@
  * r.group('/api', { middleware: [auth(), roleGuard(['developer', 'admin', 'reseller'])] }, (r) => { ... });
  *
  * @see docs/framework/14-authentication.md
+ * @see docs/framework/08-error-handling.md
  *
  * @param {string[]} allowedRoles - 접근 허용 역할 코드 배열
  * @param {object} [opts]
@@ -19,6 +24,8 @@
  * @param {string} [opts.message='auth.role_denied'] - 거부 시 에러 메시지 키
  * @returns {Function} 미들웨어 함수
  */
+import { ServiceError } from '../core/AppError.js';
+
 export function roleGuard(allowedRoles, opts = {}) {
     const roleField = opts.roleField || 'role_code';
     const message = opts.message || 'auth.role_denied';
@@ -26,8 +33,7 @@ export function roleGuard(allowedRoles, opts = {}) {
     return async (ctx, next) => {
         /** 인증되지 않은 사용자 */
         if (!ctx.user) {
-            ctx.status(401).json({ error: { message: 'Unauthorized', status: 401 } });
-            return;
+            throw new ServiceError('Unauthorized', 401);
         }
 
         /** 역할 코드 추출 */
@@ -35,13 +41,8 @@ export function roleGuard(allowedRoles, opts = {}) {
 
         /** 허용된 역할인지 확인 */
         if (!userRole || !allowedRoles.includes(userRole)) {
-            ctx.status(403).json({
-                error: {
-                    message: ctx.t ? ctx.t(message) : message,
-                    status: 403,
-                },
-            });
-            return;
+            const msg = (typeof ctx.t === 'function') ? ctx.t(message) : message;
+            throw new ServiceError(msg, 403);
         }
 
         await next();

package/lib/schedule/Queue.js

@@ -1,5 +1,5 @@
 /**
- * Queue — Task 큐 관리 (Memory/Redis)
+ * Queue — Task 큐 관리 (driver 분기: memory / redis)
  *
  * AutoLoader가 shared/jobs/ 에서 Task 클래스를 자동 스캔·등록.
  * handle(data)은 메인 스레드에서 실행되므로 this.db, this.service() 등
@@ -7,97 +7,97 @@
  *
  * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
  *
+ * Driver:
+ *   - 'memory' (기본): 단일 process 내, 재시작 시 손실
+ *   - 'redis': ioredis 기반 영구 큐, 멀티워커 안전
+ *
+ * 설정 (fuzionx.yaml):
+ *   queue:
+ *     driver: redis | memory
+ *     redis_url: "redis://:password@localhost:6379"   # redis 일 때만
+ *     prefix: "fuzionx:queue"                          # 선택 (default 동일)
+ *
  * @see docs/framework/10-scheduler-queue.md
+ * @see lib/schedule/drivers/MemoryQueueDriver.js
+ * @see lib/schedule/drivers/RedisQueueDriver.js
  * @see lib/schedule/WorkerPool.js
  */
+import MemoryQueueDriver from './drivers/MemoryQueueDriver.js';
+import RedisQueueDriver from './drivers/RedisQueueDriver.js';
+
 export default class Queue {
     /**
      * @param {import('../core/Application.js').default} app
      * @param {object} [opts]
      * @param {string} [opts.driver='memory'] - 'memory' | 'redis'
+     * @param {string} [opts.url] - redis driver 의 접속 URL
+     * @param {string} [opts.prefix] - redis driver 의 키 접두사
      */
     constructor(app, opts = {}) {
         this.app = app;
         this.driver = opts.driver || 'memory';
-        this._tasks = new Map();  // name → TaskClass
-        this._queue = [];
-        this._processing = false;
+
+        // driver 인스턴스 생성 — 외부 API 는 동일 (register/dispatch/pending)
+        if (this.driver === 'redis') {
+            this._impl = new RedisQueueDriver(app, opts);
+        } else {
+            this._impl = new MemoryQueueDriver(app, opts);
+        }
+    }
+
+    /**
+     * 드라이버 초기화 (Application.boot 에서 호출 권장).
+     * redis driver 는 connection + worker loop 시작.
+     *
+     * @returns {Promise<void>}
+     */
+    async start() {
+        if (typeof this._impl.start === 'function') {
+            await this._impl.start();
+        }
     }
 
     /**
-     * Task 클래스 등록
+     * Task 클래스 등록 (AutoLoader 가 호출).
+     *
      * @param {string} name
      * @param {typeof import('./Task.js').default} TaskClass
      */
     register(name, TaskClass) {
-        this._tasks.set(name, TaskClass);
+        this._impl.register(name, TaskClass);
     }
 
     /**
-     * Task 디스패치 (큐에 추가)
+     * Task 디스패치 — 큐에 enqueue.
+     *
      * @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();
-        }
+        this._impl.dispatch(taskOrName, data, opts);
     }
 
     /**
-     * 큐 처리 루프
-     * @private
+     * 대기 중 작업 수 (graceful shutdown 의 drain 판정용).
+     * - memory driver: 정확한 in-memory 큐 길이
+     * - redis driver: 0 반환 (Application 의 drain 로직은 memory 기준 설계 —
+     *   redis 는 별도 drain 필요. 운영자가 외부에서 wait)
+     *
+     * @returns {number}
      */
-    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?.(`[Queue] Task '${job.name}' not registered`);
-                continue;
-            }
-
-            const timeout = TaskClass.timeout || 30000;
-            const task = new TaskClass(this.app);
-
-            try {
-                let timer;
-                await Promise.race([
-                    task.handle(job.data).finally(() => clearTimeout(timer)),
-                    new Promise((_, reject) => {
-                        timer = 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 {
-                    try { await task.failed(job.data, err); } catch {}
-                }
-            }
-        }
-
-        this._processing = false;
+    get pending() {
+        return this._impl.pending;
     }
 
     /**
-     * 남은 큐 수
-     * @returns {number}
+     * graceful shutdown.
+     *
+     * @param {number} [timeoutMs=10000]
      */
-    get pending() {
-        return this._queue.length;
+    async stop(timeoutMs = 10000) {
+        if (typeof this._impl.stop === 'function') {
+            await this._impl.stop(timeoutMs);
+        }
     }
 }

package/lib/schedule/Scheduler.js

@@ -7,19 +7,67 @@
  *
  * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
  *
+ * ## Redis Leader Election (멀티워커 안전)
+ *
+ * `opts.url` (redis URL) 가 주어지면 매 Job 실행 직전 SET NX EX 로 lock 획득.
+ * 성공한 워커만 실행 → 멀티 worker / 멀티 server 환경에서 **단 1번만 실행**.
+ * redis 미설정 시 fallback — 각 워커가 자체 실행 (단일 인스턴스 환경 가정).
+ *
+ * Lock key 구조:
+ *   {prefix}:lock:{JobName}:{bucketTs}
+ *   - bucketTs = floor(now / interval) * interval — 같은 bucket 에선 1번만 실행
+ *   - TTL = interval × 0.9 (다음 bucket 진입 전 만료)
+ *
  * @see docs/framework/10-scheduler-queue.md
  * @see lib/schedule/WorkerPool.js
  */
 export default class Scheduler {
     /**
      * @param {import('../core/Application.js').default} app
+     * @param {object} [opts]
+     * @param {string} [opts.url] - Redis URL (leader election 활성). 미지정 시 fallback (각 워커 실행)
+     * @param {string} [opts.prefix='fuzionx:scheduler'] - lock key 접두사
      */
-    constructor(app) {
+    constructor(app, opts = {}) {
         this.app = app;
+        this._url = opts.url || null;
+        this._prefix = opts.prefix || 'fuzionx:scheduler';
+
         /** @type {Array<{JobClass: typeof import('./Job.js').default}>} */
         this._jobs = [];
         /** @type {Array<NodeJS.Timeout>} */
         this._timers = [];
+
+        /** @type {import('ioredis').default | null} leader election 용 redis client */
+        this._redis = null;
+    }
+
+    /**
+     * Redis 연결 (leader election 용). opts.url 있을 때만.
+     * Application.boot 에서 호출 — 실패해도 fallback 동작.
+     *
+     * @returns {Promise<void>}
+     */
+    async connect() {
+        if (!this._url) return;
+        try {
+            const { default: Redis } = await import('ioredis');
+            this._redis = new Redis(this._url, {
+                maxRetriesPerRequest: 3,
+                retryStrategy: (times) => {
+                    if (times > 5) return null;
+                    return Math.min(times * 200, 2000);
+                },
+                lazyConnect: false,
+            });
+            this._redis.on('error', (err) =>
+                this.app?.logger?.error?.(`[Scheduler:Redis] ${err.message}`),
+            );
+            this.app?.logger?.info?.(`[Scheduler] redis leader election enabled (prefix=${this._prefix})`);
+        } catch (e) {
+            this.app?.logger?.warn?.(`[Scheduler] redis connect failed — fallback to local: ${e.message}`);
+            this._redis = null;
+        }
     }
 
     /**
@@ -46,6 +94,24 @@ export default class Scheduler {
             const timeout = JobClass.timeout || 30000;
 
             const runJob = async () => {
+                // ── Redis leader election ──
+                // 같은 bucket 에선 1개 워커만 실행. redis 미연결 시 통과.
+                if (this._redis) {
+                    const bucketTs = Math.floor(Date.now() / interval) * interval;
+                    const lockKey = `${this._prefix}:lock:${JobClass.name}:${bucketTs}`;
+                    const lockTtlMs = Math.max(Math.floor(interval * 0.9), 1000);
+                    try {
+                        const acquired = await this._redis.set(lockKey, '1', 'PX', lockTtlMs, 'NX');
+                        if (acquired !== 'OK') {
+                            // 다른 워커가 이미 실행 — skip
+                            return;
+                        }
+                    } catch (e) {
+                        // redis 일시 장애 — fallback (실행 진행). 중복 가능하지만 실행 누락보단 안전
+                        this.app?.logger?.warn?.(`[Scheduler] lock acquire failed for ${JobClass.name}: ${e.message}`);
+                    }
+                }
+
                 const job = new JobClass(this.app);
                 try {
                     let timer;
@@ -87,14 +153,18 @@ export default class Scheduler {
     }
 
     /**
-     * 모든 타이머 정지
+     * 모든 타이머 정지 + redis 연결 종료
      */
-    stop() {
+    async stop() {
         for (const timer of this._timers) {
             clearInterval(timer);
             clearTimeout(timer);
         }
         this._timers = [];
+        if (this._redis) {
+            try { await this._redis.quit(); } catch {}
+            this._redis = null;
+        }
     }
 
     // ── Schedule 파싱 ──

package/lib/schedule/drivers/MemoryQueueDriver.js

@@ -0,0 +1,137 @@
+/**
+ * MemoryQueueDriver — 인메모리 Task 큐 드라이버
+ *
+ * Queue.js 의 기존 in-process 로직을 추출한 driver.
+ * 단일 process 내에서만 동작 — multi-worker / 재시작 잔존 불가.
+ * 개발/테스트 또는 단일 인스턴스 운영용.
+ *
+ * 큐 동작:
+ *   - dispatch: Array.push → 비동기 _process 자동 시작
+ *   - process loop: shift → Task 실행 → 실패 시 retry (TaskClass.retries 까지)
+ *   - 최종 실패: Task.failed(data, error) 호출
+ *
+ * @see lib/schedule/Queue.js
+ */
+export default class MemoryQueueDriver {
+    /**
+     * @param {import('../../core/Application.js').default} app
+     * @param {object} [opts]
+     */
+    constructor(app, opts = {}) {
+        this.app = app;
+        this.opts = opts;
+
+        /** @type {Map<string, typeof import('../Task.js').default>} Task 클래스 레지스트리 */
+        this._tasks = new Map();
+
+        /** @type {Array<{ name, data, opts, retries }>} 큐 배열 */
+        this._queue = [];
+
+        /** @type {boolean} process 루프 동작 중 여부 */
+        this._processing = false;
+    }
+
+    /**
+     * 드라이버 초기화 (no-op for memory).
+     * Queue 가 boot 시점에 호출.
+     *
+     * @returns {Promise<void>}
+     */
+    async start() {
+        // memory 는 별도 초기화 불필요
+    }
+
+    /**
+     * Task 클래스 등록 (AutoLoader 에서 호출).
+     *
+     * @param {string} name - Task 이름 (보통 클래스명)
+     * @param {typeof import('../Task.js').default} TaskClass
+     */
+    register(name, TaskClass) {
+        this._tasks.set(name, TaskClass);
+    }
+
+    /**
+     * Task 디스패치 — 큐에 추가 + 자동 처리.
+     *
+     * @param {string|Function} taskOrName - Task 이름 또는 클래스
+     * @param {object} data - handle(data) 에 전달
+     * @param {object} [opts]
+     */
+    dispatch(taskOrName, data, opts = {}) {
+        const name = typeof taskOrName === 'string' ? taskOrName : taskOrName.name;
+        this._queue.push({ name, data, opts, retries: 0 });
+
+        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?.(`[Queue] Task '${job.name}' not registered`);
+                continue;
+            }
+
+            const timeout = TaskClass.timeout || 30000;
+            const task = new TaskClass(this.app);
+
+            try {
+                let timer;
+                await Promise.race([
+                    task.handle(job.data).finally(() => clearTimeout(timer)),
+                    new Promise((_, reject) => {
+                        timer = 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 {
+                    try { await task.failed(job.data, err); } catch {}
+                }
+            }
+        }
+
+        this._processing = false;
+    }
+
+    /**
+     * 남은 큐 길이 (대기 중인 Task 수).
+     *
+     * @returns {number}
+     */
+    get pending() {
+        return this._queue.length;
+    }
+
+    /**
+     * graceful shutdown — 처리 중 작업 완료 대기.
+     * memory driver 는 _processing 가 false 될 때까지 polling.
+     *
+     * @param {number} [timeoutMs=10000]
+     * @returns {Promise<void>}
+     */
+    async stop(timeoutMs = 10000) {
+        const start = Date.now();
+        while (this._processing && Date.now() - start < timeoutMs) {
+            await new Promise(r => setTimeout(r, 100));
+        }
+    }
+}