create-entity-app-server 0.0.3

package/src/system/cache/drivers/redis.ts

@@ -0,0 +1,109 @@
+/**
+ * Cache Redis 드라이버
+ * ioredis 를 동적으로 import 합니다 (optionalDependencies).
+ *
+ * ioredis 가 설치되어 있지 않으면 연결 시 오류가 발생합니다:
+ *   npm install ioredis
+ */
+
+import type { CacheStore, CacheDriver, RedisCacheConfig } from "../types.ts";
+
+type RedisLike = {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, exArg: "EX", ttl: number): Promise<unknown>;
+    set(key: string, value: string): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    exists(key: string): Promise<number>;
+    flushdb(): Promise<unknown>;
+    dbsize(): Promise<number>;
+    quit(): Promise<unknown>;
+};
+
+export class RedisDriver implements CacheStore {
+    readonly driver: CacheDriver = "redis";
+
+    private client!: RedisLike;
+    private readonly prefix: string;
+    private readonly defaultTtlMs: number;
+    private _size = 0;
+
+    constructor(
+        private readonly config: RedisCacheConfig,
+        defaultTtlSeconds = 3600,
+    ) {
+        this.prefix = config.key_prefix ?? "gw:";
+        this.defaultTtlMs = defaultTtlSeconds * 1000;
+    }
+
+    /** Redis 클라이언트를 생성하고 연결한다 */
+    async connect(): Promise<void> {
+        let Redis: new (opts: object) => RedisLike;
+        try {
+            // @ts-ignore — ioredis 타입은 런타임에 확인
+            const mod = await import("ioredis");
+            Redis = (mod.default ?? mod) as new (opts: object) => RedisLike;
+        } catch {
+            throw new Error(
+                "[Cache] Redis 드라이버를 사용하려면 ioredis 를 설치하세요: npm install ioredis",
+            );
+        }
+
+        this.client = new Redis({
+            host: this.config.host ?? "localhost",
+            port: this.config.port ?? 6379,
+            password: this.config.password || undefined,
+            db: this.config.db ?? 0,
+            connectTimeout: this.config.connect_timeout_ms ?? 5000,
+            lazyConnect: false,
+        });
+        this._size = await this.client.dbsize();
+    }
+
+    async disconnect(): Promise<void> {
+        await this.client.quit();
+    }
+
+    async get<T = unknown>(key: string): Promise<T | null> {
+        const raw = await this.client.get(this.prefix + key);
+        if (raw === null) return null;
+        return JSON.parse(raw) as T;
+    }
+
+    async set<T = unknown>(
+        key: string,
+        value: T,
+        ttlMs?: number,
+    ): Promise<void> {
+        const raw = JSON.stringify(value);
+        const effectiveTtl = ttlMs ?? this.defaultTtlMs;
+        if (effectiveTtl === 0) {
+            await this.client.set(this.prefix + key, raw);
+        } else {
+            const ttlSec = Math.max(1, Math.ceil(effectiveTtl / 1000));
+            await this.client.set(this.prefix + key, raw, "EX", ttlSec);
+        }
+    }
+
+    async del(key: string): Promise<void> {
+        await this.client.del(this.prefix + key);
+    }
+
+    async has(key: string): Promise<boolean> {
+        const n = await this.client.exists(this.prefix + key);
+        return n > 0;
+    }
+
+    async flush(): Promise<void> {
+        await this.client.flushdb();
+    }
+
+    /** 대략적인 키 수 — 정확한 dbsize()는 비동기이므로 마지막 조회값 반환 */
+    get size(): number {
+        // 백그라운드 갱신 (fire-and-forget)
+        this.client
+            .dbsize()
+            .then((n) => (this._size = n))
+            .catch(() => {});
+        return this._size;
+    }
+}

