create-entity-app-server 0.0.3

package/src/app/schedules/kobc_freight_sync/index.ts

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+    createCron,
+    acquireLock,
+    releaseLock,
+    logger,
+    type CronHandle,
+} from "@gateway/api";
+import { loadKobcFreightConfig } from "@app/plugins/kobc_freight/config.ts";
+import { KobcFreightService } from "@app/plugins/kobc_freight/service.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LOCK_KEY = "kobc_freight_sync";
+const LOCK_TTL = 1800; // 30분
+
+interface ScheduleConfig {
+    enabled?: boolean;
+    cron?: string;
+}
+
+function loadScheduleConfig(): ScheduleConfig {
+    const configPath = join(__dirname, "config.json");
+    if (!existsSync(configPath)) return {};
+    try {
+        return JSON.parse(readFileSync(configPath, "utf-8")) as ScheduleConfig;
+    } catch {
+        return {};
+    }
+}
+
+let cronHandle: CronHandle | null = null;
+
+export function start(): void {
+    const schedCfg = loadScheduleConfig();
+    if (schedCfg.enabled === false) return;
+
+    const pluginConfig = loadKobcFreightConfig();
+    if (!pluginConfig) return;
+
+    const cron = schedCfg.cron ?? "0 6 * * *";
+    const service = new KobcFreightService(pluginConfig);
+
+    cronHandle = createCron({
+        expression: cron,
+        onTick: async () => {
+            const locked = await acquireLock(LOCK_KEY, LOCK_TTL);
+            if (!locked) {
+                logger.warn("kobc_freight sync: already running, skipping");
+                return;
+            }
+            try {
+                logger.info("kobc_freight sync: started");
+                const [kdci, kcci, ncfi, kpli] = await Promise.allSettled([
+                    service.syncRecent(),
+                    service.syncKcci(),
+                    service.syncNcfi(),
+                    service.syncKpliRecent(),
+                ]);
+                logger.info(
+                    {
+                        kdci:
+                            kdci.status === "fulfilled"
+                                ? kdci.value
+                                : kdci.reason,
+                        kcci:
+                            kcci.status === "fulfilled"
+                                ? kcci.value
+                                : kcci.reason,
+                        ncfi:
+                            ncfi.status === "fulfilled"
+                                ? ncfi.value
+                                : ncfi.reason,
+                        kpli:
+                            kpli.status === "fulfilled"
+                                ? kpli.value
+                                : kpli.reason,
+                    },
+                    "kobc_freight sync: completed",
+                );
+            } catch (err) {
+                logger.error({ err }, "kobc_freight sync: unexpected error");
+            } finally {
+                await releaseLock(LOCK_KEY, LOCK_TTL);
+            }
+        },
+    });
+}
+
+export function stop(): void {
+    cronHandle?.stop();
+    cronHandle = null;
+}

package/src/app/schedules/vessel_kr_sync/config.json

@@ -0,0 +1,4 @@
+{
+    "enabled": true,
+    "cron": "0 3 * * *"
+}

