@fuzionx/framework 0.1.76 → 0.1.77

package/cli/templates/make/app-spa/views/default/spa/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@fuzionx/player": "^0.1.76",
+    "@fuzionx/player": "^0.1.77",
     "pinia": "^3.0.4",
     "vue": "^3.5.0",
     "vue-router": "^4.5.0"

package/lib/core/Application.js

@@ -300,8 +300,50 @@ export default class Application {
         await this.i18n.load();
 
         // 3. Scheduler / Queue / Telegram / Storage / Cache 초기화
-        this._scheduler = new Scheduler(this);
-        this._queue = new Queue(this, { driver: this.config.get('queue.driver', 'memory') });
+        //
+        // yaml 구조:
+        //   app.scheduler.enabled / .lock.{driver,redis_url,prefix}
+        //   app.queue.{driver,redis_url,prefix}
+        // fuzionx 기존 코드는 top-level (config.get('queue')) 였지만 실제로는
+        // app.* 아래에 있음 — fallback 둘 다 지원.
+        const queueCfg     = this.config.get('app.queue')     || this.config.get('queue')     || {};
+        const schedulerCfg = this.config.get('app.scheduler') || this.config.get('scheduler') || {};
+        const lockCfg      = schedulerCfg.lock || {};
+
+        // Scheduler — leader election 용 redis URL
+        //   우선순위: app.scheduler.lock.redis_url → app.queue.redis_url 재사용
+        //   lock.driver !== 'redis' 면 leader election 비활성 (fallback)
+        const schedulerLockEnabled = lockCfg.driver === 'redis';
+        const schedulerRedisUrl = schedulerLockEnabled
+            ? (lockCfg.redis_url || queueCfg.redis_url || null)
+            : null;
+        this._scheduler = new Scheduler(this, {
+            url:    schedulerRedisUrl,
+            prefix: lockCfg.prefix || 'fuzionx:scheduler',
+        });
+        this._schedulerEnabled = schedulerCfg.enabled !== false;   // 기본 true
+        if (this._schedulerEnabled) {
+            try {
+                await this._scheduler.connect();
+            } catch (e) {
+                this.logger.warn(`[Scheduler] connect failed: ${e.message}`);
+            }
+        } else {
+            this.logger.info('[Scheduler] disabled (app.scheduler.enabled=false)');
+        }
+
+        this._queue = new Queue(this, {
+            driver: queueCfg.driver || 'memory',
+            url:    queueCfg.redis_url,
+            prefix: queueCfg.prefix,
+            brpopTimeoutSec:    queueCfg.brpop_timeout_sec,
+            promoterIntervalMs: queueCfg.promoter_interval_ms,
+        });
+        try {
+            await this._queue.start();
+        } catch (e) {
+            this.logger.error(`[Queue] start failed: ${e.message}`);
+        }
         
         // 텔레그램 매니저 로드 (Queue 기반이므로 _queue 설정 직후 구성)
         const telegramConfig = this.config.get('app.telegram');
@@ -531,8 +573,11 @@ export default class Application {
 
         // Scheduler 시작 — primary 프로세스에서만 (워커 중복 실행 방지)
         // fuzionx 상위 레이어가 cluster.fork()로 워커를 생성하므로
-        // cluster.isPrimary로 단일 프로세스 보장
-        if (this._scheduler && this._scheduler._jobs.length > 0 && !cluster.isWorker) {
+        // cluster.isPrimary로 단일 프로세스 보장 — multi-worker 차원 보호.
+        // 추가로 redis leader election (Scheduler.connect) 가 multi-server 차원 보호.
+        // app.scheduler.enabled=false 면 전체 스킵.
+        if (this._scheduler && this._scheduler._jobs.length > 0
+            && !cluster.isWorker && this._schedulerEnabled !== false) {
             this._scheduler.start();
         }
 
@@ -1493,7 +1538,7 @@ export default class Application {
             await this.emit('shutting-down', { signal });
 
             // 1. 스케줄러 정지 (04-bootstrap-lifecycle.md)
-            if (this._scheduler) this._scheduler.stop();
+            if (this._scheduler) await this._scheduler.stop();
 
             // 2. 큐 drain — 처리 중 Task 완료 대기 (doc 04 순서 3)
             if (this._queue && this._queue.pending > 0) {

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));
+        }
+    }
+}

