@fuzionx/framework 0.1.61 → 0.1.62

package/index.js

@@ -36,6 +36,7 @@ export { default as Pagination } from './lib/database/Pagination.js';
 export { default as Service } from './lib/services/Service.js';
 export { default as EventBus } from './lib/services/EventBus.js';
 export { default as Storage } from './lib/services/Storage.js';
+export { default as CacheManager } from './lib/cache/CacheManager.js';
 
 // ── Realtime ──
 export { default as WsHandler, EventBuilder } from './lib/realtime/WsHandler.js';
@@ -64,4 +65,4 @@ export { default as OpenAPI } from './lib/view/OpenAPI.js';
 export { PaginationUtil, StrUtil, NumUtil, DateUtil, ArrUtil, FunctionUtil, ObjectUtil } from './lib/utilities/index.js';
 
 // ── Built-in Middleware ──
-export { bodyParser, cors, auth, apiAuth, csrf, session, theme, loadUser } from './lib/middleware/index.js';
+export { bodyParser, cors, auth, apiAuth, csrf, session, theme, loadUser, roleGuard } from './lib/middleware/index.js';

package/lib/cache/CacheManager.js

@@ -0,0 +1,183 @@
+/**
+ * CacheManager — 캐시 관리자
+ *
+ * fuzionx.yaml의 `cache` 설정을 읽어 적절한 드라이버를 초기화.
+ * 지원 드라이버: redis, file
+ *
+ * 워커 간 공유가 필요하므로 인메모리(Map)는 지원하지 않음.
+ * Redis 또는 파일시스템을 통해 프로세스 간 캐시를 공유.
+ *
+ * @example
+ * // Service 내에서 사용
+ * const stats = await this.cache.get('dashboard:stats');
+ * await this.cache.set('dashboard:stats', data, 300);
+ *
+ * // withCache 패턴 (캐시 미스 시 자동 실행)
+ * const result = await this.cache.remember('user:1', 600, async () => {
+ *     return this.db.User.find(1);
+ * });
+ *
+ * @see docs/framework/cache.md
+ */
+export default class CacheManager {
+    /**
+     * @param {object} config - cache 설정 객체
+     * @param {string} config.driver - 'redis' | 'file'
+     * @param {string} [config.redis_url] - Redis 접속 URL (driver='redis')
+     * @param {string} [config.prefix] - 캐시 키 접두사
+     * @param {number} [config.ttl] - 기본 TTL (초)
+     * @param {string} [config.file_dir] - 파일 캐시 디렉토리 (driver='file')
+     */
+    constructor(config = {}) {
+        /** @type {string} 캐시 드라이버 */
+        this.driverName = (config.driver || 'file').toLowerCase();
+
+        /** @type {string} 캐시 키 접두사 */
+        this.prefix = config.prefix || '';
+
+        /** @type {number} 기본 TTL (초) */
+        this.defaultTtl = config.ttl || 3600;
+
+        /** @type {import('./drivers/RedisDriver.js').default | import('./drivers/FileDriver.js').default | null} 드라이버 인스턴스 */
+        this._driver = null;
+
+        /** @type {object} 원본 설정 */
+        this._config = config;
+
+        /** @type {boolean} 초기화 완료 여부 */
+        this._ready = false;
+    }
+
+    /**
+     * 드라이버 초기화 (지연 로딩)
+     *
+     * @returns {Promise<void>}
+     */
+    async init() {
+        if (this._ready) return;
+
+        if (this.driverName === 'redis') {
+            const { default: RedisDriver } = await import('./drivers/RedisDriver.js');
+            this._driver = new RedisDriver({
+                url: this._config.redis_url,
+                prefix: this.prefix,
+            });
+            await this._driver.connect();
+        } else if (this.driverName === 'file') {
+            const { default: FileDriver } = await import('./drivers/FileDriver.js');
+            this._driver = new FileDriver({
+                dir: this._config.file_dir || './storage/cache',
+                prefix: this.prefix,
+            });
+            await this._driver.init();
+        } else {
+            throw new Error(`[CacheManager] 지원하지 않는 캐시 드라이버: ${this.driverName}`);
+        }
+
+        this._ready = true;
+    }
+
+    /**
+     * 캐시 값 조회
+     *
+     * @param {string} key - 캐시 키
+     * @returns {Promise<*|null>} 캐시 값 또는 null
+     */
+    async get(key) {
+        if (!this._ready) await this.init();
+        return this._driver.get(key);
+    }
+
+    /**
+     * 캐시 값 저장
+     *
+     * @param {string} key - 캐시 키
+     * @param {*} value - 저장할 값 (JSON 직렬화 가능)
+     * @param {number} [ttl] - TTL (초), 기본값: this.defaultTtl
+     * @returns {Promise<void>}
+     */
+    async set(key, value, ttl) {
+        if (!this._ready) await this.init();
+        return this._driver.set(key, value, ttl || this.defaultTtl);
+    }
+
+    /**
+     * 캐시 키 존재 여부
+     *
+     * @param {string} key - 캐시 키
+     * @returns {Promise<boolean>}
+     */
+    async has(key) {
+        if (!this._ready) await this.init();
+        return this._driver.has(key);
+    }
+
+    /**
+     * 캐시 키 삭제
+     *
+     * @param {string} key - 캐시 키
+     * @returns {Promise<void>}
+     */
+    async delete(key) {
+        if (!this._ready) await this.init();
+        return this._driver.delete(key);
+    }
+
+    /**
+     * 패턴 기반 캐시 삭제
+     *
+     * @param {string} pattern - 키 패턴 (예: 'user:*')
+     * @returns {Promise<number>} 삭제된 키 수
+     */
+    async deletePattern(pattern) {
+        if (!this._ready) await this.init();
+        return this._driver.deletePattern(pattern);
+    }
+
+    /**
+     * 전체 캐시 초기화 (prefix 범위)
+     *
+     * @returns {Promise<void>}
+     */
+    async flush() {
+        if (!this._ready) await this.init();
+        return this._driver.flush();
+    }
+
+    /**
+     * 캐시 미스 시 자동 실행 (remember 패턴)
+     *
+     * 캐시가 존재하면 반환, 없으면 fn()을 실행하고 결과를 캐시에 저장.
+     *
+     * @param {string} key - 캐시 키
+     * @param {number} ttl - TTL (초)
+     * @param {Function} fn - 캐시 미스 시 실행할 함수
+     * @returns {Promise<*>}
+     *
+     * @example
+     * const user = await this.cache.remember('user:1', 300, async () => {
+     *     return this.db.User.find(1);
+     * });
+     */
+    async remember(key, ttl, fn) {
+        const cached = await this.get(key);
+        if (cached !== null) return cached;
+
+        const value = await fn();
+        await this.set(key, value, ttl);
+        return value;
+    }
+
+    /**
+     * 연결 해제
+     *
+     * @returns {Promise<void>}
+     */
+    async disconnect() {
+        if (this._driver?.disconnect) {
+            await this._driver.disconnect();
+        }
+        this._ready = false;
+        this._driver = null;
+    }
+}