package/src/system/cache/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Cache 시스템 공개 API
+ *
+ * 사용 예시:
+ * ```ts
+ * import { cache } from "@gateway/api";
+ *
+ * async function handler(req, reply) {
+ *     const cached = await cache().get<User[]>("users:all");
+ *     if (cached) return ok(cached);
+ *
+ *     const users = await fetchUsers();
+ *     await cache().set("users:all", users, 60_000); // TTL: 60초
+ *     return ok(users);
+ * }
+ * ```
+ */
+
+import type { CacheStore } from "./types.ts";
+import { _getCacheStore } from "./_store-ref.ts";
+
+export type { CacheStore, CacheConfig, CacheDriver } from "./types.ts";
+export { default as cachePlugin } from "./plugin.ts";
+
+/**
+ * 전역 캐시 스토어를 반환합니다.
+ *
+ * @example
+ * const store = cache();
+ * const data = await store.get<MyType>("key");
+ * await store.set("key", data, 30_000); // 30초 TTL
+ * await store.del("key");
+ * await store.flush();
+ */
+export function cache(): CacheStore {
+    const store = _getCacheStore();
+    if (!store) {
+        throw new Error(
+            "[Cache] 캐시가 초기화되지 않았습니다. 서버 시작 전에 호출되었을 수 있습니다.",
+        );
+    }
+    return store;
+}

package/src/system/cache/namespaced.ts

@@ -0,0 +1,79 @@
+/**
+ * NamespacedCacheStore
+ *
+ * 실제 드라이버 스토어를 감싸는 래퍼.
+ *
+ * 키 변환 규칙:
+ *   stored_key = sha256( namespace + ":" + originalKey )
+ *
+ * - 멀티인스턴스 배포 시 namespace(앱 이름 등)를 다르게 설정하면 키 충돌이 없어집니다.
+ * - 긴 키나 특수문자가 포함된 키도 고정길이(64자) hex로 정규화됩니다.
+ */
+
+import { createHash } from "node:crypto";
+import type { CacheStore, CacheDriver } from "./types.ts";
+
+/**
+ * namespace + key → sha256 hex (64자)
+ * 결과를 인메모리 Map 에 캐시하여 반복 해시를 피한다.
+ *
+ * 일반적으로 키 종류는 수천 개 이내이므로 메모리 부담이 미미하다.
+ */
+const _keyCache = new Map<string, string>();
+const _KEY_CACHE_MAX = 10_000;
+
+function resolveKey(namespace: string, key: string): string {
+    const raw = `${namespace}:${key}`;
+    let hashed = _keyCache.get(raw);
+    if (hashed) return hashed;
+    hashed = createHash("sha256").update(raw).digest("hex");
+    if (_keyCache.size >= _KEY_CACHE_MAX) {
+        // FIFO 간단 정리 — 오래된 절반 제거
+        const it = _keyCache.keys();
+        for (let i = 0; i < _KEY_CACHE_MAX / 2; i++) it.next();
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        for (const k of [..._keyCache.keys()].slice(0, _KEY_CACHE_MAX / 2)) {
+            _keyCache.delete(k);
+        }
+    }
+    _keyCache.set(raw, hashed);
+    return hashed;
+}
+
+export class NamespacedCacheStore implements CacheStore {
+    private readonly inner: CacheStore;
+    private readonly ns: string;
+
+    constructor(inner: CacheStore, namespace: string) {
+        this.inner = inner;
+        this.ns = namespace;
+    }
+
+    get<T = unknown>(key: string): Promise<T | null> {
+        return this.inner.get<T>(resolveKey(this.ns, key));
+    }
+
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void> {
+        return this.inner.set<T>(resolveKey(this.ns, key), value, ttlMs);
+    }
+
+    del(key: string): Promise<void> {
+        return this.inner.del(resolveKey(this.ns, key));
+    }
+
+    has(key: string): Promise<boolean> {
+        return this.inner.has(resolveKey(this.ns, key));
+    }
+
+    flush(): Promise<void> {
+        return this.inner.flush();
+    }
+
+    get size(): number {
+        return this.inner.size;
+    }
+
+    get driver(): CacheDriver {
+        return this.inner.driver;
+    }
+}

package/src/system/cache/plugin.ts

