@fuzionx/framework 0.1.43 → 0.1.44

package/lib/schedule/Queue.js

@@ -1,103 +1,103 @@
-/**
- * Queue — Task 큐 관리 (Memory/Redis)
- *
- * AutoLoader가 shared/jobs/ 에서 Task 클래스를 자동 스캔·등록.
- * handle(data)은 메인 스레드에서 실행되므로 this.db, this.service() 등
- * 앱 컨텍스트에 접근 가능합니다.
- *
- * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
- *
- * @see docs/framework/10-scheduler-queue.md
- * @see lib/schedule/WorkerPool.js
- */
-export default class Queue {
-    /**
-     * @param {import('../core/Application.js').default} app
-     * @param {object} [opts]
-     * @param {string} [opts.driver='memory'] - 'memory' | 'redis'
-     */
-    constructor(app, opts = {}) {
-        this.app = app;
-        this.driver = opts.driver || 'memory';
-        this._tasks = new Map();  // name → TaskClass
-        this._queue = [];
-        this._processing = false;
-    }
-
-    /**
-     * Task 클래스 등록
-     * @param {string} name
-     * @param {typeof import('./Task.js').default} TaskClass
-     */
-    register(name, TaskClass) {
-        this._tasks.set(name, TaskClass);
-    }
-
-    /**
-     * Task 디스패치 (큐에 추가)
-     * @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();
-        }
-    }
-
-    /**
-     * 큐 처리 루프
-     * @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;
-    }
-
-    /**
-     * 남은 큐 수
-     * @returns {number}
-     */
-    get pending() {
-        return this._queue.length;
-    }
-}
+/**
+ * Queue — Task 큐 관리 (Memory/Redis)
+ *
+ * AutoLoader가 shared/jobs/ 에서 Task 클래스를 자동 스캔·등록.
+ * handle(data)은 메인 스레드에서 실행되므로 this.db, this.service() 등
+ * 앱 컨텍스트에 접근 가능합니다.
+ *
+ * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
+ *
+ * @see docs/framework/10-scheduler-queue.md
+ * @see lib/schedule/WorkerPool.js
+ */
+export default class Queue {
+    /**
+     * @param {import('../core/Application.js').default} app
+     * @param {object} [opts]
+     * @param {string} [opts.driver='memory'] - 'memory' | 'redis'
+     */
+    constructor(app, opts = {}) {
+        this.app = app;
+        this.driver = opts.driver || 'memory';
+        this._tasks = new Map();  // name → TaskClass
+        this._queue = [];
+        this._processing = false;
+    }
+
+    /**
+     * Task 클래스 등록
+     * @param {string} name
+     * @param {typeof import('./Task.js').default} TaskClass
+     */
+    register(name, TaskClass) {
+        this._tasks.set(name, TaskClass);
+    }
+
+    /**
+     * Task 디스패치 (큐에 추가)
+     * @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();
+        }
+    }
+
+    /**
+     * 큐 처리 루프
+     * @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;
+    }
+
+    /**
+     * 남은 큐 수
+     * @returns {number}
+     */
+    get pending() {
+        return this._queue.length;
+    }
+}

package/lib/schedule/Scheduler.js