package/lib/cache/drivers/FileDriver.js

@@ -0,0 +1,228 @@
+/**
+ * FileDriver — 파일 기반 캐시 드라이버
+ *
+ * 캐시 데이터를 JSON 파일로 저장.
+ * 각 키는 개별 .json 파일로 관리되며, 메타데이터(expires)를 함께 저장.
+ * GC(Garbage Collection)로 만료된 파일을 주기적으로 정리.
+ *
+ * 파일명은 키를 SHA-256 해시하여 충돌 방지.
+ *
+ * @see lib/cache/CacheManager.js
+ */
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export default class FileDriver {
+    /**
+     * @param {object} opts
+     * @param {string} opts.dir - 캐시 파일 저장 디렉토리
+     * @param {string} [opts.prefix] - 캐시 키 접두사
+     */
+    constructor(opts = {}) {
+        /** @type {string} 캐시 디렉토리 */
+        this._dir = path.resolve(opts.dir || './storage/cache');
+
+        /** @type {string} 키 접두사 */
+        this._prefix = opts.prefix ? `${opts.prefix}:` : '';
+
+        /** @type {NodeJS.Timeout|null} GC 타이머 */
+        this._gcTimer = null;
+    }
+
+    /**
+     * 초기화 — 캐시 디렉토리 생성 + GC 스케줄링
+     *
+     * @returns {Promise<void>}
+     */
+    async init() {
+        await fs.mkdir(this._dir, { recursive: true });
+
+        // 5분마다 만료 캐시 정리
+        this._gcTimer = setInterval(() => this._gc(), 5 * 60 * 1000);
+        if (this._gcTimer.unref) this._gcTimer.unref(); // 프로세스 종료 차단 방지
+    }
+
+    /**
+     * 키 → 파일 경로 변환
+     *
+     * SHA-256 해시로 파일명 생성 (키에 특수문자가 있어도 안전).
+     *
+     * @param {string} key
+     * @returns {string} 파일 절대 경로
+     * @private
+     */
+    _filePath(key) {
+        const fullKey = `${this._prefix}${key}`;
+        const hash = createHash('sha256').update(fullKey).digest('hex');
+        return path.join(this._dir, `${hash}.json`);
+    }
+
+    /**
+     * 캐시 값 조회
+     *
+     * 파일을 읽어 만료 여부를 확인하고 값을 반환.
+     *
+     * @param {string} key
+     * @returns {Promise<*|null>}
+     */
+    async get(key) {
+        const filePath = this._filePath(key);
+        try {
+            const raw = await fs.readFile(filePath, 'utf8');
+            const entry = JSON.parse(raw);
+
+            // 만료 확인
+            if (entry.expires > 0 && entry.expires < Date.now()) {
+                // 만료된 파일 삭제 (비동기, 에러 무시)
+                fs.unlink(filePath).catch(() => {});
+                return null;
+            }
+
+            return entry.value;
+        } catch {
+            return null; // 파일 없거나 파싱 실패
+        }
+    }
+
+    /**
+     * 캐시 값 저장
+     *
+     * @param {string} key
+     * @param {*} value - JSON 직렬화 가능한 값
+     * @param {number} ttl - TTL (초)
+     * @returns {Promise<void>}
+     */
+    async set(key, value, ttl) {
+        const filePath = this._filePath(key);
+        const entry = {
+            key: `${this._prefix}${key}`, // 디버깅용 원본 키 보존
+            value,
+            expires: ttl > 0 ? Date.now() + (ttl * 1000) : 0, // 0이면 무기한
+            created_at: Date.now(),
+        };
+        await fs.writeFile(filePath, JSON.stringify(entry), 'utf8');
+    }
+
+    /**
+     * 캐시 키 존재 여부
+     *
+     * @param {string} key
+     * @returns {Promise<boolean>}
+     */
+    async has(key) {
+        const value = await this.get(key); // get()이 만료 체크도 수행
+        return value !== null;
+    }
+
+    /**
+     * 캐시 키 삭제
+     *
+     * @param {string} key
+     * @returns {Promise<void>}
+     */
+    async delete(key) {
+        const filePath = this._filePath(key);
+        await fs.unlink(filePath).catch(() => {});
+    }
+
+    /**
+     * 패턴 기반 캐시 삭제
+     *
+     * 파일 캐시에서는 모든 파일을 순회하며 키 매칭 수행.
+     * 와일드카드 '*'을 정규식으로 변환.
+     *
+     * @param {string} pattern - 키 패턴 (예: 'user:*')
+     * @returns {Promise<number>} 삭제된 키 수
+     */
+    async deletePattern(pattern) {
+        const fullPattern = `${this._prefix}${pattern}`;
+        // 와일드카드 → 정규식 변환
+        const regex = new RegExp('^' + fullPattern.replace(/\*/g, '.*') + '$');
+
+        let deleted = 0;
+        try {
+            const files = await fs.readdir(this._dir);
+            for (const file of files) {
+                if (!file.endsWith('.json')) continue;
+                const filePath = path.join(this._dir, file);
+                try {
+                    const raw = await fs.readFile(filePath, 'utf8');
+                    const entry = JSON.parse(raw);
+                    if (entry.key && regex.test(entry.key)) {
+                        await fs.unlink(filePath);
+                        deleted++;
+                    }
+                } catch {
+                    // 파싱 실패 파일 무시
+                }
+            }
+        } catch {
+            // 디렉토리 없으면 무시
+        }
+        return deleted;
+    }
+
+    /**
+     * 전체 캐시 플러시
+     *
+     * @returns {Promise<void>}
+     */
+    async flush() {
+        try {
+            const files = await fs.readdir(this._dir);
+            const unlinkPromises = files
+                .filter(f => f.endsWith('.json'))
+                .map(f => fs.unlink(path.join(this._dir, f)).catch(() => {}));
+            await Promise.all(unlinkPromises);
+        } catch {
+            // 디렉토리 없으면 무시
+        }
+    }
+
+    /**
+     * 만료 캐시 파일 정리 (Garbage Collection)
+     *
+     * @returns {Promise<number>} 삭제된 파일 수
+     * @private
+     */
+    async _gc() {
+        let cleaned = 0;
+        try {
+            const files = await fs.readdir(this._dir);
+            const now = Date.now();
+
+            for (const file of files) {
+                if (!file.endsWith('.json')) continue;
+                const filePath = path.join(this._dir, file);
+                try {
+                    const raw = await fs.readFile(filePath, 'utf8');
+                    const entry = JSON.parse(raw);
+                    if (entry.expires > 0 && entry.expires < now) {
+                        await fs.unlink(filePath);
+                        cleaned++;
+                    }
+                } catch {
+                    // 손상된 파일 삭제
+                    await fs.unlink(filePath).catch(() => {});
+                    cleaned++;
+                }
+            }
+        } catch {
+            // 디렉토리 없으면 무시
+        }
+        return cleaned;
+    }
+
+    /**
+     * 드라이버 종료 — GC 타이머 해제
+     *
+     * @returns {Promise<void>}
+     */
+    async disconnect() {
+        if (this._gcTimer) {
+            clearInterval(this._gcTimer);
+            this._gcTimer = null;
+        }
+    }
+}