@@ -0,0 +1,59 @@
+/**
+ * Cache 시스템 Fastify 플러그인
+ * app.cache 데코레이터를 등록합니다.
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { loadCacheConfig } from "./config.ts";
+import { MemoryDriver } from "./drivers/memory.ts";
+import { RedisDriver } from "./drivers/redis.ts";
+import { MemcachedDriver } from "./drivers/memcached.ts";
+import { NamespacedCacheStore } from "./namespaced.ts";
+import type { CacheStore } from "./types.ts";
+import { _setCacheStore } from "./_store-ref.ts";
+import { logger, logFmt } from "../config/env.ts";
+import { serverConfig } from "../config/server.ts";
+
+async function cachePlugin(app: FastifyInstance): Promise<void> {
+    const config = loadCacheConfig();
+    const driver = config.driver ?? "memory";
+
+    let store: CacheStore;
+
+    if (driver === "redis") {
+        const redisDriver = new RedisDriver(
+            config.redis ?? {},
+            config.default_ttl_seconds,
+        );
+        await redisDriver.connect();
+        store = redisDriver;
+
+        app.addHook("onClose", async () => {
+            await redisDriver.disconnect();
+            logger.info(logFmt.cache("redis", "(closed)"));
+        });
+    } else if (driver === "memcached") {
+        const memcachedDriver = new MemcachedDriver(
+            config.memcached ?? {},
+            config.default_ttl_seconds,
+        );
+        await memcachedDriver.connect();
+        store = memcachedDriver;
+
+        app.addHook("onClose", async () => {
+            memcachedDriver.disconnect();
+            logger.info(logFmt.cache("memcached", "(closed)"));
+        });
+    } else {
+        store = new MemoryDriver(config.memory, config.default_ttl_seconds);
+    }
+
+    const namespace = serverConfig.namespace;
+    const namespacedStore = new NamespacedCacheStore(store, namespace);
+
+    app.decorate("cache", namespacedStore);
+    _setCacheStore(namespacedStore);
+}
+
+export default fp(cachePlugin, { name: "cache" });

package/src/system/cache/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Cache 시스템 타입 정의
+ */
+
+// ─── Driver 식별자 ────────────────────────────────────────────────────────────
+
+export type CacheDriver = "memory" | "redis" | "memcached";
+
+// ─── Config 타입 ─────────────────────────────────────────────────────────────
+
+export interface MemoryCacheConfig {
+    /** 최대 항목 수 (기본 10000) */
+    max_entries?: number;
+}
+
+export interface RedisCacheConfig {
+    host?: string;
+    port?: number;
+    password?: string;
+    /** Redis DB 번호 (기본 0) */
+    db?: number;
+    /** 모든 키에 붙일 접두사 (기본 "gw:") */
+    key_prefix?: string;
+    /** 연결 타임아웃 ms (기본 5000) */
+    connect_timeout_ms?: number;
+}
+
+export interface MemcachedCacheConfig {
+    host?: string;
+    port?: number;
+    /** SASL 인증 사용자명 (선택) */
+    username?: string;
+    /** SASL 인증 비밀번호 (선택) */
+    password?: string;
+}
+
+export interface CacheConfig {
+    /** 캐시 드라이버 (기본 "memory") */
+    driver?: CacheDriver;
+    /** 기본 TTL 초 (기본 3600, 0 = 만료 없음) */
+    default_ttl_seconds?: number;
+    memory?: MemoryCacheConfig;
+    redis?: RedisCacheConfig;
+    memcached?: MemcachedCacheConfig;
+}
+
+// ─── Store 인터페이스 ─────────────────────────────────────────────────────────
+
+/**
+ * 캐시 저장소 인터페이스.
+ * driver 가 바뀌어도 동일한 API 로 사용합니다.
+ *
+ * 예시:
+ * ```ts
+ * const store = cache();
+ * const data = await store.get<MyType>("my-key");
+ * await store.set("my-key", data, 60_000);
+ * ```
+ */
+export interface CacheStore {
+    /** 키로 캐시를 조회합니다. 없거나 만료되면 null 반환 */
+    get<T = unknown>(key: string): Promise<T | null>;
+
+    /** 캐시를 저장합니다. ttlMs 미지정 시 기본 TTL 사용 */
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+
+    /** 키를 삭제합니다 */
+    del(key: string): Promise<void>;
+
+    /** 키 존재 여부를 확인합니다 */
+    has(key: string): Promise<boolean>;
+
+    /** 전체 캐시를 비웁니다 */
+    flush(): Promise<void>;
+
+    /** 현재 항목 수 */
+    readonly size: number;
+
+    /** 드라이버 이름 */
+    readonly driver: CacheDriver;
+}

