create-entity-app-server 0.0.3

package/src/system/routes/loader.ts

@@ -0,0 +1,215 @@
+/**
+ * 라우트 자동 로더 — 두 곳을 스캔하여 Fastify에 등록
+ *
+ * 1차: app/plugins/{module}/routes.ts              → /api/v1/{module}/*
+ *      app/plugins/{module}/routes.ts + multiRoutes export → /api/v1/{name}/*
+ *      app/plugins/{module}/*-routes.ts            → /api/v1/{name}/*
+ *      app/plugins/{module}/routes/routes.ts       → /api/v1/{module}/*
+ *      app/plugins/{module}/routes/*-routes.ts     → /api/v1/{name}/*
+ *      예) alimtalk/friendtalk-routes.ts           → /api/v1/friendtalk/*
+ *
+ * 2차: app/routes/{domain}/routes.ts          → /api/v1/{domain}/*
+ *      (health 등 비확장 라우트용)
+ */
+
+import { readdirSync, existsSync, readFileSync } from "fs";
+import path from "path";
+import type { FastifyInstance } from "fastify";
+import { logger, logFmt } from "../config/env.ts";
+import { resolveAppRoot } from "../utils/app-path.ts";
+import { resolveModulePath } from "../config/module-path.ts";
+import { substituteEnvVars } from "../config/env-substitution.ts";
+
+const isTTY = process.stdout.isTTY;
+
+function writeProgress(label: string, name: string): void {
+    if (isTTY) {
+        process.stdout.write(`\r  ${label} [${name}]...`.padEnd(72));
+    }
+}
+
+function clearProgress(): void {
+    if (isTTY) {
+        process.stdout.write(`\r${" ".repeat(72)}\r`);
+    }
+}
+
+/** 확장모듈·독립 라우트를 자동 탐색하여 등록한다 */
+export async function registerRoutes(app: FastifyInstance): Promise<number> {
+    const registered = new Set<string>();
+
+    // ── 1차: plugins/{module}/routes.ts ──
+    const extensionCount = await loadExtensionRoutes(app, registered);
+
+    // ── 2차: routes/{domain}/routes.ts (비확장 라우트) ──
+    const standaloneCount = await loadStandaloneRoutes(app, registered);
+
+    clearProgress();
+    return extensionCount + standaloneCount;
+}
+
+/**
+ * plugins/{module}/routes.ts 및 routes/ 하위 *-routes.ts 스캔
+ */
+async function loadExtensionRoutes(
+    app: FastifyInstance,
+    registered: Set<string>,
+): Promise<number> {
+    const extDir = path.join(resolveAppRoot(import.meta.url), "plugins");
+    if (!existsSync(extDir)) return 0;
+
+    let loadedCount = 0;
+
+    const modules = readdirSync(extDir, { withFileTypes: true });
+
+    for (const mod of modules) {
+        if (!mod.isDirectory()) continue;
+        const modDir = path.join(extDir, mod.name);
+        if (!(await isExtensionRoutesEnabled(modDir))) continue;
+
+        const candidateDirs = [modDir, path.join(modDir, "routes")];
+
+        for (const routeDir of candidateDirs) {
+            if (!existsSync(routeDir)) continue;
+
+            // routes.ts — 모듈 이름으로 등록
+            loadedCount += await tryRegister(
+                app,
+                routeDir,
+                "routes",
+                mod.name,
+                registered,
+            );
+
+            // *-routes.ts — 접두어를 도메인명으로 사용
+            const files = readdirSync(routeDir);
+            for (const file of files) {
+                const match = file.match(/^(.+)-routes\.(ts|js)$/);
+                if (!match) continue;
+                const domain = match[1]!;
+                loadedCount += await tryRegister(
+                    app,
+                    routeDir,
+                    file.replace(/\.(ts|js)$/, ""),
+                    domain,
+                    registered,
+                );
+            }
+        }
+    }
+
+    return loadedCount;
+}
+
+async function isExtensionRoutesEnabled(modDir: string): Promise<boolean> {
+    const configPath = path.join(modDir, "config.json");
+    if (!existsSync(configPath)) return true;
+
+    try {
+        const raw = substituteEnvVars(readFileSync(configPath, "utf-8"));
+        const cfg = JSON.parse(raw) as { enabled?: boolean };
+        return cfg.enabled !== false;
+    } catch (err) {
+        logger.warn(
+            { modDir, err },
+            "Failed to parse plugin config while loading extension routes",
+        );
+        return true;
+    }
+}
+
+/**
+ * routes/{domain}/routes.ts 스캔 (비확장 라우트)
+ */
+async function loadStandaloneRoutes(
+    app: FastifyInstance,
+    registered: Set<string>,
+): Promise<number> {
+    const routesDir = path.join(resolveAppRoot(import.meta.url), "routes");
+    if (!existsSync(routesDir)) return 0;
+
+    let loadedCount = 0;
+
+    const entries = readdirSync(routesDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (registered.has(entry.name)) continue; // 이미 extension에서 등록됨
+
+        // config.json 체크: enabled: false 이면 스킵
+        const configPath = path.join(routesDir, entry.name, "config.json");
+        if (existsSync(configPath)) {
+            try {
+                const raw = substituteEnvVars(
+                    readFileSync(configPath, "utf-8"),
+                );
+                const cfg = JSON.parse(raw) as { enabled?: boolean };
+                if (cfg.enabled === false) {
+                    // 로그 없이 스킵
+                    continue;
+                }
+            } catch (err) {
+                logger.warn(
+                    { domain: entry.name, err },
+                    `Failed to parse route config: ${entry.name}`,
+                );
+            }
+        }
+
+        const routePath = resolveModulePath(
+            path.join(routesDir, entry.name),
+            "routes",
+        );
+
+        if (!routePath) continue;
+
+        try {
+            const mod = await import(routePath);
+            await app.register(mod.default, {
+                prefix: `/api/v1/${entry.name}`,
+            });
+            registered.add(entry.name);
+            loadedCount++;
+        } catch (err) {
+            logger.error(
+                { domain: entry.name, err },
+                logFmt.error(`Failed to load route: ${entry.name}`),
+            );
+        }
+    }
+
+    return loadedCount;
+}
+
+/**
+ * 라우트 파일을 로드하고 등록
+ */
+async function tryRegister(
+    app: FastifyInstance,
+    dir: string,
+    baseName: string,
+    domain: string,
+    registered: Set<string>,
+): Promise<number> {
+    if (registered.has(domain)) return 0;
+
+    const filePath = resolveModulePath(dir, baseName);
+
+    if (!filePath) return 0;
+
+    try {
+        const mod = await import(filePath);
+
+        await app.register(mod.default, {
+            prefix: `/api/v1/${domain}`,
+        });
+        registered.add(domain);
+        return 1;
+    } catch (err) {
+        logger.error(
+            { domain, err },
+            logFmt.error(`Failed to load route: ${domain}`),
+        );
+        return 0;
+    }
+}

