@fuzionx/framework 0.1.43 → 0.1.44

package/lib/middleware/csrf.js

@@ -1,32 +1,32 @@
-/**
- * csrf — CSRF 보호 미들웨어
- *
- * GET/HEAD/OPTIONS 는 통과, 나머지는 토큰 검증.
- *
- * @see docs/framework/12-middleware.md
- *
- * @param {object} [opts]
- * @param {string} [opts.headerName='x-csrf-token']
- * @param {string} [opts.sessionKey='_csrfToken']
- */
-export function csrf(opts = {}) {
-    const headerName = opts.headerName || 'x-csrf-token';
-    const sessionKey = opts.sessionKey || '_csrfToken';
-
-    return async (ctx, next) => {
-        if (['GET', 'HEAD', 'OPTIONS'].includes(ctx.method)) {
-            await next();
-            return;
-        }
-
-        const token = ctx.get(headerName);
-        const expected = ctx._rawSession?.[sessionKey];
-
-        if (!token || !expected || token !== expected) {
-            ctx.status(403).json({ error: { message: 'CSRF token mismatch', status: 403 } });
-            return;
-        }
-
-        await next();
-    };
-}
+/**
+ * csrf — CSRF 보호 미들웨어
+ *
+ * GET/HEAD/OPTIONS 는 통과, 나머지는 토큰 검증.
+ *
+ * @see docs/framework/12-middleware.md
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.headerName='x-csrf-token']
+ * @param {string} [opts.sessionKey='_csrfToken']
+ */
+export function csrf(opts = {}) {
+    const headerName = opts.headerName || 'x-csrf-token';
+    const sessionKey = opts.sessionKey || '_csrfToken';
+
+    return async (ctx, next) => {
+        if (['GET', 'HEAD', 'OPTIONS'].includes(ctx.method)) {
+            await next();
+            return;
+        }
+
+        const token = ctx.get(headerName);
+        const expected = ctx._rawSession?.[sessionKey];
+
+        if (!token || !expected || token !== expected) {
+            ctx.status(403).json({ error: { message: 'CSRF token mismatch', status: 403 } });
+            return;
+        }
+
+        await next();
+    };
+}

package/lib/middleware/index.js

@@ -1,13 +1,13 @@
-/**
- * 내장 미들웨어 — 배럴 re-export
- *
- * @see docs/framework/12-middleware.md
- * @see docs/framework/14-authentication.md
- */
-export { bodyParser } from './bodyParser.js';
-export { cors } from './cors.js';
-export { auth } from './auth.js';
-export { apiAuth } from './apiAuth.js';
-export { csrf } from './csrf.js';
-export { session } from './session.js';
-export { theme } from './theme.js';
+/**
+ * 내장 미들웨어 — 배럴 re-export
+ *
+ * @see docs/framework/12-middleware.md
+ * @see docs/framework/14-authentication.md
+ */
+export { bodyParser } from './bodyParser.js';
+export { cors } from './cors.js';
+export { auth } from './auth.js';
+export { apiAuth } from './apiAuth.js';
+export { csrf } from './csrf.js';
+export { session } from './session.js';
+export { theme } from './theme.js';

package/lib/middleware/session.js

