@fuzionx/framework 0.1.42 → 0.1.44

package/lib/schedule/WorkerPool.js

@@ -1,225 +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 = (cb, value) => {
-                if (settled) return;
-                settled = true;
-                clearTimeout(timer);
-                this._activeWorkers.delete(worker);
-                cb(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) 단축 이름 → shared/workers/ 폴더 탐색
-        const workersDir = path.resolve(baseDir, 'shared/workers');
-        for (const ext of ['.js', '.mjs']) {
-            const candidate = path.join(workersDir, name + ext);
-            if (fs.existsSync(candidate)) return candidate;
-        }
-
-        // 기본값: shared/workers/{name}.js (존재하지 않아도 Worker 생성 시 에러)
-        return path.join(workersDir, name + '.js');
-    }
-}
+/**
+ * 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 = (cb, value) => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                this._activeWorkers.delete(worker);
+                cb(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) 단축 이름 → shared/workers/ 폴더 탐색
+        const workersDir = path.resolve(baseDir, 'shared/workers');
+        for (const ext of ['.js', '.mjs']) {
+            const candidate = path.join(workersDir, name + ext);
+            if (fs.existsSync(candidate)) return candidate;
+        }
+
+        // 기본값: shared/workers/{name}.js (존재하지 않아도 Worker 생성 시 에러)
+        return path.join(workersDir, name + '.js');
+    }
+}

package/lib/services/EventBus.js

@@ -1,94 +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();
-    }
-}
+/**
+ * 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();
+    }
+}