create-entity-app-server 0.0.3 → 0.0.4

package/src/system/routes/entity-interceptor.ts

@@ -1,327 +0,0 @@
-/**
- * 엔티티 훅 인터셉터
- *
- * submit / delete / list 라우트를 명시적으로 등록하여
- * @fastify/http-proxy 의 와일드카드(`/*`)보다 우선 매칭되게 한다.
- *
- * - 훅이 등록된 엔티티 → before/after 훅 실행 + EntityServerClient CRUD
- * - 훅이 없거나 skipHooks → 원본 요청을 엔티티서버로 그대로 포워드
- */
-
-import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
-import type { UserInfo } from "../hooks/types.ts";
-import { entityServer } from "../config/entity-server.ts";
-import { env, logger } from "../config/env.ts";
-import { cache } from "../cache/index.ts";
-import {
-    hasHook,
-    hasSpecificHook,
-    runBeforeGet,
-    runAfterGet,
-    runBeforeSubmit,
-    runAfterSubmit,
-    runBeforeDelete,
-    runAfterDelete,
-    runBeforeList,
-    runAfterList,
-} from "../hooks/runner.ts";
-
-// ─── 상수 ────────────────────────────────────────────────────────────────────
-
-/** 단건 조회 캐시 TTL (ms) */
-const GET_CACHE_TTL = 30_000;
-
-/** 엔티티 캐시 키 생성 */
-function entityCacheKey(entity: string, seq: number | string): string {
-    return `entity_get:${entity}:${seq}`;
-}
-
-// ─── 공통 params / querystring 타입 ──────────────────────────────────────────
-
-interface EntityParams {
-    entity: string;
-}
-
-interface EntitySeqParams {
-    entity: string;
-    seq: string;
-}
-
-interface SkipHooksQs {
-    skipHooks?: string;
-}
-
-// ─── 등록 ────────────────────────────────────────────────────────────────────
-
-/** 훅이 등록된 엔티티의 get/submit/delete/list 를 인터셉트하는 라우트를 등록한다 */
-export async function registerEntityInterceptor(app: FastifyInstance) {
-    // ── Get (단건 조회) ───────────────────────────────────────────────────
-    app.get<{ Params: EntitySeqParams; Querystring: SkipHooksQs }>(
-        "/api/v1/entity/:entity/:seq",
-        { preHandler: [app.authRequired] },
-        async (req, reply) => {
-            const { entity, seq: seqStr } = req.params;
-            const seq = Number(seqStr);
-            const user = req.user as UserInfo;
-
-            if (!hasHook(entity) || req.query.skipHooks === "true") {
-                return forwardToEntityServer(req, reply);
-            }
-
-            // ① beforeGet — 접근 제어
-            const allowed = await runBeforeGet(entity, seq, user);
-            if (!allowed) {
-                return reply
-                    .status(403)
-                    .send({ ok: false, error: "Get blocked by hook" });
-            }
-
-            // ② 엔티티서버 get (캐시 우선)
-            const getCacheKey = entityCacheKey(entity, seq);
-            const store = cache();
-            let entityData = await store.get<any>(getCacheKey);
-            if (!entityData) {
-                const res = await entityServer.get(entity, seq, {
-                    skipHooks: true,
-                });
-                entityData = res.data;
-                await store.set(getCacheKey, entityData, GET_CACHE_TTL);
-            }
-
-            // ③ afterGet — 데이터 마스킹/가공 (user마다 다르므로 매번 실행)
-            const finalData = await runAfterGet(entity, entityData, user);
-
-            return reply.send({ ok: true, data: finalData });
-        },
-    );
-
-    // ── Submit ────────────────────────────────────────────────────────────
-    app.post<{ Params: EntityParams; Querystring: SkipHooksQs }>(
-        "/api/v1/entity/:entity/submit",
-        { preHandler: [app.authRequired] },
-        async (req, reply) => {
-            const { entity } = req.params;
-            const user = req.user as UserInfo;
-
-            if (!hasHook(entity) || req.query.skipHooks === "true") {
-                return forwardToEntityServer(req, reply);
-            }
-
-            const data = req.body as Record<string, unknown>;
-            const isUpdate = data.seq != null;
-
-            // ① old 데이터 조회 (UPDATE 시, beforeSubmit 훅이 있을 때만)
-            let old: any = null;
-            if (isUpdate && hasSpecificHook(entity, "beforeSubmit")) {
-                try {
-                    const oldCacheKey = entityCacheKey(
-                        entity,
-                        data.seq as number,
-                    );
-                    old = await cache().get<any>(oldCacheKey);
-                    if (!old) {
-                        const res = await entityServer.get(
-                            entity,
-                            Number(data.seq),
-                            { skipHooks: true },
-                        );
-                        old = res.data ?? null;
-                    }
-                } catch (err) {
-                    logger.warn(
-                        { entity, seq: data.seq, err },
-                        "old 데이터 조회 실패 — old=null 로 진행",
-                    );
-                }
-            }
-
-            // ② beforeSubmit → 변환된 데이터
-            const submitData = await runBeforeSubmit(
-                entity,
-                { old, new: data },
-                user,
-            );
-
-            // ③ 엔티티서버 submit
-            const result = await entityServer.submit(entity, submitData, {
-                skipHooks: true,
-            });
-
-            // ④ afterSubmit (훅이 있을 때만 새 데이터 조회)
-            if (hasSpecificHook(entity, "afterSubmit")) {
-                let newData: any;
-                try {
-                    const res = await entityServer.get(entity, result.seq, {
-                        skipHooks: true,
-                    });
-                    newData = res.data;
-                } catch {
-                    newData = { ...submitData, seq: result.seq };
-                }
-                await runAfterSubmit(entity, { old, new: newData }, user);
-            }
-
-            // ⑤ 캐시 무효화 (변경된 엔티티의 캐시를 즉시 제거)
-            await cache().del(entityCacheKey(entity, result.seq));
-
-            // ⑥ 엔티티서버 응답 형식 그대로 반환
-            return reply.send({ ok: true, seq: result.seq });
-        },
-    );
-
-    // ── Delete ────────────────────────────────────────────────────────────
-    app.post<{
-        Params: EntitySeqParams;
-        Querystring: SkipHooksQs & { hard?: string };
-    }>(
-        "/api/v1/entity/:entity/delete/:seq",
-        { preHandler: [app.authRequired] },
-        async (req, reply) => {
-            const { entity, seq: seqStr } = req.params;
-            const seq = Number(seqStr);
-            const user = req.user as UserInfo;
-
-            if (!hasHook(entity) || req.query.skipHooks === "true") {
-                return forwardToEntityServer(req, reply);
-            }
-
-            // ① 삭제 대상 데이터 조회
-            let data: any = null;
-            try {
-                const res = await entityServer.get(entity, seq, {
-                    skipHooks: true,
-                });
-                data = res.data ?? null;
-            } catch (err) {
-                logger.warn(
-                    { entity, seq, err },
-                    "삭제 대상 데이터 조회 실패 — data=null 로 진행",
-                );
-            }
-            const deleteCtx = { seq, data };
-
-            // ② beforeDelete
-            const allowed = await runBeforeDelete(entity, deleteCtx, user);
-            if (!allowed) {
-                return reply
-                    .status(403)
-                    .send({ ok: false, error: "Delete blocked by hook" });
-            }
-
-            // ③ 엔티티서버 delete
-            const result = await entityServer.delete(entity, seq, {
-                hard: req.query.hard === "true",
-                skipHooks: true,
-            });
-
-            // ④ afterDelete (사이드이펙트)
-            await runAfterDelete(entity, deleteCtx, user);
-
-            // ⑤ 캐시 무효화
-            await cache().del(entityCacheKey(entity, seq));
-
-            return reply.send(result);
-        },
-    );
-
-    // ── Find (조건 단건 조회 — afterGet 훅 재사용) ────────────────────────
-    app.post<{ Params: EntityParams; Querystring: SkipHooksQs }>(
-        "/api/v1/entity/:entity/find",
-        { preHandler: [app.authRequired] },
-        async (req, reply) => {
-            const { entity } = req.params;
-            const user = req.user as UserInfo;
-
-            if (!hasHook(entity) || req.query.skipHooks === "true") {
-                return forwardToEntityServer(req, reply);
-            }
-
-            // ① 엔티티서버 find
-            const conditions = req.body as Record<string, unknown>;
-            const result = await entityServer.find(entity, conditions, {
-                skipHooks: true,
-            });
-
-            // ② afterGet — get과 동일한 데이터 마스킹/가공
-            const finalData = await runAfterGet(entity, result.data, user);
-
-            return reply.send({ ok: true, data: finalData });
-        },
-    );
-
-    // ── List ──────────────────────────────────────────────────────────────
-    app.post<{
-        Params: EntityParams;
-        Querystring: SkipHooksQs & Record<string, string>;
-    }>(
-        "/api/v1/entity/:entity/list",
-        { preHandler: [app.authRequired] },
-        async (req, reply) => {
-            const { entity } = req.params;
-            const user = req.user as UserInfo;
-
-            if (!hasHook(entity) || req.query.skipHooks === "true") {
-                return forwardToEntityServer(req, reply);
-            }
-
-            // ① beforeList — 조건/정렬 변환
-            const conditions = req.body as Record<string, unknown>;
-            const { skipHooks: _, ...queryParams } = req.query;
-            const params = await runBeforeList(
-                entity,
-                { conditions, ...queryParams },
-                user,
-            );
-
-            // ② 엔티티서버 list
-            const { conditions: listConditions, ...listParams } = params;
-            const result = await entityServer.list(entity, {
-                ...listParams,
-                conditions: listConditions,
-            });
-
-            // ③ afterList — 응답 가공
-            const finalData = await runAfterList(entity, result.data, user);
-
-            return reply.send({ ok: true, data: finalData });
-        },
-    );
-}
-
-// ─── 프록시 포워드 ───────────────────────────────────────────────────────────
-
-/**
- * 훅이 없는 엔티티 요청을 엔티티서버로 그대로 중계한다.
- * 원본 헤더(Authorization 등)를 보존하여 사용자 컨텍스트를 유지한다.
- */
-async function forwardToEntityServer(req: FastifyRequest, reply: FastifyReply) {
-    const url = `${env.ENTITY_SERVER_URL}${req.url.replace("/api/v1/", "/v1/")}`;
-
-    const headers: Record<string, string> = {};
-    for (const [key, val] of Object.entries(req.headers)) {
-        if (typeof val === "string") headers[key] = val;
-    }
-    delete headers.host;
-
-    // body가 있는 경우 content-type 보장
-    const hasBody = req.method !== "GET" && req.method !== "HEAD";
-    if (hasBody && !headers["content-type"]) {
-        headers["content-type"] = "application/json";
-    }
-
-    const response = await fetch(url, {
-        method: req.method,
-        headers,
-        body: hasBody ? JSON.stringify(req.body) : undefined,
-    });
-
-    reply.status(response.status);
-    for (const [key, val] of response.headers.entries()) {
-        const lower = key.toLowerCase();
-        if (lower !== "transfer-encoding" && lower !== "content-encoding") {
-            reply.header(key, val);
-        }
-    }
-    const body = await response.text();
-    return reply.send(body);
-}

package/src/system/routes/loader.ts

@@ -1,215 +0,0 @@
-/**
- * 라우트 자동 로더 — 두 곳을 스캔하여 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

@@ -1,150 +0,0 @@
-/**
- * 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(),
-    };
-}