package/lib/schedule/drivers/RedisQueueDriver.js

@@ -0,0 +1,285 @@
+/**
+ * RedisQueueDriver — Redis 기반 Task 큐 드라이버
+ *
+ * ioredis 를 사용한 영구 큐. 멀티워커/재시작 안전.
+ *
+ * 자료구조 (prefix 기본 'fuzionx:queue'):
+ *   {prefix}:{queueName}:pending      ─ List (LPUSH/BRPOP) — 즉시 처리 대기열
+ *   {prefix}:{queueName}:scheduled    ─ Sorted Set (ZADD score=executeAtMs) — retry 지연 큐
+ *   {prefix}:{queueName}:dead         ─ List (LPUSH) — 최종 실패 (dead-letter)
+ *   {prefix}:{queueName}:processing   ─ List (RPOPLPUSH 으로 atomic 이동) — 처리 중 (crash 시 복구용, optional)
+ *
+ * 워커 흐름:
+ *   1. BRPOP pending (blocking, timeout 5s)
+ *   2. Task.handle(data) 실행 (TaskClass.timeout 안)
+ *   3. 성공 → 완료
+ *   4. 실패 → retries 미만이면 ZADD scheduled (executeAt = now + retryDelay)
+ *           → 도달 시 별도 promoter loop 가 ZRANGEBYSCORE 로 추출 후 LPUSH pending
+ *   5. 최종 실패 → LPUSH dead + Task.failed() 호출
+ *
+ * 클라이언트 분리:
+ *   - this._client: 일반 명령 (LPUSH/ZADD/...)
+ *   - this._blockingClient: BRPOP 전용 (blocking 명령이 일반 명령 차단 회피)
+ *
+ * @see lib/schedule/Queue.js
+ * @see lib/schedule/drivers/MemoryQueueDriver.js
+ */
+export default class RedisQueueDriver {
+    /**
+     * @param {import('../../core/Application.js').default} app
+     * @param {object} opts
+     * @param {string} opts.url - Redis 접속 URL
+     * @param {string} [opts.prefix='fuzionx:queue'] - 키 접두사
+     * @param {number} [opts.brpopTimeoutSec=5] - BRPOP timeout (초) — 짧을수록 graceful shutdown 빠름
+     * @param {number} [opts.promoterIntervalMs=1000] - scheduled → pending 승격 검사 주기
+     */
+    constructor(app, opts = {}) {
+        this.app = app;
+        this._url = opts.url || 'redis://localhost:6379';
+        this._prefix = opts.prefix || 'fuzionx:queue';
+        this._brpopTimeoutSec = opts.brpopTimeoutSec ?? 5;
+        this._promoterIntervalMs = opts.promoterIntervalMs ?? 1000;
+
+        /** @type {Map<string, typeof import('../Task.js').default>} */
+        this._tasks = new Map();
+
+        /** @type {import('ioredis').default | null} 일반 명령용 */
+        this._client = null;
+
+        /** @type {import('ioredis').default | null} BRPOP blocking 용 (별도 connection) */
+        this._blockingClient = null;
+
+        /** @type {Set<string>} 활성 워커가 폴링 중인 큐 이름들 */
+        this._activeQueues = new Set();
+
+        /** @type {boolean} stop() 호출 후 워커 종료 신호 */
+        this._stopping = false;
+
+        /** @type {NodeJS.Timeout|null} scheduled → pending 승격 timer */
+        this._promoterTimer = null;
+    }
+
+    /** 큐 키 helper */
+    _k(queue, suffix) { return `${this._prefix}:${queue}:${suffix}`; }
+
+    /**
+     * 드라이버 초기화 — ioredis 연결 + 승격 worker 시작.
+     *
+     * @returns {Promise<void>}
+     */
+    async start() {
+        const { default: Redis } = await import('ioredis');
+        const redisOpts = {
+            maxRetriesPerRequest: null,    // blocking 명령 BRPOP 위해 null 필수
+            retryStrategy: (times) => {
+                if (times > 10) return null;
+                return Math.min(times * 200, 2000);
+            },
+            lazyConnect: false,
+        };
+        this._client = new Redis(this._url, redisOpts);
+        this._blockingClient = new Redis(this._url, redisOpts);
+
+        const onErr = (label) => (err) =>
+            this.app?.logger?.error?.(`[Queue:Redis:${label}] ${err.message}`);
+        this._client.on('error', onErr('cmd'));
+        this._blockingClient.on('error', onErr('blocking'));
+
+        // scheduled → pending 승격 loop
+        this._startPromoter();
+    }
+
+    /**
+     * Task 클래스 등록 + 해당 큐의 BRPOP worker 시작.
+     *
+     * @param {string} name - Task 이름
+     * @param {typeof import('../Task.js').default} TaskClass
+     */
+    register(name, TaskClass) {
+        this._tasks.set(name, TaskClass);
+        const queue = TaskClass.queue || 'default';
+        if (!this._activeQueues.has(queue)) {
+            this._activeQueues.add(queue);
+            this._startWorker(queue);
+        }
+    }
+
+    /**
+     * Task 디스패치 — pending 큐에 LPUSH.
+     *
+     * @param {string|Function} taskOrName
+     * @param {object} data
+     * @param {object} [opts]
+     */
+    dispatch(taskOrName, data, opts = {}) {
+        const name = typeof taskOrName === 'string' ? taskOrName : taskOrName.name;
+        const TaskClass = this._tasks.get(name);
+        if (!TaskClass) {
+            this.app?.logger?.error?.(`[Queue:Redis] Task '${name}' not registered`);
+            return;
+        }
+        const queue = TaskClass.queue || 'default';
+        const job = { name, data, opts, retries: 0, enqueued_at: Date.now() };
+        // LPUSH (FIFO 위해 worker 는 BRPOP — 오른쪽에서 pop)
+        this._client.lpush(this._k(queue, 'pending'), JSON.stringify(job))
+            .catch(err => this.app?.logger?.error?.(`[Queue:Redis] dispatch failed: ${err.message}`));
+    }
+
+    /**
+     * 큐별 BRPOP worker loop.
+     *
+     * @param {string} queue
+     * @private
+     */
+    async _startWorker(queue) {
+        const pendingKey = this._k(queue, 'pending');
+        const deadKey    = this._k(queue, 'dead');
+
+        while (!this._stopping) {
+            let result;
+            try {
+                // BRPOP returns [key, value] or null on timeout
+                result = await this._blockingClient.brpop(pendingKey, this._brpopTimeoutSec);
+            } catch (err) {
+                if (this._stopping) break;
+                this.app?.logger?.error?.(`[Queue:Redis] BRPOP error on '${queue}': ${err.message}`);
+                await new Promise(r => setTimeout(r, 1000));
+                continue;
+            }
+            if (!result) continue;   // timeout — 다시 BRPOP
+
+            let job;
+            try { job = JSON.parse(result[1]); }
+            catch (err) {
+                this.app?.logger?.error?.(`[Queue:Redis] bad job JSON: ${err.message}`);
+                continue;
+            }
+
+            const TaskClass = this._tasks.get(job.name);
+            if (!TaskClass) {
+                this.app?.logger?.error?.(`[Queue:Redis] Task '${job.name}' not registered (queue=${queue})`);
+                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 = (job.retries || 0) + 1;
+                if (job.retries < (TaskClass.retries || 3)) {
+                    // 지수 백오프 또는 fixed — Task 가 지정한 retryDelay 사용 + backoff factor 2x
+                    const baseDelay = TaskClass.retryDelay || 1000;
+                    const delay = baseDelay * Math.pow(2, job.retries - 1);
+                    const executeAt = Date.now() + delay;
+                    job.last_error = String(err?.message || err);
+                    await this._client.zadd(
+                        this._k(queue, 'scheduled'),
+                        executeAt,
+                        JSON.stringify(job),
+                    ).catch(e => this.app?.logger?.error?.(`[Queue:Redis] zadd failed: ${e.message}`));
+                } else {
+                    // dead-letter
+                    job.last_error = String(err?.message || err);
+                    job.dead_at = Date.now();
+                    await this._client.lpush(deadKey, JSON.stringify(job))
+                        .catch(e => this.app?.logger?.error?.(`[Queue:Redis] dead push failed: ${e.message}`));
+                    try { await task.failed(job.data, err); } catch {}
+                }
+            }
+        }
+    }
+
+    /**
+     * scheduled → pending 승격 loop.
+     * ZRANGEBYSCORE 로 due-time 도달한 job 추출 후 LPUSH pending.
+     *
+     * @private
+     */
+    _startPromoter() {
+        const tick = async () => {
+            if (this._stopping) return;
+            try {
+                for (const queue of this._activeQueues) {
+                    const schedKey   = this._k(queue, 'scheduled');
+                    const pendingKey = this._k(queue, 'pending');
+                    const now = Date.now();
+
+                    // ZRANGEBYSCORE -inf now LIMIT 0 100
+                    const dueJobs = await this._client.zrangebyscore(schedKey, '-inf', now, 'LIMIT', 0, 100);
+                    if (dueJobs.length === 0) continue;
+
+                    // pipeline: ZREM + LPUSH atomic 묶음
+                    const pipe = this._client.pipeline();
+                    for (const raw of dueJobs) {
+                        pipe.zrem(schedKey, raw);
+                        pipe.lpush(pendingKey, raw);
+                    }
+                    await pipe.exec();
+                }
+            } catch (err) {
+                this.app?.logger?.error?.(`[Queue:Redis] promoter error: ${err.message}`);
+            }
+        };
+        this._promoterTimer = setInterval(tick, this._promoterIntervalMs);
+        // unref — 프로세스 종료를 막지 않음
+        if (this._promoterTimer.unref) this._promoterTimer.unref();
+    }
+
+    /**
+     * 대기 중 작업 수 (모든 활성 큐 합계).
+     * 비동기지만 동기 getter 형태 유지 위해 캐시 X — 정확한 수는 pendingAsync() 사용.
+     *
+     * @returns {number} 0 (sync 정확값 미지원 — Application 의 graceful drain 용)
+     */
+    get pending() {
+        return 0;
+    }
+
+    /**
+     * 정확한 pending 수 (모든 큐 합계).
+     *
+     * @returns {Promise<number>}
+     */
+    async pendingAsync() {
+        let total = 0;
+        for (const queue of this._activeQueues) {
+            const len = await this._client.llen(this._k(queue, 'pending'));
+            total += len;
+        }
+        return total;
+    }
+
+    /**
+     * graceful shutdown.
+     * 1. _stopping 신호 → worker loop 종료
+     * 2. blocking client 강제 종료 (BRPOP 대기 중인 client 깨움)
+     * 3. promoter timer clear
+     * 4. 연결 종료
+     *
+     * @param {number} [timeoutMs=10000]
+     */
+    async stop(timeoutMs = 10000) {
+        this._stopping = true;
+        if (this._promoterTimer) {
+            clearInterval(this._promoterTimer);
+            this._promoterTimer = null;
+        }
+        try {
+            // disconnect 로 BRPOP 깨워 worker loop 종료 유도
+            if (this._blockingClient) this._blockingClient.disconnect();
+        } catch {}
+        try {
+            if (this._client) await this._client.quit();
+        } catch {}
+        this._client = null;
+        this._blockingClient = null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.76",
+  "version": "0.1.77",
   "type": "module",
   "description": "Full-stack MVC framework built on @fuzionx/core — Controller, Service, Model, Middleware, DI, EventBus",
   "main": "index.js",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1028.0",
-    "@fuzionx/core": "^0.1.76",
+    "@fuzionx/core": "^0.1.77",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",