package/lib/cache/drivers/RedisDriver.js

@@ -0,0 +1,166 @@
+/**
+ * RedisDriver — Redis 기반 캐시 드라이버
+ *
+ * ioredis를 사용하여 Redis에 캐시 데이터를 저장.
+ * 값은 JSON 직렬화하여 저장하고, TTL은 SETEX로 관리.
+ * prefix로 네임스페이스를 분리하여 다른 데이터와 충돌 방지.
+ *
+ * @see lib/cache/CacheManager.js
+ */
+export default class RedisDriver {
+    /**
+     * @param {object} opts
+     * @param {string} opts.url - Redis 접속 URL (예: redis://:password@localhost:6379)
+     * @param {string} [opts.prefix] - 캐시 키 접두사
+     */
+    constructor(opts = {}) {
+        /** @type {string} Redis URL */
+        this._url = opts.url || 'redis://localhost:6379';
+
+        /** @type {string} 키 접두사 (구분자 ':' 포함) */
+        this._prefix = opts.prefix ? `${opts.prefix}:` : '';
+
+        /** @type {import('ioredis').default | null} Redis 클라이언트 */
+        this._client = null;
+    }
+
+    /**
+     * Redis 연결
+     *
+     * @returns {Promise<void>}
+     */
+    async connect() {
+        // ioredis 동적 import (peerDependency)
+        const { default: Redis } = await import('ioredis');
+        this._client = new Redis(this._url, {
+            maxRetriesPerRequest: 3,      // 요청당 재시도 횟수
+            retryStrategy: (times) => {
+                if (times > 5) return null; // 5회 초과 시 재연결 중단
+                return Math.min(times * 200, 2000); // 최대 2초 간격 재시도
+            },
+            lazyConnect: false,           // 즉시 연결
+        });
+
+        // 연결 에러 무음 처리 (로깅만)
+        this._client.on('error', (err) => {
+            console.error(`[CacheManager:Redis] ${err.message}`);
+        });
+    }
+
+    /**
+     * 전체 키 생성 (접두사 + 키)
+     *
+     * @param {string} key
+     * @returns {string}
+     * @private
+     */
+    _key(key) {
+        return `${this._prefix}${key}`;
+    }
+
+    /**
+     * 캐시 값 조회
+     *
+     * @param {string} key
+     * @returns {Promise<*|null>} 역직렬화된 값 또는 null
+     */
+    async get(key) {
+        const raw = await this._client.get(this._key(key));
+        if (raw === null) return null;
+        try {
+            return JSON.parse(raw);
+        } catch {
+            return raw; // JSON 파싱 실패 시 문자열 그대로 반환
+        }
+    }
+
+    /**
+     * 캐시 값 저장
+     *
+     * @param {string} key
+     * @param {*} value - JSON 직렬화 가능한 값
+     * @param {number} ttl - TTL (초)
+     * @returns {Promise<void>}
+     */
+    async set(key, value, ttl) {
+        const serialized = JSON.stringify(value);
+        if (ttl > 0) {
+            await this._client.setex(this._key(key), ttl, serialized);
+        } else {
+            await this._client.set(this._key(key), serialized);
+        }
+    }
+
+    /**
+     * 캐시 키 존재 여부
+     *
+     * @param {string} key
+     * @returns {Promise<boolean>}
+     */
+    async has(key) {
+        const exists = await this._client.exists(this._key(key));
+        return exists === 1;
+    }
+
+    /**
+     * 캐시 키 삭제
+     *
+     * @param {string} key
+     * @returns {Promise<void>}
+     */
+    async delete(key) {
+        await this._client.del(this._key(key));
+    }
+
+    /**
+     * 패턴 기반 캐시 삭제
+     *
+     * SCAN 명령으로 키를 순회하며 삭제 (KEYS 대신 SCAN 사용 — 프로덕션 안전).
+     *
+     * @param {string} pattern - 키 패턴 (예: 'user:*')
+     * @returns {Promise<number>} 삭제된 키 수
+     */
+    async deletePattern(pattern) {
+        const fullPattern = this._key(pattern);
+        let deleted = 0;
+        let cursor = '0';
+
+        do {
+            const [nextCursor, keys] = await this._client.scan(cursor, 'MATCH', fullPattern, 'COUNT', 100);
+            cursor = nextCursor;
+            if (keys.length > 0) {
+                await this._client.del(...keys);
+                deleted += keys.length;
+            }
+        } while (cursor !== '0');
+
+        return deleted;
+    }
+
+    /**
+     * 전체 캐시 플러시 (prefix 범위)
+     *
+     * @returns {Promise<void>}
+     */
+    async flush() {
+        if (this._prefix) {
+            // prefix가 있으면 해당 범위만 삭제
+            await this.deletePattern('*');
+        } else {
+            // prefix 없으면 FLUSHDB (주의: 전체 DB 삭제)
+            await this._client.flushdb();
+        }
+    }
+
+    /**
+     * Redis 연결 종료
+     *
+     * @returns {Promise<void>}
+     */
+    async disconnect() {
+        if (this._client) {
+            await this._client.quit();
+            this._client = null;
+        }
+    }
+}