package/src/app/schedules/vessel_kr_sync/index.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+    createCron,
+    acquireLock,
+    releaseLock,
+    logger,
+    type CronHandle,
+} from "@gateway/api";
+import { loadVesselKrConfig } from "@app/plugins/vessel_kr/config.ts";
+import { VesselKrService } from "@app/plugins/vessel_kr/service.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LOCK_KEY = "vessel_kr_sync";
+const LOCK_TTL = 1800;
+
+interface ScheduleConfig {
+    enabled?: boolean;
+    cron?: string;
+}
+
+function loadScheduleConfig(): ScheduleConfig {
+    const configPath = join(__dirname, "config.json");
+    if (!existsSync(configPath)) return {};
+    try {
+        return JSON.parse(readFileSync(configPath, "utf-8")) as ScheduleConfig;
+    } catch {
+        return {};
+    }
+}
+
+let cronHandle: CronHandle | null = null;
+
+export function start(): void {
+    const schedCfg = loadScheduleConfig();
+    if (schedCfg.enabled === false) return;
+
+    const pluginConfig = loadVesselKrConfig();
+    if (!pluginConfig) return;
+
+    const cron = schedCfg.cron ?? "0 3 * * *";
+    const service = new VesselKrService(pluginConfig);
+
+    cronHandle = createCron({
+        expression: cron,
+        onTick: async () => {
+            const locked = await acquireLock(LOCK_KEY, LOCK_TTL);
+            if (!locked) {
+                logger.warn("vessel_kr sync: already running, skipping");
+                return;
+            }
+            try {
+                logger.info("vessel_kr sync: started");
+                const { dates, saved, errors } = await service.syncAll();
+                logger.info(
+                    { dates, saved, errors },
+                    "vessel_kr sync: completed",
+                );
+            } catch (err) {
+                logger.error({ err }, "vessel_kr sync: unexpected error");
+            } finally {
+                await releaseLock(LOCK_KEY, LOCK_TTL);
+            }
+        },
+    });
+}
+
+export function stop(): void {
+    cronHandle?.stop();
+    cronHandle = null;
+}

package/src/system/app.ts

@@ -0,0 +1,129 @@
+/// <reference path="./types/fastify.d.ts" />
+
+/**
+ * Fastify 앱 생성 & 플러그인 등록
+ */
+
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+import helmet from "@fastify/helmet";
+import rateLimit from "@fastify/rate-limit";
+
+import { env, logger } from "./config/env.ts";
+import { serverConfig } from "./config/server.ts";
+import { entityServer } from "./config/entity-server.ts";
+import { loadCorsConfig } from "./config/cors.ts";
+import { helmetOptions } from "./config/security.ts";
+import { rateLimitOptions } from "./config/rate-limit.ts";
+
+import authPlugin from "./middleware/auth.ts";
+import csrfPlugin from "./middleware/csrf.ts";
+import packetEncryptPlugin from "./middleware/packet-encrypt.ts";
+import databasePlugin from "./middleware/database.ts";
+import errorHandlerPlugin from "./middleware/error-handler.ts";
+import requestIdPlugin from "./middleware/request-id.ts";
+import accessLogPlugin from "./middleware/access-log.ts";
+import cachePlugin from "./cache/plugin.ts";
+
+import { registerProxyRoutes } from "./proxy/register.ts";
+import { loadHooks } from "./hooks/loader.ts";
+import { registerEntityInterceptor } from "./routes/entity-interceptor.ts";
+import { registerRoutes } from "./routes/loader.ts";
+import { loadExtensionPlugins } from "./middleware/extension-loader.ts";
+import { loadSchedules } from "./scheduler/schedule-loader.ts";
+import type { StartupSummary } from "./startup-banner.ts";
+import { printStartupBanner } from "./startup-banner.ts";
+import { getPacketHealth } from "../app/routes/health/handlers.ts";
+
+/** Fastify 앱 인스턴스를 생성하고 플러그인·라우트를 등록한다 */
+export async function buildApp() {
+    await entityServer.checkHealth();
+
+    const app = Fastify({
+        logger: false, // pino logger를 직접 사용
+        trustProxy: true,
+    });
+
+    // --- 보안/인프라 플러그인 ---
+    const corsConfig = loadCorsConfig();
+    const resolveOrigin = corsConfig.enabled
+        ? (
+              origin: string | undefined,
+              cb: (err: Error | null, allow: boolean) => void,
+          ) => {
+              if (!origin) {
+                  cb(null, true);
+                  return;
+              }
+              const allowed =
+                  (corsConfig.allowLocalhost &&
+                      /^https?:\/\/localhost(:\d+)?$/.test(origin)) ||
+                  corsConfig.origins.includes(origin);
+              cb(null, allowed);
+          }
+        : false;
+    await app.register(cors, {
+        origin: resolveOrigin,
+        credentials: corsConfig.credentials,
+        allowedHeaders: corsConfig.allowedHeaders,
+        exposedHeaders: corsConfig.exposedHeaders,
+        maxAge: corsConfig.maxAge,
+    });
+    await app.register(helmet, helmetOptions);
+    await app.register(rateLimit, rateLimitOptions);
+
+    // --- 시스템 플러그인 ---
+    await app.register(requestIdPlugin);
+    await app.register(accessLogPlugin);
+    await app.register(errorHandlerPlugin);
+    await app.register(cachePlugin);
+    await app.register(authPlugin);
+    await app.register(csrfPlugin);
+    await app.register(packetEncryptPlugin);
+    await app.register(databasePlugin);
+
+    // --- 훅 로드 ---
+    const hookCount = await loadHooks();
+
+    // --- 플러그인 (app/plugins/*/index.ts 자동 탐색) ---
+    const pluginCount = await loadExtensionPlugins(app);
+
+    // --- 엔티티 훅 인터셉터 (프록시보다 먼저 등록 → 우선 매칭) ---
+    await registerEntityInterceptor(app);
+
+    // --- 비즈니스 라우트 (app/routes/) — 프록시보다 먼저 등록해야 우선 매칭됨 ---
+    const routeCount = await registerRoutes(app);
+
+    // --- Packet bootstrap health ---
+    app.get("/v1/health", getPacketHealth);
+
+    // --- 프록시 라우트 (Entity Server) — 위에서 처리되지 않은 경로만 패스스루 ---
+    await registerProxyRoutes(app);
+
+    // --- 스케줄러 (app/schedules/) ---
+    const scheduleCount = (await loadSchedules(app)) ?? 0;
+
+    // --- Health check ---
+    app.get("/health", async () => ({
+        status: "ok",
+        timestamp: new Date().toISOString(),
+        uptime: process.uptime(),
+    }));
+
+    const startupSummary: StartupSummary = {
+        hookCount,
+        pluginCount,
+        routeCount,
+        scheduleCount,
+    };
+
+    app.addHook("onReady", async () => {
+        printStartupBanner(
+            serverConfig.baseUrl ??
+                `http://${serverConfig.host}:${serverConfig.port}`,
+            startupSummary,
+        );
+    });
+
+    return { app, startupSummary };
+}