package/src/system/scheduler/cron-utils.ts

@@ -0,0 +1,150 @@
+/**
+ * Cron 표현식 파싱·검증·스케줄 생성 공통 유틸리티
+ *
+ * 각 스케줄러에서 반복되는 Cron 생성 로직을 통합합니다.
+ *
+ *   import { createCron, validateCron, describeCron } from "@gateway/api";
+ */
+
+import { Cron } from "croner";
+
+/** createCron 옵션 */
+export interface CreateCronOptions {
+    /** cron 표현식 (5-field 또는 6-field). 예: "0 3 * * *" */
+    expression: string;
+    /** IANA 타임존. 기본값: "Asia/Seoul" */
+    timezone?: string;
+    /** 이전 실행이 끝나기 전 다음 실행 스킵 여부. 기본값: true */
+    protect?: boolean;
+    /** 실행할 콜백 (async 가능) */
+    onTick: () => void | Promise<void>;
+}
+
+/** createCron 반환값 */
+export interface CronHandle {
+    /** croner Cron 인스턴스 */
+    job: InstanceType<typeof Cron>;
+    /** 다음 실행 예정 시각 (ISO 문자열). 없으면 null */
+    nextRun: string | null;
+    /** 스케줄 중지 */
+    stop: () => void;
+}
+
+/**
+ * cron 표현식이 유효한지 검증합니다.
+ * 유효하면 true, 아니면 false를 반환합니다.
+ */
+export function validateCron(expression: string): boolean {
+    try {
+        // croner는 생성 시 파싱 — 콜백 없이 즉시 중지하면 검증만 수행
+        const test = new Cron(expression, { paused: true }, () => {});
+        test.stop();
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * cron 표현식의 다음 N회 실행 예정 시각을 반환합니다.
+ * @param expression  cron 표현식
+ * @param count       반환할 횟수 (기본 5)
+ * @param timezone    IANA 타임존 (기본 "Asia/Seoul")
+ * @returns Date 배열. 표현식이 잘못되면 빈 배열.
+ */
+export function nextRuns(
+    expression: string,
+    count = 5,
+    timezone = "Asia/Seoul",
+): Date[] {
+    try {
+        const job = new Cron(expression, { timezone, paused: true }, () => {});
+        const dates: Date[] = [];
+        let ref: Date | undefined | null;
+        for (let i = 0; i < count; i++) {
+            ref = ref ? job.nextRun(ref) : job.nextRun();
+            if (!ref) break;
+            dates.push(new Date(ref.getTime()));
+            // 다음 반복을 위해 1초 후부터 탐색
+            ref = new Date(ref.getTime() + 1000);
+        }
+        job.stop();
+        return dates;
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * cron 표현식을 사람이 읽기 쉬운 한국어 설명으로 변환합니다.
+ * 5-field 표준(분 시 일 월 요일)만 지원합니다.
+ *
+ * 예: "0 3 * * *"  → "매일 03:00"
+ *     "30 2 * * *" → "매일 02:30"
+ *     "0 0 1 * *"  → "매월 1일 00:00"
+ *     "0 9 * * 1"  → "매주 월요일 09:00"
+ */
+export function describeCron(expression: string): string {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length < 5 || parts.length > 6) return expression;
+
+    // 6-field (초 포함)일 경우 첫 필드 제거
+    const [minute, hour, dayOfMonth, month, dayOfWeek] =
+        parts.length === 6 ? parts.slice(1) : parts;
+
+    const dayNames = ["일", "월", "화", "수", "목", "금", "토"];
+
+    const timePart =
+        minute !== "*" && hour !== "*"
+            ? hour.padStart(2, "0") + ":" + minute.padStart(2, "0")
+            : "";
+
+    // 매일
+    if (dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+        return timePart ? "매일 " + timePart : "매분";
+    }
+
+    // 매주 특정 요일
+    if (dayOfMonth === "*" && month === "*" && dayOfWeek !== "*") {
+        const dow = Number(dayOfWeek);
+        const dayName =
+            dow >= 0 && dow <= 6 ? dayNames[dow] + "요일" : dayOfWeek;
+        return "매주 " + dayName + (timePart ? " " + timePart : "");
+    }
+
+    // 매월 특정 일
+    if (dayOfMonth !== "*" && month === "*" && dayOfWeek === "*") {
+        return "매월 " + dayOfMonth + "일" + (timePart ? " " + timePart : "");
+    }
+
+    return expression;
+}
+
+/**
+ * Cron 스케줄을 생성합니다.
+ * 표현식 검증 → Cron 인스턴스 생성 → CronHandle 반환.
+ *
+ * @throws Error  표현식이 유효하지 않으면 에러
+ */
+export function createCron(opts: CreateCronOptions): CronHandle {
+    const {
+        expression,
+        timezone = "Asia/Seoul",
+        protect = true,
+        onTick,
+    } = opts;
+
+    if (!validateCron(expression)) {
+        throw new Error("Invalid cron expression: " + expression);
+    }
+
+    const job = new Cron(expression, { timezone, protect }, onTick);
+
+    const next = job.nextRun();
+
+    return {
+        job,
+        nextRun: next ? next.toISOString() : null,
+        stop: () => job.stop(),
+    };
+}

package/src/system/scheduler/distributed-lock.ts

@@ -0,0 +1,141 @@
+/**
+ * 분산 락 — 멀티인스턴스 중복 실행 방지
+ *
+ * Go `internal/privacy/service.go` acquireLock/releaseLock 포팅.
+ *
+ * `privacy_cron_lock` 엔티티의 unique constraint를 활용한 슬롯 기반 락.
+ * 엔티티가 없으면 단일 인스턴스로 간주하고 항상 true 반환.
+ *
+ * 슬롯 계산:
+ *   slot = `${jobName}:${Math.floor(now / ttlSec)}`
+ *   → 동일 interval 내 모든 인스턴스가 같은 slot 값을 사용
+ *   → Insert 시 unique constraint 위반 = 다른 인스턴스가 이미 처리 중
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import { hostname } from "node:os";
+
+/**
+ * 분산 락을 획득한다.
+ *
+ * @param jobName  작업 식별자 (예: "privacy:password_expiry")
+ * @param ttlSec   락 유효 시간(초) — 같은 값으로 release 호출해야 함
+ * @returns 락 획득 성공 여부
+ */
+export async function acquireLock(
+    jobName: string,
+    ttlSec: number,
+): Promise<boolean> {
+    const now = Math.floor(Date.now() / 1000);
+    const slotNum = Math.floor(now / ttlSec);
+    const slot = `${jobName}:${slotNum}`;
+    const expiresAt = new Date((now + ttlSec) * 1000)
+        .toISOString()
+        .replace("T", " ")
+        .slice(0, 19);
+    const lockedBy = `${hostname()}:${process.pid}`;
+
+    // 1단계: 즉시 Insert 시도 — unique constraint로 동시 실행 방지
+    try {
+        await entityServer.submit("privacy_cron_lock", {
+            job_name: slot,
+            locked_by: lockedBy,
+            locked_time: new Date(now * 1000)
+                .toISOString()
+                .replace("T", " ")
+                .slice(0, 19),
+            expires_time: expiresAt,
+        });
+        return true;
+    } catch (insertErr) {
+        // unique constraint 위반 또는 privacy_cron_lock 엔티티 미설정
+        try {
+            // 2단계: 기존 락 확인 (stale 여부 체크)
+            const existing = await entityServer.find<Record<string, unknown>>(
+                "privacy_cron_lock",
+                { job_name: slot },
+            );
+            if (!existing?.data) {
+                // 찾을 수 없음 — 다른 인스턴스가 이미 처리 완료
+                logger.info(
+                    { jobName },
+                    "Distributed lock: contention, skipping",
+                );
+                return false;
+            }
+
+            const expStr = String(existing.data.expires_time ?? "");
+            const nowStr = new Date(now * 1000)
+                .toISOString()
+                .replace("T", " ")
+                .slice(0, 19);
+
+            if (expStr && expStr < nowStr) {
+                // 만료된 stale 락 → 삭제 후 재시도
+                const seq = Number(existing.data.seq);
+                if (seq > 0) {
+                    await entityServer.delete("privacy_cron_lock", seq);
+                }
+                // 삭제 후 한 번 더 Insert 시도
+                try {
+                    await entityServer.submit("privacy_cron_lock", {
+                        job_name: slot,
+                        locked_by: lockedBy,
+                        locked_time: new Date(now * 1000)
+                            .toISOString()
+                            .replace("T", " ")
+                            .slice(0, 19),
+                        expires_time: expiresAt,
+                    });
+                    return true;
+                } catch {
+                    logger.info(
+                        { jobName },
+                        "Distributed lock: contention after stale cleanup",
+                    );
+                    return false;
+                }
+            }
+
+            // 유효한 락 — 다른 인스턴스가 실행 중
+            logger.info(
+                { jobName },
+                "Distributed lock: already held by another instance",
+            );
+            return false;
+        } catch {
+            // privacy_cron_lock 엔티티 미설정 → 단일 인스턴스 모드
+            return true;
+        }
+    }
+}
+
+/**
+ * 분산 락을 해제한다.
+ *
+ * @param jobName  acquireLock과 동일한 작업 식별자
+ * @param ttlSec   acquireLock과 동일한 TTL
+ */
+export async function releaseLock(
+    jobName: string,
+    ttlSec: number,
+): Promise<void> {
+    const now = Math.floor(Date.now() / 1000);
+    const slotNum = Math.floor(now / ttlSec);
+    const slot = `${jobName}:${slotNum}`;
+
+    try {
+        const existing = await entityServer.find<Record<string, unknown>>(
+            "privacy_cron_lock",
+            { job_name: slot },
+        );
+        if (existing?.data) {
+            const seq = Number(existing.data.seq);
+            if (seq > 0) {
+                await entityServer.delete("privacy_cron_lock", seq);
+            }
+        }
+    } catch {
+        // ignore — 엔티티 미설정 또는 이미 삭제됨
+    }
+}

package/src/system/scheduler/schedule-loader.ts

@@ -0,0 +1,105 @@
+/**
+ * Schedule auto-loader
+ *
+ * Scans app/schedules/{name}/index.ts and calls
+ * start() / stop() interface methods.
+ *
+ * - onReady: start() for each scheduler
+ * - onClose: stop() for each scheduler
+ */
+
+import type { FastifyInstance } from "fastify";
+import { readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { logger } from "../config/env.ts";
+import { resolveAppRoot } from "../utils/app-path.ts";
+import { resolveModulePath } from "../config/module-path.ts";
+
+interface ScheduleModule {
+    start: () => void | Promise<void>;
+    stop: () => void | Promise<void>;
+}
+
+/**
+ * Scans app/schedules/ subdirectories,
+ * dynamic-imports index.ts (or index.js),
+ * and hooks start/stop into Fastify lifecycle.
+ */
+export async function loadSchedules(app: FastifyInstance): Promise<number> {
+    const schedulesDir = join(resolveAppRoot(import.meta.url), "schedules");
+    if (!existsSync(schedulesDir)) return 0;
+
+    const dirs = readdirSync(schedulesDir, { withFileTypes: true }).filter(
+        (d) => d.isDirectory(),
+    );
+
+    const modules: ScheduleModule[] = [];
+    const total = dirs.length;
+    let loaded = 0;
+    const isTTY = process.stdout.isTTY;
+
+    for (const dir of dirs) {
+        const modulePath = resolveModulePath(
+            join(schedulesDir, dir.name),
+            "index",
+        );
+        if (!modulePath) continue;
+
+        loaded++;
+        if (isTTY) {
+            process.stdout.write(
+                `\r  Loading schedules [${loaded}/${total}]...`.padEnd(72),
+            );
+        }
+
+        try {
+            const mod = (await import(
+                pathToFileURL(modulePath).href
+            )) as ScheduleModule;
+            if (typeof mod.start === "function") {
+                modules.push(mod);
+            } else {
+                logger.warn(
+                    "Schedule " + dir.name + "/index.ts must export start()",
+                );
+            }
+        } catch (err) {
+            logger.error({ err }, "Failed to load schedule: " + dir.name);
+        }
+    }
+
+    if (isTTY && total > 0) {
+        process.stdout.write(`\r${" ".repeat(72)}\r`);
+    }
+
+    if (modules.length === 0) return 0;
+
+    // onReady - start all schedulers (병렬)
+    app.addHook("onReady", async () => {
+        await Promise.allSettled(
+            modules.map(async (mod) => {
+                try {
+                    await mod.start();
+                } catch (err) {
+                    logger.error({ err }, "Schedule start failed");
+                }
+            }),
+        );
+    });
+
+    // onClose - stop all schedulers (병렬)
+    app.addHook("onClose", async () => {
+        await Promise.allSettled(
+            modules.map(async (mod) => {
+                try {
+                    await mod.stop();
+                } catch (err) {
+                    logger.error({ err }, "Schedule stop failed");
+                }
+            }),
+        );
+    });
+
+    return modules.length;
+}

package/src/system/security/anonymous-device-id.ts

@@ -0,0 +1,41 @@
+/**
+ * 익명 디바이스 ID 쿠키 관리
+ *
+ * 요청에서 디바이스 ID를 읽거나, 없으면 새로 생성하여 쿠키로 설정합니다.
+ */
+
+import { randomUUID } from "crypto";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { PacketEncryptConfig } from "../config/packet-encrypt.ts";
+import {
+    parseCookies,
+    serializeCookie,
+    appendSetCookie,
+} from "../http/cookie.ts";
+
+export function readAnonymousDeviceId(
+    req: FastifyRequest,
+    cfg: PacketEncryptConfig,
+): string | null {
+    if (!cfg.anonymousEnabled) return null;
+    const cookies = parseCookies(req.headers.cookie);
+    const deviceId = cookies[cfg.deviceCookieName];
+    return deviceId ? deviceId.trim() : null;
+}
+
+export function ensureAnonymousDeviceId(
+    req: FastifyRequest,
+    reply: FastifyReply,
+    cfg: PacketEncryptConfig,
+): string | null {
+    if (!cfg.anonymousEnabled) return null;
+    const current = readAnonymousDeviceId(req, cfg);
+    if (current) return current;
+
+    const created = randomUUID();
+    appendSetCookie(
+        reply,
+        serializeCookie(cfg.deviceCookieName, created, cfg.deviceCookieOptions),
+    );
+    return created;
+}