package/lib/core/Application.js

@@ -28,6 +28,7 @@ import Scheduler from '../schedule/Scheduler.js';
 import Queue from '../schedule/Queue.js';
 import Storage from '../services/Storage.js';
 import ConnectionManager from '../database/ConnectionManager.js';
+import CacheManager from '../cache/CacheManager.js';
 import SqlModel from '../database/SqlModel.js';
 import MongoModel from '../database/MongoModel.js';
 import WorkerPool from '../schedule/WorkerPool.js';
@@ -283,7 +284,7 @@ export default class Application {
         // 2. i18n 로드 (04-bootstrap-lifecycle.md)
         await this.i18n.load();
 
-        // 3. Scheduler / Queue / Storage 초기화
+        // 3. Scheduler / Queue / Storage / Cache 초기화
         this._scheduler = new Scheduler(this);
         this._queue = new Queue(this, { driver: this.config.get('queue.driver', 'memory') });
         this.storage = new Storage({
@@ -292,6 +293,24 @@ export default class Application {
             fileHelper: this.file,
         });
 
+        // 캐시 매니저 초기화 (cache 설정이 있을 때만)
+        const cacheConfig = this.config.get('app.cache');
+        if (cacheConfig?.driver) {
+            this._cacheManager = new CacheManager({
+                ...cacheConfig,
+                file_dir: cacheConfig.file_dir
+                    ? path.resolve(this.baseDir, cacheConfig.file_dir)
+                    : path.resolve(this.baseDir, './storage/cache'),
+            });
+            try {
+                await this._cacheManager.init();
+                this.logger.info(`[Cache] ${cacheConfig.driver} 드라이버 초기화 완료`);
+            } catch (err) {
+                this.logger.warn(`[Cache] 초기화 실패 (${cacheConfig.driver}): ${err.message}`);
+                this._cacheManager = null;
+            }
+        }
+
         // 4. Phase 1: 공유 리소스 로드 (database/models, shared/events,jobs,workers)
         const sharedLoader = new AutoLoader(this, this.baseDir, { mode: 'shared' });
         await sharedLoader.load();
@@ -336,6 +355,7 @@ export default class Application {
             if (dbConfig.connections) {
                 this._connectionManager.configure(dbConfig);
                 SqlModel.setConnectionManager(this._connectionManager);
+                SqlModel.setModelRegistry(this.db);    // relation eager-loading용 레지스트리 주입
                 MongoModel.setConnectionManager(this._connectionManager);
             }
         }
@@ -1268,6 +1288,11 @@ export default class Application {
                 try { await this._connectionManager.closeAll(); } catch {}
             }
 
+            // 3-0. 캐시 매니저 종료
+            if (this._cacheManager) {
+                try { await this._cacheManager.disconnect(); } catch {}
+            }
+
             // 3-1. Worker 종료
             if (this._workerPool) {
                 try { await this._workerPool.terminate(); } catch {}

package/lib/core/Base.js

@@ -61,4 +61,7 @@ export default class Base {
 
     /** @returns {import('./I18nHelper.js').default} */
     get i18n() { return this.app.i18n; }
+
+    /** @returns {import('../cache/CacheManager.js').default|null} 캐시 매니저 */
+    get cache() { return this.app._cacheManager || null; }
 }