@@ -1,27 +1,27 @@
-/**
- * session — 세션 로드/저장 미들웨어
- *
- * Bridge sessionGet/sessionSet 사용.
- *
- * @see docs/framework/12-middleware.md — "session: 세션 로드/저장"
- */
-export function session(opts = {}) {
-    return async (ctx, next) => {
-        // Session은 Context 생성 시 rawReq.session에서 이미 로드됨
-        // Bridge가 rawReq에 session 데이터를 포함하여 전달
-
-        await next();
-
-        // 요청 완료 후 — 소비된 flash 데이터 정리
-        const bridge = ctx.app?._bridge;
-        const sessionId = ctx._sessionId;
-        if (sessionId && bridge?.sessionSet && ctx._rawSession) {
-            if (ctx._rawSession._flash && Object.keys(ctx._rawSession._flash).length === 0) {
-                delete ctx._rawSession._flash;
-            }
-            try {
-                bridge.sessionSet(sessionId, ctx._rawSession);
-            } catch {}
-        }
-    };
-}
+/**
+ * session — 세션 로드/저장 미들웨어
+ *
+ * Bridge sessionGet/sessionSet 사용.
+ *
+ * @see docs/framework/12-middleware.md — "session: 세션 로드/저장"
+ */
+export function session(opts = {}) {
+    return async (ctx, next) => {
+        // Session은 Context 생성 시 rawReq.session에서 이미 로드됨
+        // Bridge가 rawReq에 session 데이터를 포함하여 전달
+
+        await next();
+
+        // 요청 완료 후 — 소비된 flash 데이터 정리
+        const bridge = ctx.app?._bridge;
+        const sessionId = ctx._sessionId;
+        if (sessionId && bridge?.sessionSet && ctx._rawSession) {
+            if (ctx._rawSession._flash && Object.keys(ctx._rawSession._flash).length === 0) {
+                delete ctx._rawSession._flash;
+            }
+            try {
+                bridge.sessionSet(sessionId, ctx._rawSession);
+            } catch {}
+        }
+    };
+}

package/lib/middleware/theme.js

@@ -1,20 +1,20 @@
-/**
- * theme — 도메인 → 테마 매핑 미들웨어
- *
- * @see docs/framework/03-views-templates.md
- * @see docs/framework/12-middleware.md — "theme: 도메인 → 테마 매핑"
- *
- * @param {object} [opts]
- * @param {string} [opts.default='default'] - 기본 테마
- * @param {object} [opts.mapping] - { 'domain.com': 'theme1' }
- */
-export function theme(opts = {}) {
-    const defaultTheme = opts.default || 'default';
-
-    return async (ctx, next) => {
-        const configDefault = ctx.app?.config?.get('app.themes.default') || defaultTheme;
-        ctx.theme = configDefault;
-
-        await next();
-    };
-}
+/**
+ * theme — 도메인 → 테마 매핑 미들웨어
+ *
+ * @see docs/framework/03-views-templates.md
+ * @see docs/framework/12-middleware.md — "theme: 도메인 → 테마 매핑"
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.default='default'] - 기본 테마
+ * @param {object} [opts.mapping] - { 'domain.com': 'theme1' }
+ */
+export function theme(opts = {}) {
+    const defaultTheme = opts.default || 'default';
+
+    return async (ctx, next) => {
+        const configDefault = ctx.app?.config?.get('app.themes.default') || defaultTheme;
+        ctx.theme = configDefault;
+
+        await next();
+    };
+}

package/lib/realtime/RoomManager.js