package/src/system/config/config-path.ts

@@ -0,0 +1,20 @@
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+let cachedConfigsDir: string | null = null;
+
+/** configs 디렉토리 절대경로를 반환한다. */
+export function resolveConfigsDir(): string {
+    if (cachedConfigsDir) return cachedConfigsDir;
+
+    const base = path.dirname(fileURLToPath(import.meta.url));
+    const prodCandidate = path.resolve(base, "..", "configs");
+    if (existsSync(prodCandidate)) {
+        cachedConfigsDir = prodCandidate;
+        return prodCandidate;
+    }
+
+    cachedConfigsDir = path.resolve(base, "..", "..", "..", "configs");
+    return cachedConfigsDir;
+}

package/src/system/config/cors.ts

@@ -0,0 +1,49 @@
+import { existsSync } from "fs";
+import path from "path";
+import { z } from "zod";
+import { resolveConfigsDir } from "./config-path.ts";
+import { loadJsonConfig } from "./json-config.ts";
+
+const corsConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    origins: z.array(z.string().url()).default([]),
+    allow_localhost: z.boolean().default(true),
+    credentials: z.boolean().default(true),
+    allowed_headers: z.array(z.string()).optional(),
+    exposed_headers: z.array(z.string()).optional(),
+    max_age: z.number().int().positive().optional(),
+});
+
+export interface CorsConfig {
+    enabled: boolean;
+    origins: string[];
+    allowLocalhost: boolean;
+    credentials: boolean;
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    maxAge?: number;
+}
+
+/** CORS 설정을 설정 파일에서 로드한다 */
+export function loadCorsConfig(): CorsConfig {
+    const defaults: CorsConfig = {
+        enabled: true,
+        origins: [],
+        allowLocalhost: true,
+        credentials: true,
+    };
+
+    const raw = loadJsonConfig<Record<string, unknown>>("cors.json");
+    if (!raw) return defaults;
+
+    const parsed = corsConfigSchema.parse(raw);
+    return {
+        enabled: parsed.enabled,
+        origins: parsed.origins,
+        allowLocalhost: parsed.allow_localhost !== false,
+        credentials: parsed.credentials,
+        allowedHeaders: parsed.allowed_headers,
+        exposedHeaders: parsed.exposed_headers,
+        maxAge: parsed.max_age,
+    };
+}

package/src/system/config/database.ts

