@fuzionx/framework 0.1.76 → 0.1.78

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.78",
     "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/database/MongoModel.js

@@ -110,63 +110,60 @@ export default class MongoModel extends Model {
 
     /**
      * 레코드 생성
+     *
+     * 실패 시 예외 throw — silent stub 반환 X.
+     * 응용이 "INSERT 성공한 줄 알고" 진행하는 디버깅 지옥 차단.
      * @param {object} data
      * @returns {Promise<MongoModel>}
+     * @throws {Error} mongoose 미설치 / 연결 실패 / 검증 실패 / 키 충돌 등
      */
     static async create(data) {
-        try {
-            const MongooseModel = this._getMongooseModel();
-            const doc = await MongooseModel.create(data);
-            return new this(doc.toObject());
-        } catch {
-            // Mongoose 미설치 → stub
-            return new this({ ...data, _id: Date.now().toString(36) });
-        }
+        const MongooseModel = this._getMongooseModel();
+        const doc = await MongooseModel.create(data);
+        return new this(doc.toObject());
     }
 
     /**
      * ID로 조회
+     *
+     * 레코드가 실제로 없으면 null 반환. 연결/쿼리 오류는 throw — silent null 반환 X.
+     * "USER_NOT_FOUND" 가 실제로 미존재인지 연결 장애인지 구분 가능.
      * @param {*} id
      * @returns {Promise<MongoModel|null>}
+     * @throws {Error} mongoose 미설치 / 연결 실패 / 쿼리 오류 등
      */
     static async find(id) {
-        try {
-            const MongooseModel = this._getMongooseModel();
-            const doc = await MongooseModel.findById(id);
-            return doc ? new this(doc.toObject()) : null;
-        } catch {
-            return null;
-        }
+        const MongooseModel = this._getMongooseModel();
+        const doc = await MongooseModel.findById(id);
+        return doc ? new this(doc.toObject()) : null;
     }
 
     /**
      * 전체 조회
+     *
+     * 결과 없으면 빈 배열 반환. 연결/쿼리 오류는 throw — silent [] 반환 X.
      * @returns {Promise<Array>}
+     * @throws {Error} mongoose 미설치 / 연결 실패 / 쿼리 오류 등
      */
     static async all() {
-        try {
-            const MongooseModel = this._getMongooseModel();
-            const docs = await MongooseModel.find({});
-            return docs.map(d => new this(d.toObject()));
-        } catch {
-            return [];
-        }
+        const MongooseModel = this._getMongooseModel();
+        const docs = await MongooseModel.find({});
+        return docs.map(d => new this(d.toObject()));
     }
 
     static async findAll() { return this.all(); }
 
     /**
      * Raw aggregation pipeline
+     *
+     * 파이프라인 실행 결과 반환. 오류 시 throw — silent [] 반환 X.
      * @param {Array} pipeline
      * @returns {Promise<Array>}
+     * @throws {Error} mongoose 미설치 / 연결 실패 / 파이프라인 오류 등
      */
     static async raw(pipeline) {
-        try {
-            const MongooseModel = this._getMongooseModel();
-            return MongooseModel.aggregate(pipeline);
-        } catch {
-            return [];
-        }
+        const MongooseModel = this._getMongooseModel();
+        return MongooseModel.aggregate(pipeline);
     }
 
     /**
@@ -185,8 +182,13 @@ export default class MongoModel extends Model {
 
     /**
      * 인스턴스 수정
+     *
+     * `_id` 가 없으면 no-op (메모리만 갱신). DB 수정 실패 시 throw —
+     * silent swallow 안 함. 응용이 "DB 저장됐다고 착각하는" 케이스 차단.
+     *
      * @param {object} data
      * @returns {Promise<this>}
+     * @throws {Error} mongoose 미설치 / 연결 실패 / 검증 실패 등
      */
     async update(data) {
         Object.assign(this._attributes, data);
@@ -195,16 +197,13 @@ export default class MongoModel extends Model {
         const id = this._attributes._id || this._attributes[this.constructor.primaryKey];
         if (!id) return this;
 
-        try {
-            const MongooseModel = this.constructor._getMongooseModel();
-            await MongooseModel.updateOne({ _id: id }, { $set: data });
-        } catch {}
-
+        const MongooseModel = this.constructor._getMongooseModel();
+        await MongooseModel.updateOne({ _id: id }, { $set: data });
         return this;
     }
 
     /**
-     * 삭제
+     * 삭제 (soft delete 지원)
      */
     async delete() {
         if (this.constructor.softDelete) {
@@ -219,14 +218,16 @@ export default class MongoModel extends Model {
 
     /**
      * 실제 삭제
+     *
+     * `_id` 없으면 no-op. DB 삭제 오류 시 throw — silent swallow X.
+     *
+     * @throws {Error} mongoose 미설치 / 연결 실패 / 권한 오류 등
      */
     async forceDelete() {
         const id = this._attributes._id || this._attributes[this.constructor.primaryKey];
         if (!id) return;
 
-        try {
-            const MongooseModel = this.constructor._getMongooseModel();
-            await MongooseModel.deleteOne({ _id: id });
-        } catch {}
+        const MongooseModel = this.constructor._getMongooseModel();
+        await MongooseModel.deleteOne({ _id: id });
     }
 }

package/lib/database/SqlQueryBuilder.js

@@ -29,7 +29,12 @@ export default class SqlQueryBuilder extends QueryBuilder {
 
     /**
      * 결과 조회 — SQL SELECT 실행
+     *
+     * 지원 driver (sqlite/knex) 매칭 안 되거나 conn.db 비어 있으면 throw —
+     * silent [] 반환 X. driver 미지원/연결 미수립을 빈 결과로 착각하지 않게.
+     *
      * @returns {Promise<Array<import('./Model.js').default>>}
+     * @throws {Error} 지원 driver 없음 / 연결 미수립
      */
     async get() {
         const conn = this._model.getConnection();
@@ -40,7 +45,9 @@ export default class SqlQueryBuilder extends QueryBuilder {
         } else if (conn.type === 'knex' && conn.db) {
             results = await this._executeKnex(conn.db, 'select');
         } else {
-            results = [];
+            throw new Error(
+                `[SqlQueryBuilder.get] '${this._model.table}' — unsupported driver or no connection (conn.type=${conn?.type}, conn.db=${!!conn?.db})`,
+            );
         }
 
         // eager-loading — with()로 지정된 관계 로드
@@ -63,7 +70,11 @@ export default class SqlQueryBuilder extends QueryBuilder {
 
     /**
      * 카운트
+     *
+     * 지원 driver 매칭 안 되면 throw — silent 0 반환 X.
+     *
      * @returns {Promise<number>}
+     * @throws {Error} 지원 driver 없음 / 연결 미수립
      */
     async count() {
         const conn = this._model.getConnection();
@@ -83,7 +94,9 @@ export default class SqlQueryBuilder extends QueryBuilder {
             return Number(cnt);
         }
 
-        return 0;
+        throw new Error(
+            `[SqlQueryBuilder.count] '${this._model.table}' — unsupported driver or no connection (conn.type=${conn?.type}, conn.db=${!!conn?.db})`,
+        );
     }
 
     /**
@@ -115,12 +128,18 @@ export default class SqlQueryBuilder extends QueryBuilder {
             return query.update(data);
         }
 
-        return 0;
+        throw new Error(
+            `[SqlQueryBuilder.update] '${this._model.table}' — unsupported driver or no connection (conn.type=${conn?.type}, conn.db=${!!conn?.db})`,
+        );
     }
 
     /**
      * 조건부 삭제
+     *
+     * 지원 driver 매칭 안 되면 throw — silent 0 반환 X.
+     *
      * @returns {Promise<number>}
+     * @throws {Error} 지원 driver 없음 / 연결 미수립
      */
     async delete() {
         const conn = this._model.getConnection();
@@ -148,7 +167,9 @@ export default class SqlQueryBuilder extends QueryBuilder {
             return query.delete();
         }
 
-        return 0;
+        throw new Error(
+            `[SqlQueryBuilder.delete] '${this._model.table}' — unsupported driver or no connection (conn.type=${conn?.type}, conn.db=${!!conn?.db})`,
+        );
     }
 
     /**

package/lib/helpers/FileHelper.js

@@ -39,9 +39,25 @@ export default class FileHelper {
         return stat.size;
     }
 
+    /**
+     * 파일 존재 여부.
+     *
+     * ENOENT (파일 없음) 만 false 반환. 권한 오류(EACCES) / 심볼 무한 루프(ELOOP) /
+     * IO 오류 등은 throw — silent false 로 가리지 않음.
+     *
+     * @param {string} filePath
+     * @returns {Promise<boolean>}
+     * @throws {Error} ENOENT 외의 fs 오류
+     */
     async exists(filePath) {
         if (this._bridge?.fileExists) return this._bridge.fileExists(filePath);
-        try { await fs.access(filePath); return true; } catch { return false; }
+        try {
+            await fs.access(filePath);
+            return true;
+        } catch (err) {
+            if (err && err.code === 'ENOENT') return false;
+            throw err;
+        }
     }
 
     async remove(filePath) {

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,146 @@
+/**
+ * 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 {
+                    // Task.failed 콜백 자체가 실패해도 워커 루프는 멈추면 안 됨 (fire-and-forget).
+                    // 단 silent 하지 않게 logger.warn 으로 노출 — 디버깅 가능.
+                    try { await task.failed(job.data, err); }
+                    catch (failedErr) {
+                        const log = this.app?.logger || console;
+                        log.warn?.(
+                            `[MemoryQueueDriver] ${TaskClass.name || 'Task'}.failed() callback threw — ` +
+                            `original error: ${err?.message || err}; failed-callback error: ${failedErr?.message || failedErr}`,
+                        );
+                    }
+                }
+            }
+        }
+
+        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,294 @@
+/**
+ * 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}`));
+                    // Task.failed 콜백 자체가 실패해도 워커 루프 유지 (fire-and-forget),
+                    // 단 silent 하지 않게 logger.warn 으로 노출.
+                    try { await task.failed(job.data, err); }
+                    catch (failedErr) {
+                        const log = this.app?.logger || console;
+                        log.warn?.(
+                            `[RedisQueueDriver] ${TaskClass.name || 'Task'}.failed() callback threw — ` +
+                            `original error: ${err?.message || err}; failed-callback error: ${failedErr?.message || failedErr}`,
+                        );
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * 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/Storage.js

@@ -117,19 +117,25 @@ export default class Storage {
     }
 
     /**
-     * 파일 존재 여부
+     * 파일 존재 여부.
+     *
+     * ENOENT (파일 없음) 만 false 반환. 권한 오류 / IO 오류 / S3 인증 오류 등은
+     * throw — silent false 로 가리지 않음.
+     *
      * @param {string} filePath
      * @returns {Promise<boolean>}
+     * @throws {Error} ENOENT 외의 fs/S3 오류
      */
     async exists(filePath) {
+        if (this.driver === 's3') {
+            return this._s3Exists(filePath);
+        }
         try {
-            if (this.driver === 's3') {
-                return this._s3Exists(filePath);
-            }
             await fs.access(path.join(this.basePath, filePath));
             return true;
-        } catch {
-            return false;
+        } catch (err) {
+            if (err && err.code === 'ENOENT') return false;
+            throw err;
         }
     }
 

package/package.json

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