@@ -1,171 +1,171 @@
-/**
- * Scheduler — 정기 실행 작업 관리 (cron 스케줄)
- *
- * AutoLoader가 shared/jobs/ 에서 Job 클래스를 자동 스캔·등록.
- * handle()은 메인 스레드에서 실행되므로 this.db, this.service() 등
- * 앱 컨텍스트에 접근 가능합니다.
- *
- * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
- *
- * @see docs/framework/10-scheduler-queue.md
- * @see lib/schedule/WorkerPool.js
- */
-export default class Scheduler {
-    /**
-     * @param {import('../core/Application.js').default} app
-     */
-    constructor(app) {
-        this.app = app;
-        /** @type {Array<{JobClass: typeof import('./Job.js').default}>} */
-        this._jobs = [];
-        /** @type {Array<NodeJS.Timeout>} */
-        this._timers = [];
-    }
-
-    /**
-     * Job 클래스 등록 (AutoLoader에서 호출)
-     * @param {typeof import('./Job.js').default} JobClass
-     */
-    register(JobClass) {
-        if (!JobClass.schedule) return;
-        if (JobClass.enabled === false) return;
-        this._jobs.push({ JobClass });
-    }
-
-    /**
-     * 등록된 모든 Job 시작
-     */
-    start() {
-        for (const { JobClass } of this._jobs) {
-            const interval = this._parseSchedule(JobClass.schedule);
-            if (!interval) {
-                this.app?.logger?.warn?.(`[Scheduler] Invalid schedule: ${JobClass.name} → '${JobClass.schedule}'`);
-                continue;
-            }
-
-            const timeout = JobClass.timeout || 30000;
-
-            const runJob = async () => {
-                const job = new JobClass(this.app);
-                try {
-                    let timer;
-                    await Promise.race([
-                        job.handle().finally(() => clearTimeout(timer)),
-                        new Promise((_, reject) => {
-                            timer = setTimeout(() => reject(new Error(`Job timeout (${timeout}ms)`)), timeout);
-                        }),
-                    ]);
-                } catch (err) {
-                    if (typeof job.onError === 'function') {
-                        try { await job.onError(err); } catch {}
-                    } else {
-                        this.app?.logger?.error?.(`[Scheduler] ${JobClass.name} failed: ${err.message}`);
-                    }
-                }
-            };
-
-            // daily/weekly → 첫 실행까지 지연 계산
-            const initialDelay = this._calcInitialDelay(JobClass.schedule);
-            if (initialDelay > 0) {
-                const delayed = setTimeout(() => {
-                    runJob();
-                    const timer = setInterval(runJob, interval);
-                    this._timers.push(timer);
-                }, initialDelay);
-                this._timers.push(delayed);
-            } else {
-                const timer = setInterval(runJob, interval);
-                this._timers.push(timer);
-                // 즉시 첫 실행
-                runJob();
-            }
-
-            this.app?.logger?.info?.(
-                `[Scheduler] ${JobClass.name} registered (${JobClass.schedule}, interval=${interval}ms)`
-            );
-        }
-    }
-
-    /**
-     * 모든 타이머 정지
-     */
-    stop() {
-        for (const timer of this._timers) {
-            clearInterval(timer);
-            clearTimeout(timer);
-        }
-        this._timers = [];
-    }
-
-    // ── Schedule 파싱 ──
-
-    /**
-     * 간편 스케줄 → ms 변환
-     *
-     * 지원 포맷:
-     *   'every:5s'  → 5000ms
-     *   'every:5m'  → 300000ms
-     *   'every:1h'  → 3600000ms
-     *   'daily:HH:MM'      → 24h (첫 실행은 _calcInitialDelay)
-     *   'weekly:DAY:HH:MM' → 7d  (첫 실행은 _calcInitialDelay)
-     */
-    _parseSchedule(schedule) {
-        if (!schedule) return null;
-
-        // every:Ns/Nm/Nh
-        const everyMatch = schedule.match(/^every:(\d+)(s|m|h)$/i);
-        if (everyMatch) {
-            const val = parseInt(everyMatch[1], 10);
-            const unit = everyMatch[2].toLowerCase();
-            if (unit === 's') return val * 1000;
-            if (unit === 'm') return val * 60000;
-            if (unit === 'h') return val * 3600000;
-        }
-
-        // daily:HH:MM → 24시간 간격
-        if (/^daily:\d{2}:\d{2}$/.test(schedule)) {
-            return 24 * 60 * 60 * 1000;
-        }
-
-        // weekly:DAY:HH:MM → 7일 간격
-        if (/^weekly:\w+:\d{2}:\d{2}$/.test(schedule)) {
-            return 7 * 24 * 60 * 60 * 1000;
-        }
-
-        return null;
-    }
-
-    /**
-     * daily/weekly 스케줄의 첫 실행 지연시간 계산
-     */
-    _calcInitialDelay(schedule) {
-        const now = new Date();
-
-        // daily:HH:MM
-        const dailyMatch = schedule.match(/^daily:(\d{2}):(\d{2})$/);
-        if (dailyMatch) {
-            const target = new Date(now);
-            target.setHours(parseInt(dailyMatch[1], 10), parseInt(dailyMatch[2], 10), 0, 0);
-            if (target <= now) target.setDate(target.getDate() + 1);
-            return target - now;
-        }
-
-        // weekly:DAY:HH:MM
-        const weeklyMatch = schedule.match(/^weekly:(\w+):(\d{2}):(\d{2})$/);
-        if (weeklyMatch) {
-            const days = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
-            const targetDay = days[weeklyMatch[1].toLowerCase()];
-            if (targetDay === undefined) return 0;
-
-            const target = new Date(now);
-            target.setHours(parseInt(weeklyMatch[2], 10), parseInt(weeklyMatch[3], 10), 0, 0);
-
-            let diff = targetDay - now.getDay();
-            if (diff < 0 || (diff === 0 && target <= now)) diff += 7;
-            target.setDate(target.getDate() + diff);
-            return target - now;
-        }
-
-        return 0; // every:* → 즉시 시작
-    }
-}
+/**
+ * Scheduler — 정기 실행 작업 관리 (cron 스케줄)
+ *
+ * AutoLoader가 shared/jobs/ 에서 Job 클래스를 자동 스캔·등록.
+ * handle()은 메인 스레드에서 실행되므로 this.db, this.service() 등
+ * 앱 컨텍스트에 접근 가능합니다.
+ *
+ * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
+ *
+ * @see docs/framework/10-scheduler-queue.md
+ * @see lib/schedule/WorkerPool.js
+ */
+export default class Scheduler {
+    /**
+     * @param {import('../core/Application.js').default} app
+     */
+    constructor(app) {
+        this.app = app;
+        /** @type {Array<{JobClass: typeof import('./Job.js').default}>} */
+        this._jobs = [];
+        /** @type {Array<NodeJS.Timeout>} */
+        this._timers = [];
+    }
+
+    /**
+     * Job 클래스 등록 (AutoLoader에서 호출)
+     * @param {typeof import('./Job.js').default} JobClass
+     */
+    register(JobClass) {
+        if (!JobClass.schedule) return;
+        if (JobClass.enabled === false) return;
+        this._jobs.push({ JobClass });
+    }
+
+    /**
+     * 등록된 모든 Job 시작
+     */
+    start() {
+        for (const { JobClass } of this._jobs) {
+            const interval = this._parseSchedule(JobClass.schedule);
+            if (!interval) {
+                this.app?.logger?.warn?.(`[Scheduler] Invalid schedule: ${JobClass.name} → '${JobClass.schedule}'`);
+                continue;
+            }
+
+            const timeout = JobClass.timeout || 30000;
+
+            const runJob = async () => {
+                const job = new JobClass(this.app);
+                try {
+                    let timer;
+                    await Promise.race([
+                        job.handle().finally(() => clearTimeout(timer)),
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => reject(new Error(`Job timeout (${timeout}ms)`)), timeout);
+                        }),
+                    ]);
+                } catch (err) {
+                    if (typeof job.onError === 'function') {
+                        try { await job.onError(err); } catch {}
+                    } else {
+                        this.app?.logger?.error?.(`[Scheduler] ${JobClass.name} failed: ${err.message}`);
+                    }
+                }
+            };
+
+            // daily/weekly → 첫 실행까지 지연 계산
+            const initialDelay = this._calcInitialDelay(JobClass.schedule);
+            if (initialDelay > 0) {
+                const delayed = setTimeout(() => {
+                    runJob();
+                    const timer = setInterval(runJob, interval);
+                    this._timers.push(timer);
+                }, initialDelay);
+                this._timers.push(delayed);
+            } else {
+                const timer = setInterval(runJob, interval);
+                this._timers.push(timer);
+                // 즉시 첫 실행
+                runJob();
+            }
+
+            this.app?.logger?.info?.(
+                `[Scheduler] ${JobClass.name} registered (${JobClass.schedule}, interval=${interval}ms)`
+            );
+        }
+    }
+
+    /**
+     * 모든 타이머 정지
+     */
+    stop() {
+        for (const timer of this._timers) {
+            clearInterval(timer);
+            clearTimeout(timer);
+        }
+        this._timers = [];
+    }
+
+    // ── Schedule 파싱 ──
+
+    /**
+     * 간편 스케줄 → ms 변환
+     *
+     * 지원 포맷:
+     *   'every:5s'  → 5000ms
+     *   'every:5m'  → 300000ms
+     *   'every:1h'  → 3600000ms
+     *   'daily:HH:MM'      → 24h (첫 실행은 _calcInitialDelay)
+     *   'weekly:DAY:HH:MM' → 7d  (첫 실행은 _calcInitialDelay)
+     */
+    _parseSchedule(schedule) {
+        if (!schedule) return null;
+
+        // every:Ns/Nm/Nh
+        const everyMatch = schedule.match(/^every:(\d+)(s|m|h)$/i);
+        if (everyMatch) {
+            const val = parseInt(everyMatch[1], 10);
+            const unit = everyMatch[2].toLowerCase();
+            if (unit === 's') return val * 1000;
+            if (unit === 'm') return val * 60000;
+            if (unit === 'h') return val * 3600000;
+        }
+
+        // daily:HH:MM → 24시간 간격
+        if (/^daily:\d{2}:\d{2}$/.test(schedule)) {
+            return 24 * 60 * 60 * 1000;
+        }
+
+        // weekly:DAY:HH:MM → 7일 간격
+        if (/^weekly:\w+:\d{2}:\d{2}$/.test(schedule)) {
+            return 7 * 24 * 60 * 60 * 1000;
+        }
+
+        return null;
+    }
+
+    /**
+     * daily/weekly 스케줄의 첫 실행 지연시간 계산
+     */
+    _calcInitialDelay(schedule) {
+        const now = new Date();
+
+        // daily:HH:MM
+        const dailyMatch = schedule.match(/^daily:(\d{2}):(\d{2})$/);
+        if (dailyMatch) {
+            const target = new Date(now);
+            target.setHours(parseInt(dailyMatch[1], 10), parseInt(dailyMatch[2], 10), 0, 0);
+            if (target <= now) target.setDate(target.getDate() + 1);
+            return target - now;
+        }
+
+        // weekly:DAY:HH:MM
+        const weeklyMatch = schedule.match(/^weekly:(\w+):(\d{2}):(\d{2})$/);
+        if (weeklyMatch) {
+            const days = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+            const targetDay = days[weeklyMatch[1].toLowerCase()];
+            if (targetDay === undefined) return 0;
+
+            const target = new Date(now);
+            target.setHours(parseInt(weeklyMatch[2], 10), parseInt(weeklyMatch[3], 10), 0, 0);
+
+            let diff = targetDay - now.getDay();
+            if (diff < 0 || (diff === 0 && target <= now)) diff += 7;
+            target.setDate(target.getDate() + diff);
+            return target - now;
+        }
+
+        return 0; // every:* → 즉시 시작
+    }
+}