@@ -0,0 +1,190 @@
+import { z } from "zod";
+import {
+    Kysely,
+    MysqlDialect,
+    PostgresDialect,
+    SqliteDialect,
+    type KyselyPlugin,
+    type PluginTransformQueryArgs,
+    type PluginTransformResultArgs,
+} from "kysely";
+import { logger } from "./env.ts";
+import { loadJsonConfig } from "./json-config.ts";
+
+const databaseGroupSchema = z.object({
+    driver: z.enum(["mysql", "mariadb", "tidb", "postgresql", "sqlite"]),
+    host: z.string().optional(),
+    port: z.coerce.number().optional(),
+    database: z.string(),
+    user: z.string().optional(),
+    password: z.string().optional(),
+    maxConnections: z.coerce.number().default(10),
+    idleTimeout: z.coerce.number().default(60000),
+    connectionTimeout: z.coerce.number().default(10000),
+    ssl: z.boolean().optional(),
+    readOnly: z.boolean().default(false),
+});
+
+const databaseConfigSchema = z.object({
+    default: z.string(),
+    /** glob 패턴 목록 — 일치하는 테이블에 쓰기 쿼리 차단 (예: ["entity_*"]) */
+    tableReadOnly: z.array(z.string()).default([]),
+    groups: z.record(databaseGroupSchema),
+});
+
+export type DatabaseGroup = z.infer<typeof databaseGroupSchema>;
+export type DatabaseConfig = z.infer<typeof databaseConfigSchema>;
+
+/** DB 설정 파일(database.json)을 로드하고 파싱한다 */
+export function loadDatabaseConfig(): DatabaseConfig | null {
+    const raw = loadJsonConfig<Record<string, unknown>>("database.json");
+    if (!raw) {
+        logger.warn("configs/database.json not found — DB 직접 접속 비활성화");
+        return null;
+    }
+    return databaseConfigSchema.parse(raw);
+}
+
+// --- Kysely 팩토리 ---
+
+/** MySQL / MariaDB / TiDB 용 Kysely Dialect을 생성한다 (mysql2 호환) */
+async function createMysqlDialect(cfg: DatabaseGroup): Promise<MysqlDialect> {
+    const mysql2 = await import("mysql2");
+    const pool = mysql2.createPool({
+        host: cfg.host,
+        port: cfg.port,
+        database: cfg.database,
+        user: cfg.user,
+        password: cfg.password,
+        connectionLimit: cfg.maxConnections,
+        idleTimeout: cfg.idleTimeout,
+        connectTimeout: cfg.connectionTimeout,
+    });
+    // mysql2 타입과 Kysely MysqlPool 타입 간 minor 불일치 — 런타임 호환
+    return new MysqlDialect({ pool: pool as any });
+}
+
+/** PostgreSQL 용 Kysely Dialect을 생성한다 */
+async function createPgDialect(cfg: DatabaseGroup): Promise<PostgresDialect> {
+    const pg = await import("pg");
+    const pool = new pg.Pool({
+        host: cfg.host,
+        port: cfg.port,
+        database: cfg.database,
+        user: cfg.user,
+        password: cfg.password,
+        max: cfg.maxConnections,
+        idleTimeoutMillis: cfg.idleTimeout,
+        connectionTimeoutMillis: cfg.connectionTimeout,
+        ssl: cfg.ssl ? { rejectUnauthorized: false } : undefined,
+    });
+    return new PostgresDialect({ pool });
+}
+
+/** SQLite 용 Kysely Dialect을 생성한다 */
+async function createSqliteDialect(cfg: DatabaseGroup): Promise<SqliteDialect> {
+    const BetterSqlite3 = (await import("better-sqlite3")).default;
+    const db = new BetterSqlite3(cfg.database, {
+        readonly: cfg.readOnly,
+    });
+    return new SqliteDialect({ database: db });
+}
+
+// ─── tableReadOnly 플러그인 ────────────────────────────────────────────────────
+
+/** glob 패턴을 정규식으로 변환 (예: "entity_*" → /^entity_.*$/i) */
+function globToRegex(pattern: string): RegExp {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`, "i");
+}
+
+/** 쓰기 쿼리 대상 테이블명을 AST에서 추출한다 */
+function extractWriteTableName(node: any): string | null {
+    switch (node.kind) {
+        case "InsertQueryNode":
+            return node.into?.table?.identifier?.name ?? null;
+        case "UpdateQueryNode":
+            return node.table?.table?.identifier?.name ?? null;
+        case "DeleteQueryNode":
+            return node.from?.froms?.[0]?.table?.identifier?.name ?? null;
+        default:
+            return null;
+    }
+}
+
+/**
+ * 지정된 glob 패턴과 일치하는 테이블에 INSERT / UPDATE / DELETE를 차단하는
+ * Kysely 플러그인을 생성합니다.
+ *
+ * 예: createTableReadOnlyPlugin(["entity_*"]) → entity_ 로 시작하는 테이블 쓰기 차단
+ */
+export function createTableReadOnlyPlugin(patterns: string[]): KyselyPlugin {
+    const isFullReadOnly = patterns.length === 1 && patterns[0] === "*";
+    const rules = patterns.map((p) => ({ pattern: p, regex: globToRegex(p) }));
+
+    return {
+        transformQuery(args: PluginTransformQueryArgs) {
+            const tableName = extractWriteTableName(args.node);
+            if (tableName) {
+                if (isFullReadOnly) {
+                    throw new Error(
+                        "Database is configured as readOnly — write operation blocked",
+                    );
+                }
+                for (const { pattern, regex } of rules) {
+                    if (regex.test(tableName)) {
+                        throw new Error(
+                            `테이블 "${tableName}"은 읽기 전용입니다 — 쓰기 쿼리 차단 (패턴: "${pattern}")`,
+                        );
+                    }
+                }
+            }
+            return args.node;
+        },
+        async transformResult(args: PluginTransformResultArgs) {
+            return args.result;
+        },
+    };
+}
+
+type DialectFactory = (
+    cfg: DatabaseGroup,
+) => Promise<MysqlDialect | PostgresDialect | SqliteDialect>;
+
+const dialectFactory: Record<string, DialectFactory> = {
+    mysql: createMysqlDialect,
+    tidb: createMysqlDialect,
+    mariadb: createMysqlDialect, // mysql2 가 MariaDB 완전 호환
+    postgresql: createPgDialect,
+    sqlite: createSqliteDialect,
+};
+
+/** 드라이버에 맞는 Kysely 인스턴스를 생성한다 */
+export async function createKyselyDb(
+    cfg: DatabaseGroup,
+    tableReadOnlyPatterns: string[] = [],
+): Promise<Kysely<any>> {
+    const factory = dialectFactory[cfg.driver];
+    if (!factory) {
+        throw new Error(`Unsupported database driver: ${cfg.driver}`);
+    }
+
+    const dialect = await factory(cfg);
+
+    let db = new Kysely<any>({ dialect });
+
+    // readOnly 모드: 모든 테이블에 쓰기 차단 ("*" glob 으로 위임)
+    if (cfg.readOnly) {
+        db = db.withPlugin(createTableReadOnlyPlugin(["*"]));
+    }
+
+    // tableReadOnly: 특정 테이블 패턴에 쓰기 차단
+    if (tableReadOnlyPatterns.length > 0) {
+        db = db.withPlugin(createTableReadOnlyPlugin(tableReadOnlyPatterns));
+    }
+
+    return db;
+}

package/src/system/config/entity-server.ts

@@ -0,0 +1,8 @@
+import { EntityServerClient } from "entity-server-client";
+import { env } from "./env.ts";
+
+export const entityServer = new EntityServerClient({
+    baseUrl: env.ENTITY_SERVER_URL,
+    apiKey: env.ENTITY_API_KEY,
+    hmacSecret: env.ENTITY_HMAC_SECRET,
+});

package/src/system/config/env-substitution.ts

@@ -0,0 +1,4 @@
+/** 문자열 내 `${VAR}` 플레이스홀더를 process.env 값으로 치환한다. */
+export function substituteEnvVars(str: string): string {
+    return str.replace(/\$\{(\w+)\}/g, (_, key) => process.env[key] ?? "");
+}

package/src/system/config/env.ts

@@ -0,0 +1,30 @@
+/**
+ * 환경변수 검증 — Zod 스키마
+ *
+ * dotenv 는 server.ts 에서 이미 로드됨 (이 모듈이 serverConfig 를 import 하므로 순서 보장)
+ */
+
+import { z } from "zod";
+import "./server.ts"; // dotenv 로드 순서 보장
+
+const envSchema = z.object({
+    NODE_ENV: z
+        .enum(["development", "production", "test"])
+        .default("development"),
+
+    ENTITY_SERVER_URL: z.string().url(),
+    ENTITY_API_KEY: z.string().min(1),
+    ENTITY_HMAC_SECRET: z
+        .string()
+        .min(32, "ENTITY_HMAC_SECRET must be at least 32 characters"),
+
+    JWT_SECRET: z.string().min(32, "JWT_SECRET must be at least 32 characters"),
+});
+
+export const env = envSchema.parse(process.env);
+export type Env = z.infer<typeof envSchema>;
+export const isDev = env.NODE_ENV === "development";
+
+// 기존 호환: logger, logFmt, accessLogger 를 이 모듈에서 재내보냄
+export { logger, accessLogger } from "../logging/logger.ts";
+export { logFmt } from "../logging/log-format.ts";