@fuzionx/framework 0.1.2

package/lib/schedule/Scheduler.js

@@ -0,0 +1,161 @@
+/**
+ * Scheduler — Job 스케줄 관리 (마스터 프로세스)
+ *
+ * @see docs/framework/10-scheduler-queue.md
+ * @see docs/framework/class-design.mm.md (Scheduler)
+ */
+export default class Scheduler {
+    constructor(app) {
+        this.app = app;
+        this._jobs = [];
+        this._timers = [];
+        this._running = false;
+    }
+
+    /**
+     * Job 등록
+     * @param {typeof import('./Job.js').default} JobClass
+     */
+    register(JobClass) {
+        this._jobs.push(JobClass);
+    }
+
+    /**
+     * 모든 스케줄 시작
+     */
+    start() {
+        if (this._running) return;
+        this._running = true;
+
+        for (const JobClass of this._jobs) {
+            // enabled === false면 스킵 (10-scheduler-queue.md)
+            if (JobClass.enabled === false) continue;
+
+            const interval = this._parseCron(JobClass.schedule);
+            if (!interval) continue;
+
+            const timeout = JobClass.timeout || 30000;
+
+            const runJob = async () => {
+                const job = new JobClass(this.app);
+                try {
+                    await Promise.race([
+                        job.handle(),
+                        new Promise((_, reject) =>
+                            setTimeout(() => reject(new Error(`Job timeout (${timeout}ms)`)), timeout)
+                        ),
+                    ]);
+                } catch (err) {
+                    await job.onError(err);
+                }
+            };
+
+            // 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);
+            }
+        }
+    }
+
+    /**
+     * 모든 스케줄 정지
+     */
+    stop() {
+        for (const timer of this._timers) {
+            clearInterval(timer);
+            clearTimeout(timer);
+        }
+        this._timers = [];
+        this._running = false;
+    }
+
+    /**
+     * daily/weekly 스케줄의 첫 실행까지 지연(ms) 계산
+     * @param {string} schedule
+     * @returns {number} 0이면 즉시 setInterval, >0이면 setTimeout 필요
+     * @private
+     */
+    _calcInitialDelay(schedule) {
+        const now = new Date();
+
+        // 'daily:HH:MM'
+        const dailyMatch = schedule.match(/^daily:(\d{2}):(\d{2})$/);
+        if (dailyMatch) {
+            const [, h, m] = dailyMatch;
+            const target = new Date(now);
+            target.setHours(Number(h), Number(m), 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 [, day, h, m] = weeklyMatch;
+            const targetDay = days[day.toLowerCase()] ?? 0;
+            const target = new Date(now);
+            target.setHours(Number(h), Number(m), 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:*, cron → 즉시 setInterval
+    }
+
+    /**
+     * 간단 cron 파서 — 간격(ms) 또는 다음 실행까지 지연(ms) 반환
+     * 지원:
+     *   'every:30s' / 'every:5m' / 'every:1h'
+     *   'daily:02:00' — 매일 HH:MM
+     *   'weekly:mon:09:00' — 매주 요일 HH:MM
+     *   '* * * * *' — 매분 (60초)
+     *   5-field cron — 분 단위 간격 근사
+     * @private
+     */
+    _parseCron(schedule) {
+        if (!schedule) return null;
+
+        // 'every:30s' → 30000ms
+        const everyMatch = schedule.match(/^every:(\d+)([smh])$/);
+        if (everyMatch) {
+            const [, num, unit] = everyMatch;
+            const multiplier = { s: 1000, m: 60000, h: 3600000 };
+            return Number(num) * multiplier[unit];
+        }
+
+        // 'daily:HH:MM' → 24h interval
+        const dailyMatch = schedule.match(/^daily:(\d{2}):(\d{2})$/);
+        if (dailyMatch) {
+            return 86400000;
+        }
+
+        // 'weekly:day:HH:MM' → 7일 간격
+        const weeklyMatch = schedule.match(/^weekly:\w+:\d{2}:\d{2}$/);
+        if (weeklyMatch) {
+            return 604800000;
+        }
+
+        // 5-field cron: '*/5 * * * *' → 분 단위 추출
+        const cronMatch = schedule.match(/^\*\/(\d+)\s/);
+        if (cronMatch) {
+            return Number(cronMatch[1]) * 60000;
+        }
+
+        // '* * * * *' → 60000ms (매분)
+        if (schedule.match(/^[\d*\/,-]+(\s[\d*\/,-]+){4}$/)) return 60000;
+
+        return null;
+    }
+}

package/lib/schedule/Task.js

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

package/lib/schedule/WorkerPool.js

@@ -0,0 +1,225 @@
+/**
+ * WorkerPool — CPU 격리 워커 관리 (worker_threads)
+ *
+ * Scheduler("언제"), Queue("나중에")와 함께 "별도로" 실행을 담당.
+ * CPU-heavy 작업을 별도 스레드에서 실행하여 메인 이벤트 루프 보호.
+ *
+ * workers/ 폴더 컨벤션:
+ *   workers/
+ *   ├── csv-parser.js
+ *   ├── image-resize.js
+ *   └── excel/
+ *       └── csv-parser.js
+ *
+ * @see docs/framework/10-scheduler-queue.md
+ *
+ * @example
+ * // 단축 이름 (workers/ 폴더 기준)
+ * const result = await app.worker.run('csv-parser', { path: '/tmp/data.csv' });
+ * const result = await app.worker.run('excel/csv-parser', { path: '/tmp/sheet.xlsx' });
+ *
+ * // 절대경로도 가능
+ * const result = await app.worker.run('/opt/workers/custom.js', data);
+ *
+ * // Queue Task 내에서 조합
+ * class HeavyTask extends Task {
+ *     async handle(data) {
+ *         const result = await this.worker.run('file-processor', data);
+ *         await this.db.Report.create(result);
+ *     }
+ * }
+ */
+import { Worker, isMainThread } from 'node:worker_threads';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export default class WorkerPool {
+    /**
+     * @param {import('../core/Application.js').default} app
+     * @param {object} [opts]
+     * @param {number} [opts.timeout=30000] - 기본 타임아웃 (ms)
+     */
+    constructor(app, opts = {}) {
+        this.app = app;
+        this._defaultTimeout = opts.timeout || 30000;
+        /** @type {Set<Worker>} 활성 워커 추적 */
+        this._activeWorkers = new Set();
+    }
+
+    /**
+     * 워커 스크립트 실행
+     *
+     * 이름 해석 규칙:
+     *   - 절대경로 → 그대로 사용
+     *   - 확장자 포함 (`./xxx.js`) → baseDir 상대경로
+     *   - 단축 이름 (`csv-parser`, `excel/csv-parser`) → workers/ 폴더에서 .js/.mjs 자동 탐색
+     *
+     * @param {string} name - 워커 이름 또는 경로
+     * @param {*} [data] - workerData로 전달
+     * @param {object} [opts]
+     * @param {number} [opts.timeout] - 타임아웃 (ms)
+     * @param {Array} [opts.transferList] - ArrayBuffer 등 zero-copy 전송
+     * @returns {Promise<*>} 워커 결과
+     */
+    run(name, data, opts = {}) {
+        const timeout = opts.timeout ?? this._defaultTimeout;
+        const resolved = this._resolve(name);
+
+        return new Promise((resolve, reject) => {
+            const worker = new Worker(resolved, {
+                workerData: data,
+                transferList: opts.transferList,
+            });
+
+            this._activeWorkers.add(worker);
+
+            let timer;
+            let settled = false;
+
+            const settle = (fn, value) => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                this._activeWorkers.delete(worker);
+                fn(value);
+            };
+
+            worker.on('message', (result) => settle(resolve, result));
+            worker.on('error', (err) => settle(reject, err));
+            worker.on('exit', (code) => {
+                if (!settled) {
+                    settle(reject, new Error(`Worker exited with code ${code}`));
+                }
+            });
+
+            if (timeout > 0) {
+                timer = setTimeout(() => {
+                    worker.terminate();
+                    settle(reject, new Error(`Worker timeout (${timeout}ms)`));
+                }, timeout);
+            }
+        });
+    }
+
+    /**
+     * 인라인 순수 함수를 워커에서 실행
+     *
+     * 함수는 직렬화 가능해야 함 (클로저/외부 참조 불가).
+     * 워커 내에서 require() 사용 가능.
+     *
+     * @param {Function} fn - (data) => result 형태의 순수 함수
+     * @param {*} [data] - 함수에 전달할 데이터
+     * @param {object} [opts]
+     * @param {number} [opts.timeout] - 타임아웃 (ms)
+     * @returns {Promise<*>} 함수 실행 결과
+     */
+    exec(fn, data, opts = {}) {
+        const timeout = opts.timeout ?? this._defaultTimeout;
+        const fnStr = fn.toString();
+
+        // 인라인 워커 코드
+        const workerCode = `
+            const { parentPort, workerData } = require('worker_threads');
+            const fn = ${fnStr};
+            (async () => {
+                try {
+                    const result = await fn(workerData);
+                    parentPort.postMessage(result);
+                } catch (err) {
+                    throw err;
+                }
+            })();
+        `;
+
+        return new Promise((resolve, reject) => {
+            const worker = new Worker(workerCode, {
+                eval: true,
+                workerData: data,
+            });
+
+            this._activeWorkers.add(worker);
+
+            let timer;
+            let settled = false;
+
+            const settle = (fn, value) => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                this._activeWorkers.delete(worker);
+                fn(value);
+            };
+
+            worker.on('message', (result) => settle(resolve, result));
+            worker.on('error', (err) => settle(reject, err));
+            worker.on('exit', (code) => {
+                if (!settled) {
+                    settle(reject, new Error(`Worker exited with code ${code}`));
+                }
+            });
+
+            if (timeout > 0) {
+                timer = setTimeout(() => {
+                    worker.terminate();
+                    settle(reject, new Error(`Worker timeout (${timeout}ms)`));
+                }, timeout);
+            }
+        });
+    }
+
+    /**
+     * 활성 워커 수
+     * @returns {number}
+     */
+    get active() {
+        return this._activeWorkers.size;
+    }
+
+    /**
+     * 모든 활성 워커 종료 (graceful shutdown)
+     * @returns {Promise<void>}
+     */
+    async terminate() {
+        const terminations = [];
+        for (const worker of this._activeWorkers) {
+            terminations.push(worker.terminate());
+        }
+        await Promise.allSettled(terminations);
+        this._activeWorkers.clear();
+    }
+
+    /**
+     * 워커 이름 → 절대경로 해석
+     *
+     * 규칙:
+     *   1) 절대경로 → 그대로
+     *   2) 확장자 포함 (./foo.js, ../foo.mjs) → baseDir 기준 상대경로
+     *   3) 단축 이름 (csv-parser, excel/csv-parser) → workers/ 폴더에서 탐색
+     *      탐색 순서: .js → .mjs
+     *
+     * @param {string} name
+     * @returns {string} 절대경로
+     * @private
+     */
+    _resolve(name) {
+        // 1) 절대경로
+        if (path.isAbsolute(name)) return name;
+
+        const baseDir = this.app?.baseDir || '.';
+
+        // 2) 확장자 포함 → baseDir 상대경로
+        if (/\.\w+$/.test(name)) {
+            return path.resolve(baseDir, name);
+        }
+
+        // 3) 단축 이름 → workers/ 폴더 탐색
+        const workersDir = path.resolve(baseDir, 'workers');
+        for (const ext of ['.js', '.mjs']) {
+            const candidate = path.join(workersDir, name + ext);
+            if (fs.existsSync(candidate)) return candidate;
+        }
+
+        // 기본값: workers/{name}.js (존재하지 않아도 Worker 생성 시 에러)
+        return path.join(workersDir, name + '.js');
+    }
+}