package/lib/schedule/Task.js

@@ -1,39 +1,39 @@
-/**
- * Task — 비동기 위임 작업 (큐)
- *
- * @see docs/framework/10-scheduler-queue.md
- * @see docs/framework/class-design.mm.md (Task)
- */
-import Job from './Job.js';
-
-export default class Task extends Job {
-    /** @type {string} 큐 이름 */
-    static queue = 'default';
-
-    /** @type {number} 최대 재시도 횟수 */
-    static retries = 3;
-
-    /** @type {number} 재시도 딜레이 (ms) */
-    static retryDelay = 5000;
-
-    /** @type {number} 타임아웃 (ms) */
-    static timeout = 30000;
-
-    /**
-     * Task 실행 (서브클래스에서 오버라이드)
-     * @param {object} data - dispatch() 시 전달된 데이터
-     * @returns {Promise<void>}
-     */
-    async handle(data) {
-        throw new Error(`${this.constructor.name}.handle() must be implemented`);
-    }
-
-    /**
-     * 최종 실패 시 호출 (모든 재시도 소진)
-     * @param {object} data
-     * @param {Error} error
-     */
-    async failed(data, error) {
-        this.logger.error(`Task ${this.constructor.name} failed permanently:`, error);
-    }
-}
+/**
+ * Task — 비동기 위임 작업 (큐)
+ *
+ * @see docs/framework/10-scheduler-queue.md
+ * @see docs/framework/class-design.mm.md (Task)
+ */
+import Job from './Job.js';
+
+export default class Task extends Job {
+    /** @type {string} 큐 이름 */
+    static queue = 'default';
+
+    /** @type {number} 최대 재시도 횟수 */
+    static retries = 3;
+
+    /** @type {number} 재시도 딜레이 (ms) */
+    static retryDelay = 5000;
+
+    /** @type {number} 타임아웃 (ms) */
+    static timeout = 30000;
+
+    /**
+     * Task 실행 (서브클래스에서 오버라이드)
+     * @param {object} data - dispatch() 시 전달된 데이터
+     * @returns {Promise<void>}
+     */
+    async handle(data) {
+        throw new Error(`${this.constructor.name}.handle() must be implemented`);
+    }
+
+    /**
+     * 최종 실패 시 호출 (모든 재시도 소진)
+     * @param {object} data
+     * @param {Error} error
+     */
+    async failed(data, error) {
+        this.logger.error(`Task ${this.constructor.name} failed permanently:`, error);
+    }
+}