@@ -1,85 +1,85 @@
-/**
- * RoomManager — 전체 룸 상태 관리 (Primary 프로세스)
- *
- * @see docs/framework/class-design.mm.md (RoomManager)
- */
-export default class RoomManager {
-    constructor() {
-        /** @type {Map<string, Set<string>>} roomName → Set<socketId> */
-        this._rooms = new Map();
-    }
-
-    /**
-     * 룸에 참가
-     * @param {string} room
-     * @param {string} socketId
-     */
-    join(room, socketId) {
-        if (!this._rooms.has(room)) {
-            this._rooms.set(room, new Set());
-        }
-        this._rooms.get(room).add(socketId);
-    }
-
-    /**
-     * 룸에서 퇴장
-     * @param {string} room
-     * @param {string} socketId
-     */
-    leave(room, socketId) {
-        const members = this._rooms.get(room);
-        if (!members) return;
-        members.delete(socketId);
-        if (members.size === 0) {
-            this._rooms.delete(room);
-        }
-    }
-
-    /**
-     * 소켓이 속한 모든 룸에서 퇴장
-     * @param {string} socketId
-     */
-    leaveAll(socketId) {
-        for (const [room, members] of this._rooms) {
-            members.delete(socketId);
-            if (members.size === 0) {
-                this._rooms.delete(room);
-            }
-        }
-    }
-
-    /**
-     * 룸 멤버 조회
-     * @param {string} room
-     * @returns {string[]}
-     */
-    members(room) {
-        const members = this._rooms.get(room);
-        return members ? [...members] : [];
-    }
-
-    /**
-     * 룸 존재 여부
-     * @param {string} room
-     * @returns {boolean}
-     */
-    has(room) {
-        return this._rooms.has(room) && this._rooms.get(room).size > 0;
-    }
-
-    /**
-     * 전체 룸 목록
-     * @returns {string[]}
-     */
-    rooms() {
-        return [...this._rooms.keys()];
-    }
-
-    /**
-     * 룸 수
-     * @returns {number}
-     */
-    get size() {
-        return this._rooms.size;
-    }
-}
+/**
+ * RoomManager — 전체 룸 상태 관리 (Primary 프로세스)
+ *
+ * @see docs/framework/class-design.mm.md (RoomManager)
+ */
+export default class RoomManager {
+    constructor() {
+        /** @type {Map<string, Set<string>>} roomName → Set<socketId> */
+        this._rooms = new Map();
+    }
+
+    /**
+     * 룸에 참가
+     * @param {string} room
+     * @param {string} socketId
+     */
+    join(room, socketId) {
+        if (!this._rooms.has(room)) {
+            this._rooms.set(room, new Set());
+        }
+        this._rooms.get(room).add(socketId);
+    }
+
+    /**
+     * 룸에서 퇴장
+     * @param {string} room
+     * @param {string} socketId
+     */
+    leave(room, socketId) {
+        const members = this._rooms.get(room);
+        if (!members) return;
+        members.delete(socketId);
+        if (members.size === 0) {
+            this._rooms.delete(room);
+        }
+    }
+
+    /**
+     * 소켓이 속한 모든 룸에서 퇴장
+     * @param {string} socketId
+     */
+    leaveAll(socketId) {
+        for (const [room, members] of this._rooms) {
+            members.delete(socketId);
+            if (members.size === 0) {
+                this._rooms.delete(room);
+            }
+        }
+    }
+
+    /**
+     * 룸 멤버 조회
+     * @param {string} room
+     * @returns {string[]}
+     */
+    members(room) {
+        const members = this._rooms.get(room);
+        return members ? [...members] : [];
+    }
+
+    /**
+     * 룸 존재 여부
+     * @param {string} room
+     * @returns {boolean}
+     */
+    has(room) {
+        return this._rooms.has(room) && this._rooms.get(room).size > 0;
+    }
+
+    /**
+     * 전체 룸 목록
+     * @returns {string[]}
+     */
+    rooms() {
+        return [...this._rooms.keys()];
+    }
+
+    /**
+     * 룸 수
+     * @returns {number}
+     */
+    get size() {
+        return this._rooms.size;
+    }
+}

package/lib/realtime/WsHandler.js