package/src/system/cache/_store-ref.ts

@@ -0,0 +1,15 @@
+/**
+ * 캐시 store 전역 참조 — 순환 참조 방지용 내부 모듈
+ */
+
+import type { CacheStore } from "./types.ts";
+
+let _store: CacheStore | null = null;
+
+export function _setCacheStore(store: CacheStore): void {
+    _store = store;
+}
+
+export function _getCacheStore(): CacheStore | null {
+    return _store;
+}

package/src/system/cache/config.ts

@@ -0,0 +1,61 @@
+/**
+ * Cache 설정 로더 — configs/cache.json
+ */
+
+import { z } from "zod";
+import { loadJsonConfig } from "../config/json-config.ts";
+import type { CacheConfig } from "./types.ts";
+
+const memoryCacheSchema = z.object({
+    max_entries: z.number().int().positive().optional(),
+});
+
+const redisCacheSchema = z.object({
+    host: z.string().optional(),
+    port: z.number().int().positive().optional(),
+    password: z.string().optional(),
+    db: z.number().int().min(0).optional(),
+    key_prefix: z.string().optional(),
+    connect_timeout_ms: z.number().int().positive().optional(),
+});
+
+const memcachedCacheSchema = z.object({
+    host: z.string().optional(),
+    port: z.number().int().positive().optional(),
+    username: z.string().optional(),
+    password: z.string().optional(),
+});
+
+const cacheConfigSchema = z.object({
+    driver: z.enum(["memory", "redis", "memcached"]).optional(),
+    default_ttl_seconds: z.number().int().min(0).optional(),
+    memory: memoryCacheSchema.optional(),
+    redis: redisCacheSchema.optional(),
+    memcached: memcachedCacheSchema.optional(),
+});
+
+const DEFAULTS: CacheConfig = {
+    driver: "memory",
+    default_ttl_seconds: 3600,
+    memory: {
+        max_entries: 10000,
+    },
+};
+
+/** cache.json 을 로드한다. 파일이 없으면 기본값을 반환한다 */
+export function loadCacheConfig(): CacheConfig {
+    const raw = loadJsonConfig<Record<string, unknown>>("cache.json");
+    if (!raw) return DEFAULTS;
+
+    const parsed = cacheConfigSchema.parse(raw);
+    return {
+        driver: parsed.driver ?? DEFAULTS.driver,
+        default_ttl_seconds:
+            parsed.default_ttl_seconds ?? DEFAULTS.default_ttl_seconds,
+        memory: parsed.memory
+            ? { ...DEFAULTS.memory, ...parsed.memory }
+            : DEFAULTS.memory,
+        redis: parsed.redis,
+        memcached: parsed.memcached,
+    };
+}

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

