@fuzionx/framework 0.1.75 → 0.1.77

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/lib/services/Service.js

@@ -8,7 +8,6 @@
  * @see docs/framework/class-design.mm.md (Service)
  */
 import Base from '../core/Base.js';
-import { ServiceError } from '../core/AppError.js';
 
 /** @type {Map<string, { value: *, expires: number }>} 전역 캐시 스토어 */
 const _cache = new Map();
@@ -141,6 +140,28 @@ export default class Service extends Base {
         return cached ? cached.expires > Date.now() : false;
     }
 
+    /**
+     * 접두어 기반 캐시 일괄 무효화
+     *
+     * prefix로 시작하는 모든 캐시 키를 삭제한다.
+     * 예: 'reseller:tree:' → 'reseller:tree:roots', 'reseller:tree:full', 'reseller:tree:children:5' 등 모두 삭제
+     *
+     * @param {string} prefix - 캐시 키 접두어
+     */
+    async invalidateCacheByPrefix(prefix) {
+        // 인메모리 Map — prefix로 시작하는 키 일괄 삭제
+        for (const key of _cache.keys()) {
+            if (key.startsWith(prefix)) {
+                _cache.delete(key);
+            }
+        }
+
+        // CacheManager — deleteByPrefix 지원 시 위임
+        if (this.cache && typeof this.cache.deleteByPrefix === 'function') {
+            await this.cache.deleteByPrefix(prefix);
+        }
+    }
+
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     //  병렬 실행
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -257,19 +278,6 @@ export default class Service extends Base {
         }
     }
 
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  에러
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 에러 생성 헬퍼
-     * @param {string} message
-     * @param {number} [status=400]
-     * @returns {ServiceError}
-     */
-    error(message, status = 400) {
-        return new ServiceError(message, status);
-    }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.75",
+  "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.75",
+    "@fuzionx/core": "^0.1.77",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",