@@ -1,107 +1,107 @@
-/**
- * WsHandler — WebSocket 네임스페이스 핸들러
- *
- * @see docs/framework/11-websocket.md
- * @see docs/framework/class-design.mm.md (WsHandler + EventBuilder)
- */
-import Base from '../core/Base.js';
-
-/**
- * EventBuilder — static events(e) DSL에서 사용
- *
- * @example
- * static events(e) {
- *     e.on('chat', this.handleChat);
- *     e.on('typing', this.handleTyping, ['rateLimit:10']);
- * }
- */
-export class EventBuilder {
-    constructor() {
-        this._events = [];
-    }
-
-    /**
-     * 이벤트 핸들러 등록
-     * @param {string} type - 이벤트 타입
-     * @param {Function|object} handler - 핸들러 메서드 레퍼런스
-     * @param {string[]} [middleware] - 이벤트별 미들웨어
-     */
-    on(type, handler, middleware = []) {
-        this._events.push({ type, handler, middleware });
-    }
-}
-
-export default class WsHandler extends Base {
-    /** @type {string} 네임스페이스 경로 (e.g. '/chat') */
-    static namespace = '/';
-
-    /** @type {string[]} 핸드셰이크 미들웨어 */
-    static middleware = [];
-
-    /**
-     * 이벤트 라우팅 선언 (서브클래스에서 오버라이드)
-     * @param {EventBuilder} e
-     */
-    static events(e) {
-        // 서브클래스에서:
-        // e.on('chat', this.handleChat);
-        // e.on('typing', this.handleTyping, ['rateLimit:10']);
-    }
-
-    /**
-     * 이벤트 라우팅 맵 빌드
-     * @returns {Map<string, {handler, middleware}>}
-     */
-    static buildEventMap() {
-        const builder = new EventBuilder();
-        this.events(builder);
-        const map = new Map();
-        for (const { type, handler, middleware } of builder._events) {
-            map.set(type, { handler, middleware });
-        }
-        return map;
-    }
-
-    // ── 라이프사이클 훅 ──
-
-    /**
-     * 연결 시 (서브클래스에서 오버라이드)
-     * @param {object} socket
-     */
-    async onConnect(socket) {}
-
-    /**
-     * 이벤트 핸들러 (서브클래스에서 오버라이드)
-     * @param {object} socket
-     * @param {string} event
-     * @param {*} data
-     */
-    async onEvent(socket, event, data) {}
-
-    /**
-     * 연결 해제 시 (서브클래스에서 오버라이드)
-     * @param {object} socket
-     * @param {number} code
-     * @param {string} reason
-     */
-    async onDisconnect(socket, code, reason) {}
-
-    /**
-     * 미등록 이벤트 수신 시 (서브클래스에서 오버라이드)
-     * @param {object} socket
-     * @param {string} type
-     * @param {*} data
-     */
-    async onUnknownEvent(socket, type, data) {
-        // 기본: 무시 (서브클래스에서 오버라이드 가능)
-    }
-
-    /**
-     * 에러 시 (서브클래스에서 오버라이드)
-     * @param {object} socket
-     * @param {Error} error
-     */
-    async onError(socket, error) {
-        this.logger?.error(`WS error in ${this.constructor.namespace}:`, error);
-    }
-}
+/**
+ * WsHandler — WebSocket 네임스페이스 핸들러
+ *
+ * @see docs/framework/11-websocket.md
+ * @see docs/framework/class-design.mm.md (WsHandler + EventBuilder)
+ */
+import Base from '../core/Base.js';
+
+/**
+ * EventBuilder — static events(e) DSL에서 사용
+ *
+ * @example
+ * static events(e) {
+ *     e.on('chat', this.handleChat);
+ *     e.on('typing', this.handleTyping, ['rateLimit:10']);
+ * }
+ */
+export class EventBuilder {
+    constructor() {
+        this._events = [];
+    }
+
+    /**
+     * 이벤트 핸들러 등록
+     * @param {string} type - 이벤트 타입
+     * @param {Function|object} handler - 핸들러 메서드 레퍼런스
+     * @param {string[]} [middleware] - 이벤트별 미들웨어
+     */
+    on(type, handler, middleware = []) {
+        this._events.push({ type, handler, middleware });
+    }
+}
+
+export default class WsHandler extends Base {
+    /** @type {string} 네임스페이스 경로 (e.g. '/chat') */
+    static namespace = '/';
+
+    /** @type {string[]} 핸드셰이크 미들웨어 */
+    static middleware = [];
+
+    /**
+     * 이벤트 라우팅 선언 (서브클래스에서 오버라이드)
+     * @param {EventBuilder} e
+     */
+    static events(e) {
+        // 서브클래스에서:
+        // e.on('chat', this.handleChat);
+        // e.on('typing', this.handleTyping, ['rateLimit:10']);
+    }
+
+    /**
+     * 이벤트 라우팅 맵 빌드
+     * @returns {Map<string, {handler, middleware}>}
+     */
+    static buildEventMap() {
+        const builder = new EventBuilder();
+        this.events(builder);
+        const map = new Map();
+        for (const { type, handler, middleware } of builder._events) {
+            map.set(type, { handler, middleware });
+        }
+        return map;
+    }
+
+    // ── 라이프사이클 훅 ──
+
+    /**
+     * 연결 시 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     */
+    async onConnect(socket) {}
+
+    /**
+     * 이벤트 핸들러 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     * @param {string} event
+     * @param {*} data
+     */
+    async onEvent(socket, event, data) {}
+
+    /**
+     * 연결 해제 시 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     * @param {number} code
+     * @param {string} reason
+     */
+    async onDisconnect(socket, code, reason) {}
+
+    /**
+     * 미등록 이벤트 수신 시 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     * @param {string} type
+     * @param {*} data
+     */
+    async onUnknownEvent(socket, type, data) {
+        // 기본: 무시 (서브클래스에서 오버라이드 가능)
+    }
+
+    /**
+     * 에러 시 (서브클래스에서 오버라이드)
+     * @param {object} socket
+     * @param {Error} error
+     */
+    async onError(socket, error) {
+        this.logger?.error(`WS error in ${this.constructor.namespace}:`, error);
+    }
+}