@@ -0,0 +1,135 @@
+/**
+ * Cache Memcached 드라이버
+ * memjs 를 동적으로 import 합니다 (optionalDependencies).
+ *
+ * memjs 가 설치되어 있지 않으면 연결 시 오류가 발생합니다:
+ *   npm install memjs
+ *
+ * memcached 는 키 목록 조회 API 가 없으므로 size 는 항상 -1 을 반환합니다.
+ */
+
+import type {
+    CacheStore,
+    CacheDriver,
+    MemcachedCacheConfig,
+} from "../types.ts";
+
+// memjs 콜백 기반 API 최소 타입 선언
+type MemjsClient = {
+    get(key: string, cb: (err: Error | null, val: Buffer | null) => void): void;
+    set(
+        key: string,
+        value: string,
+        opts: { expires: number },
+        cb: (err: Error | null, val: boolean | null) => void,
+    ): void;
+    delete(key: string, cb: (err: Error | null, val: boolean) => void): void;
+    flush(cb: (err: Error | null) => void): void;
+    quit(): void;
+};
+
+type MemjsModule = {
+    Client: {
+        create(servers: string, opts?: object): MemjsClient;
+    };
+};
+
+export class MemcachedDriver implements CacheStore {
+    readonly driver: CacheDriver = "memcached";
+
+    private client!: MemjsClient;
+    private readonly defaultTtlMs: number;
+    private readonly servers: string;
+    private readonly username?: string;
+    private readonly password?: string;
+
+    constructor(config: MemcachedCacheConfig = {}, defaultTtlSeconds = 3600) {
+        const host = config.host ?? "localhost";
+        const port = config.port ?? 11211;
+        this.servers = `${host}:${port}`;
+        this.username = config.username;
+        this.password = config.password;
+        this.defaultTtlMs = defaultTtlSeconds * 1000;
+    }
+
+    /** memjs 클라이언트를 생성한다 */
+    async connect(): Promise<void> {
+        let memjs: MemjsModule;
+        try {
+            // @ts-ignore — memjs 는 타입 선언이 없으므로 무시
+            const mod = await import("memjs");
+            memjs = (mod.default ?? mod) as MemjsModule;
+        } catch {
+            throw new Error(
+                "[Cache] Memcached 드라이버를 사용하려면 memjs 를 설치하세요: npm install memjs",
+            );
+        }
+
+        this.client = memjs.Client.create(this.servers, {
+            username: this.username,
+            password: this.password,
+        });
+    }
+
+    disconnect(): void {
+        this.client.quit();
+    }
+
+    get<T = unknown>(key: string): Promise<T | null> {
+        return new Promise((resolve, reject) => {
+            this.client.get(key, (err, val) => {
+                if (err) return reject(err);
+                if (val === null) return resolve(null);
+                try {
+                    resolve(JSON.parse(val.toString()) as T);
+                } catch {
+                    resolve(null);
+                }
+            });
+        });
+    }
+
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void> {
+        const effectiveTtl = ttlMs ?? this.defaultTtlMs;
+        // memcached expires: 초 단위, 0 = 만료 없음
+        const expires =
+            effectiveTtl === 0
+                ? 0
+                : Math.max(1, Math.ceil(effectiveTtl / 1000));
+
+        return new Promise((resolve, reject) => {
+            this.client.set(key, JSON.stringify(value), { expires }, (err) => {
+                if (err) return reject(err);
+                resolve();
+            });
+        });
+    }
+
+    del(key: string): Promise<void> {
+        return new Promise((resolve, reject) => {
+            this.client.delete(key, (err) => {
+                if (err) return reject(err);
+                resolve();
+            });
+        });
+    }
+
+    async has(key: string): Promise<boolean> {
+        const val = await this.get(key);
+        return val !== null;
+    }
+
+    flush(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            this.client.flush((err) => {
+                if (err) return reject(err);
+                resolve();
+            });
+        });
+    }
+
+    /** memcached 는 키 개수 조회 API 가 없어 항상 -1 반환 */
+    get size(): number {
+        return -1;
+    }
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Cache 메모리 드라이버
+ * TTL + LRU-like 만료 처리 인메모리 구현
+ */
+
+import type { CacheStore, CacheDriver, MemoryCacheConfig } from "../types.ts";
+
+interface Entry {
+    /** JSON 직렬화된 값 */
+    raw: string;
+    /** 만료 시각 (0 = 영구) */
+    expiresAt: number;
+}
+
+export class MemoryDriver implements CacheStore {
+    readonly driver: CacheDriver = "memory";
+
+    private readonly store = new Map<string, Entry>();
+    private readonly maxEntries: number;
+    private readonly defaultTtlMs: number;
+
+    constructor(config: MemoryCacheConfig = {}, defaultTtlSeconds = 3600) {
+        this.maxEntries = config.max_entries ?? 10000;
+        this.defaultTtlMs = defaultTtlSeconds * 1000;
+    }
+
+    async get<T = unknown>(key: string): Promise<T | null> {
+        const entry = this.store.get(key);
+        if (!entry) return null;
+        if (entry.expiresAt !== 0 && Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return null;
+        }
+        return JSON.parse(entry.raw) as T;
+    }
+
+    async set<T = unknown>(
+        key: string,
+        value: T,
+        ttlMs?: number,
+    ): Promise<void> {
+        if (this.store.size >= this.maxEntries) {
+            this._evict();
+        }
+        const effectiveTtl = ttlMs ?? this.defaultTtlMs;
+        this.store.set(key, {
+            raw: JSON.stringify(value),
+            expiresAt: effectiveTtl === 0 ? 0 : Date.now() + effectiveTtl,
+        });
+    }
+
+    async del(key: string): Promise<void> {
+        this.store.delete(key);
+    }
+
+    async has(key: string): Promise<boolean> {
+        const entry = this.store.get(key);
+        if (!entry) return false;
+        if (entry.expiresAt !== 0 && Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return false;
+        }
+        return true;
+    }
+
+    async flush(): Promise<void> {
+        this.store.clear();
+    }
+
+    get size(): number {
+        return this.store.size;
+    }
+
+    /** 만료 항목 제거 + 여전히 초과하면 오래된 20% 추가 제거 */
+    private _evict(): void {
+        const now = Date.now();
+        for (const [key, entry] of this.store) {
+            if (entry.expiresAt !== 0 && now > entry.expiresAt) {
+                this.store.delete(key);
+            }
+        }
+        const excess = this.store.size - Math.floor(this.maxEntries * 0.8);
+        if (excess > 0) {
+            let count = 0;
+            for (const key of this.store.keys()) {
+                if (count >= excess) break;
+                this.store.delete(key);
+                count++;
+            }
+        }
+    }
+}