package/lib/services/EventBus.js

@@ -0,0 +1,94 @@
+/**
+ * EventBus — 앱 내 + Hub 경유 이벤트 시스템
+ *
+ * @see docs/framework/05-eventbus.md
+ */
+export default class EventBus {
+    /**
+     * @param {import('./Application.js').default} app
+     */
+    constructor(app) {
+        this.app = app;
+        this._handlers = new Map();
+    }
+
+    /**
+     * 이벤트 구독
+     * @param {string} event
+     * @param {Function} handler - (data, meta) => void
+     */
+    on(event, handler) {
+        if (!this._handlers.has(event)) {
+            this._handlers.set(event, []);
+        }
+        this._handlers.get(event).push(handler);
+    }
+
+    /**
+     * 이벤트 발행 (로컬)
+     * @param {string} event
+     * @param {*} data
+     * @param {object} [opts] - { hub: true } → Hub 전파
+     */
+    async emit(event, data, opts = {}) {
+        const meta = {
+            remote: false,
+            server: this.app?.config?.get('app.name', 'fuzionx') || 'fuzionx',
+            timestamp: Date.now(),
+        };
+
+        const handlers = this._handlers.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                try { await handler(data, meta); } catch (err) {
+                    this.app?.logger?.error?.(`Event '${event}' handler error:`, err);
+                }
+            }
+        }
+
+        // Hub 전파 (Hub 연동 시 구현)
+        if (opts.hub && this.app?.ws?.hub) {
+            // this.app.ws.hub.publish(event, data);
+        }
+    }
+
+    /**
+     * 원격 이벤트 수신 (Hub에서 호출)
+     * @param {string} event
+     * @param {*} data
+     * @param {object} remoteMeta
+     */
+    async onRemoteEvent(event, data, remoteMeta) {
+        const handlers = this._handlers.get(event);
+        if (!handlers) return;
+
+        const meta = { ...remoteMeta, remote: true };
+        for (const handler of handlers) {
+            await handler(data, meta);
+        }
+    }
+
+    /**
+     * 구독 해제
+     * @param {string} event
+     * @param {Function} [handler] - 없으면 이벤트의 모든 핸들러 해제
+     */
+    off(event, handler) {
+        if (!handler) {
+            this._handlers.delete(event);
+            return;
+        }
+        const handlers = this._handlers.get(event);
+        if (handlers) {
+            const idx = handlers.indexOf(handler);
+            if (idx >= 0) handlers.splice(idx, 1);
+        }
+    }
+
+    /**
+     * 모든 구독 해제
+     */
+    clear() {
+        this._handlers.clear();
+    }
+}