package/lib/schedule/Job.js

@@ -1,38 +1,38 @@
-/**
- * Job — 정기 실행 작업 (cron 스케줄)
- *
- * @see docs/framework/10-scheduler-queue.md
- * @see docs/framework/class-design.mm.md (Job)
- */
-import Base from '../core/Base.js';
-
-export default class Job extends Base {
-    /** @type {string} cron 표현식 또는 간편 표현 (every:5m, daily:02:00) */
-    static schedule = '';
-
-    /** @type {number} 타임아웃 (ms), 기본 30초 */
-    static timeout = 30000;
-
-    /** @type {boolean} false면 스킵 */
-    static enabled = true;
-
-    /**
-     * Job 실행 (서브클래스에서 오버라이드)
-     *
-     * 메인 스레드에서 실행되므로 this.db, this.service() 등 접근 가능.
-     * CPU-intensive 작업은 this.worker.run() 또는 this.worker.exec()으로 위임.
-     *
-     * @returns {Promise<void>}
-     */
-    async handle() {
-        throw new Error(`${this.constructor.name}.handle() must be implemented`);
-    }
-
-    /**
-     * Job 실패 시 호출 (서브클래스에서 오버라이드)
-     * @param {Error} error
-     */
-    async onError(error) {
-        this.logger.error(`Job ${this.constructor.name} failed:`, error);
-    }
-}
+/**
+ * Job — 정기 실행 작업 (cron 스케줄)
+ *
+ * @see docs/framework/10-scheduler-queue.md
+ * @see docs/framework/class-design.mm.md (Job)
+ */
+import Base from '../core/Base.js';
+
+export default class Job extends Base {
+    /** @type {string} cron 표현식 또는 간편 표현 (every:5m, daily:02:00) */
+    static schedule = '';
+
+    /** @type {number} 타임아웃 (ms), 기본 30초 */
+    static timeout = 30000;
+
+    /** @type {boolean} false면 스킵 */
+    static enabled = true;
+
+    /**
+     * Job 실행 (서브클래스에서 오버라이드)
+     *
+     * 메인 스레드에서 실행되므로 this.db, this.service() 등 접근 가능.
+     * CPU-intensive 작업은 this.worker.run() 또는 this.worker.exec()으로 위임.
+     *
+     * @returns {Promise<void>}
+     */
+    async handle() {
+        throw new Error(`${this.constructor.name}.handle() must be implemented`);
+    }
+
+    /**
+     * Job 실패 시 호출 (서브클래스에서 오버라이드)
+     * @param {Error} error
+     */
+    async onError(error) {
+        this.logger.error(`Job ${this.constructor.name} failed:`, error);
+    }
+}