create-entity-app-server 0.0.3

package/src/system/hooks/runner.ts

@@ -0,0 +1,159 @@
+/**
+ * 훅 실행기 — 등록된 엔티티별 훅을 실행합니다.
+ *
+ * 에러 처리 정책:
+ *   before* — 예외 시 throw → error-handler.ts 가 400/500 반환 (차단)
+ *   after*  — 예외 시 로그만 남기고 원본 result 반환 (무시)
+ */
+
+import type {
+    EntityHook,
+    UserInfo,
+    SubmitContext,
+    DeleteContext,
+} from "./types.ts";
+import { logger } from "../config/env.ts";
+
+/** 훅 레지스트리 — loader.ts 가 app/hooks/index.ts를 로드하여 채움 */
+let hookRegistry: Record<string, EntityHook> = {};
+
+/** 훅 레지스트리를 설정한다 */
+export function setHookRegistry(registry: Record<string, EntityHook>): void {
+    hookRegistry = registry;
+}
+
+/** 현재 훅 레지스트리를 반환한다 */
+export function getHookRegistry(): Record<string, EntityHook> {
+    return hookRegistry;
+}
+
+/** 엔티티에 등록된 훅이 있는지 확인한다 */
+export function hasHook(entity: string): boolean {
+    return entity in hookRegistry;
+}
+
+/** 엔티티에 특정 이름의 훅이 등록되어 있는지 확인한다 */
+export function hasSpecificHook(
+    entity: string,
+    hookName: keyof EntityHook,
+): boolean {
+    const hook = hookRegistry[entity];
+    return hook != null && typeof hook[hookName] === "function";
+}
+
+// --- before 훅: 실패 시 차단 (throw) ---
+
+/** get 전 훅을 실행하고 허용 여부를 반환한다 */
+export async function runBeforeGet(
+    entity: string,
+    seq: number,
+    user: UserInfo,
+): Promise<boolean> {
+    const hook = hookRegistry[entity];
+    if (!hook?.beforeGet) return true;
+    return await hook.beforeGet(entity, seq, user);
+}
+
+/**
+ * submit 전 훅을 실행한다.
+ * ctx.new를 변경한 반환값이 실제 submit 데이터가 된다.
+ */
+export async function runBeforeSubmit(
+    entity: string,
+    ctx: SubmitContext,
+    user: UserInfo,
+): Promise<any> {
+    const hook = hookRegistry[entity];
+    if (!hook?.beforeSubmit) return ctx.new;
+    return await hook.beforeSubmit(entity, ctx, user);
+}
+
+/** delete 전 훅을 실행하고 허용 여부를 반환한다 */
+export async function runBeforeDelete(
+    entity: string,
+    ctx: DeleteContext,
+    user: UserInfo,
+): Promise<boolean> {
+    const hook = hookRegistry[entity];
+    if (!hook?.beforeDelete) return true;
+    return await hook.beforeDelete(entity, ctx, user);
+}
+
+/** list 전 훅을 실행하고 변환된 파라미터를 반환한다 */
+export async function runBeforeList(
+    entity: string,
+    params: any,
+    user: UserInfo,
+): Promise<any> {
+    const hook = hookRegistry[entity];
+    if (!hook?.beforeList) return params;
+    return await hook.beforeList(entity, params, user);
+}
+
+// --- after 훅: 실패 시 로그만 남기고 무시 ---
+
+/** get 후 훅을 실행한다. 반환값이 클라이언트 응답이 된다 (실패 시 원본 반환) */
+export async function runAfterGet(
+    entity: string,
+    data: any,
+    user: UserInfo,
+): Promise<any> {
+    const hook = hookRegistry[entity];
+    if (!hook?.afterGet) return data;
+    try {
+        return await hook.afterGet(entity, data, user);
+    } catch (err) {
+        logger.error({ entity, err }, "afterGet hook failed — ignored");
+        return data;
+    }
+}
+
+/**
+ * submit 후 훅을 실행한다.
+ * ctx.old/ctx.new로 변경 전후 비교가 가능하다.
+ */
+export async function runAfterSubmit(
+    entity: string,
+    ctx: SubmitContext,
+    user: UserInfo,
+): Promise<any> {
+    const hook = hookRegistry[entity];
+    if (!hook?.afterSubmit) return ctx.new;
+    try {
+        return await hook.afterSubmit(entity, ctx, user);
+    } catch (err) {
+        logger.error({ entity, err }, "afterSubmit hook failed — ignored");
+        return ctx.new;
+    }
+}
+
+/** delete 후 훅을 실행한다 (실패 시 무시) */
+export async function runAfterDelete(
+    entity: string,
+    ctx: DeleteContext,
+    user: UserInfo,
+): Promise<void> {
+    const hook = hookRegistry[entity];
+    if (!hook?.afterDelete) return;
+    try {
+        await hook.afterDelete(entity, ctx, user);
+    } catch (err) {
+        logger.error({ entity, err }, "afterDelete hook failed — ignored");
+    }
+}
+
+/** list 후 훅을 실행한다 (실패 시 무시) */
+export async function runAfterList(
+    entity: string,
+    result: any,
+    user: UserInfo,
+): Promise<any> {
+    const hook = hookRegistry[entity];
+    if (!hook?.afterList) return result;
+    try {
+        return await hook.afterList(entity, result, user);
+    } catch (err) {
+        logger.error({ entity, err }, "afterList hook failed — ignored");
+        return result;
+    }
+}

package/src/system/hooks/types.ts

@@ -0,0 +1,75 @@
+/**
+ * EntityHook 인터페이스 — 엔티티 CRUD 전/후 훅
+ *
+ * before* — 예외 발생 시 프록시 요청을 차단 (클라이언트에 에러 반환)
+ * after*  — 예외 발생 시 로그만 남기고 무시 (이미 Entity Server에 반영됨)
+ *
+ * Submit 훅은 old/new 컨텍스트를 지원한다:
+ *   beforeSubmit — { old: 수정 전 데이터 | null(신규), new: 요청 데이터 }
+ *   afterSubmit  — { old: 수정 전 데이터 | null(신규), new: 저장된 결과 데이터 }
+ */
+
+export interface UserInfo {
+    sub: number;
+    email: string;
+    role: string;
+    [key: string]: unknown;
+}
+
+/** submit 훅에 전달되는 old/new 컨텍스트 */
+export interface SubmitContext<T = any> {
+    /** 수정 전 데이터 (신규 INSERT 시 null) */
+    old: T | null;
+    /** 요청 데이터 (beforeSubmit) 또는 저장된 결과 (afterSubmit) */
+    new: T;
+}
+
+/** delete 훅에 전달되는 컨텍스트 */
+export interface DeleteContext<T = any> {
+    /** 삭제 대상 시퀀스 */
+    seq: number;
+    /** 삭제 대상 데이터 (조회 실패 시 null) */
+    data: T | null;
+}
+
+export interface EntityHook {
+    /** get 전: 접근 제어. false 반환 또는 throw 시 조회 차단 */
+    beforeGet?(entity: string, seq: number, user: UserInfo): Promise<boolean>;
+
+    /** get 후: 데이터 마스킹/가공. 반환값이 클라이언트 응답이 됨 */
+    afterGet?(entity: string, data: any, user: UserInfo): Promise<any>;
+
+    /** submit 전: 데이터 변환/검증. ctx.new를 변경하여 반환하면 해당 데이터로 submit */
+    beforeSubmit?(
+        entity: string,
+        ctx: SubmitContext,
+        user: UserInfo,
+    ): Promise<any>;
+
+    /** submit 후: 알림, 로깅 등 사이드이펙트. ctx.old/ctx.new로 변경 전후 비교 가능 */
+    afterSubmit?(
+        entity: string,
+        ctx: SubmitContext,
+        user: UserInfo,
+    ): Promise<any>;
+
+    /** delete 전: ctx.data로 삭제 대상 확인, false 반환 시 삭제 차단 */
+    beforeDelete?(
+        entity: string,
+        ctx: DeleteContext,
+        user: UserInfo,
+    ): Promise<boolean>;
+
+    /** delete 후: ctx.data로 삭제된 데이터 확인, 정리/알림 등 */
+    afterDelete?(
+        entity: string,
+        ctx: DeleteContext,
+        user: UserInfo,
+    ): Promise<void>;
+
+    /** list 전: 필터 파라미터 변환/추가 */
+    beforeList?(entity: string, params: any, user: UserInfo): Promise<any>;
+
+    /** list 후: 응답 데이터 가공 */
+    afterList?(entity: string, result: any, user: UserInfo): Promise<any>;
+}

package/src/system/hooks/withdraw-hooks.ts

@@ -0,0 +1,42 @@
+/**
+ * 회원 탈퇴 훅 레지스트리
+ *
+ * 플러그인/라우트가 활성화될 때 자신의 탈퇴 cleanup 을 등록한다.
+ * withdraw/handlers.ts 에서 Go 프록시 전에 runWithdrawHooks() 를 호출한다.
+ *
+ * 사용 예:
+ *   // plugins/oauth/index.ts (enabled 체크 후)
+ *   registerWithdrawHook("oauth", async (accountSeq) => {
+ *       await entityServer.deleteWhere("account_oauth", { account_seq: accountSeq });
+ *   });
+ */
+
+export type WithdrawHookFn = (accountSeq: number) => Promise<void>;
+
+const hooks = new Map<string, WithdrawHookFn>();
+
+/**
+ * 탈퇴 cleanup 훅을 등록한다.
+ * @param name  - 플러그인/라우트 식별자 (중복 등록 방지용)
+ * @param fn    - account_seq를 받아 관련 데이터를 삭제하는 비동기 함수
+ */
+export function registerWithdrawHook(name: string, fn: WithdrawHookFn): void {
+    hooks.set(name, fn);
+}
+
+/**
+ * 등록된 모든 탈퇴 훅을 순서대로 실행한다.
+ * 개별 훅 실패는 로그 후 계속 진행한다 (탈퇴 자체를 막지 않음).
+ */
+export async function runWithdrawHooks(
+    accountSeq: number,
+    log: (msg: string, extra?: Record<string, unknown>) => void,
+): Promise<void> {
+    for (const [name, fn] of hooks) {
+        try {
+            await fn(accountSeq);
+        } catch (err) {
+            log(`Withdraw hook failed: ${name}`, { err, seq: accountSeq });
+        }
+    }
+}

package/src/system/http/cookie.ts

@@ -0,0 +1,62 @@
+/**
+ * HTTP 쿠키 유틸리티
+ *
+ * 쿠키 파싱, 직렬화, Set-Cookie 헤더 관리
+ */
+
+import type { FastifyReply } from "fastify";
+
+export function parseCookies(
+    cookieHeader: string | undefined,
+): Record<string, string> {
+    if (!cookieHeader) return {};
+    const result: Record<string, string> = {};
+    for (const pair of cookieHeader.split(";")) {
+        const idx = pair.indexOf("=");
+        if (idx < 0) continue;
+        const key = pair.substring(0, idx).trim();
+        const val = pair.substring(idx + 1).trim();
+        result[key] = decodeURIComponent(val);
+    }
+    return result;
+}
+
+export interface CookieOptions {
+    httpOnly: boolean;
+    sameSite: "strict" | "lax" | "none";
+    secure: boolean;
+    path: string;
+    maxAge: number;
+}
+
+export function serializeCookie(
+    name: string,
+    value: string,
+    options: CookieOptions,
+): string {
+    const cookieParts = [
+        `${name}=${encodeURIComponent(value)}`,
+        `Path=${options.path}`,
+        `Max-Age=${options.maxAge}`,
+        `SameSite=${options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1)}`,
+    ];
+    if (options.httpOnly) cookieParts.push("HttpOnly");
+    if (options.secure) cookieParts.push("Secure");
+    return cookieParts.join("; ");
+}
+
+export function appendSetCookie(
+    reply: FastifyReply,
+    cookieValue: string,
+): void {
+    const current = reply.getHeader("Set-Cookie");
+    if (!current) {
+        reply.header("Set-Cookie", cookieValue);
+        return;
+    }
+    if (Array.isArray(current)) {
+        reply.header("Set-Cookie", [...current.map(String), cookieValue]);
+        return;
+    }
+    reply.header("Set-Cookie", [String(current), cookieValue]);
+}

package/src/system/http/response.ts

@@ -0,0 +1,16 @@
+export interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    requestId?: string;
+}
+
+/** 성공 응답 객체를 생성한다. */
+export function ok<T>(data: T, requestId?: string): ApiResponse<T> {
+    return { success: true, data, requestId };
+}
+
+/** 실패 응답 객체를 생성한다. */
+export function fail(error: string, requestId?: string): ApiResponse {
+    return { success: false, error, requestId };
+}

package/src/system/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Entity App Server 엔트리포인트
+ */
+
+import { env, logger, logFmt } from "./config/env.ts";
+import { serverConfig } from "./config/server.ts";
+import { buildApp } from "./app.ts";
+
+/** Entity Server 헬스체크 — 연결 불가 시 FATAL 종료 */
+async function checkEntityServer(): Promise<void> {
+    const url = `${env.ENTITY_SERVER_URL}/v1/health`;
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+        if (!res.ok) {
+            throw new Error(`Entity Server returned HTTP ${res.status}`);
+        }
+    } catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        logger.fatal(
+            logFmt.error(
+                "Entity Server에 연결할 수 없습니다. 서버를 먼저 실행하세요.",
+                `(${env.ENTITY_SERVER_URL}) ${cause}`,
+            ),
+        );
+        // 부모(tsx watch)에 SIGTERM을 보내 watch 루프까지 종료
+        process.kill(process.ppid, "SIGTERM");
+        process.exit(1);
+    }
+}
+
+/** Entity App Server를 시작한다 */
+async function main() {
+    await checkEntityServer();
+
+    try {
+        const { app } = await buildApp();
+
+        await app.listen({
+            port: serverConfig.port,
+            host: serverConfig.host,
+        });
+    } catch (err) {
+        logger.fatal(err, logFmt.error("Failed to start Entity App Server"));
+        process.exit(1);
+    }
+}
+
+main();

package/src/system/logging/log-format.ts

@@ -0,0 +1,50 @@
+/**
+ * 로그 포맷 유틸리티 — ANSI 색상 포맷팅
+ *
+ * 로거 메시지에 카테고리·색상·메타 텍스트를 적용합니다.
+ * dev 모드에서만 색상이 활성화됩니다.
+ */
+
+const isDev = process.env.NODE_ENV === "development";
+
+const ANSI = {
+    reset: "\u001b[0m",
+    cyan: "\u001b[96m",
+    pink: "\u001b[95m",
+    red: "\u001b[91m",
+} as const;
+
+function paint(text: string, color: string): string {
+    return isDev ? `${color}${text}${ANSI.reset}` : text;
+}
+
+function metaText(text?: string): string {
+    return text ? ` ${paint(text, ANSI.pink)}` : "";
+}
+
+export const logFmt = {
+    cache(driver: string, meta?: string) {
+        return `[cache] ${paint(driver, ANSI.cyan)}${metaText(meta)}`;
+    },
+    db(name: string, meta?: string) {
+        return `[db] ${paint(name, ANSI.cyan)}${metaText(meta)}`;
+    },
+    hooks(text: string, meta?: string) {
+        return `[hooks] ${paint(text, ANSI.cyan)}${metaText(meta)}`;
+    },
+    plugin(pathText: string, meta?: string) {
+        return `[plugin] ${paint(pathText, ANSI.cyan)}${metaText(meta)}`;
+    },
+    route(pathText: string, meta?: string) {
+        return `[route] ${paint(pathText, ANSI.cyan)}${metaText(meta)}`;
+    },
+    schedule(pathText: string, meta?: string) {
+        return `[schedule] ${paint(pathText, ANSI.cyan)}${metaText(meta)}`;
+    },
+    server(url: string, mode: string) {
+        return `[server] ${paint(url, ANSI.cyan)}${metaText(`[${mode}]`)}`;
+    },
+    error(message: string, meta?: string) {
+        return `${paint(message, ANSI.red)}${metaText(meta)}`;
+    },
+};

package/src/system/logging/logger.ts

@@ -0,0 +1,104 @@
+/**
+ * Logger 설정 — pino 멀티스트림 로거
+ *
+ * 메인 로거와 접근 로그 전용 로거를 생성합니다.
+ * - dev: pino-pretty 콘솔 + error.log 파일
+ * - prod: stdout + error.log 파일
+ */
+
+import pino from "pino";
+import { serverConfig } from "../config/server.ts";
+
+const isDev = process.env.NODE_ENV === "development";
+import { createDatePrefixedLogStream } from "../utils/date-prefixed-log-stream.ts";
+
+const {
+    level,
+    logDir,
+    access,
+    error: errorLog,
+    app: appLog,
+} = serverConfig.logging;
+
+const DEV_SUPPRESSED_LOG_PATTERNS = [
+    /disabled in config/i,
+    /disabled \(config\.enabled = false\)/i,
+    /disabled \(config\.json enabled=false\)/i,
+    /plugin skipped/i,
+];
+
+function getLogMessage(args: unknown[]): string {
+    for (const arg of args) {
+        if (typeof arg === "string") {
+            return arg;
+        }
+    }
+    return "";
+}
+
+function shouldSuppressDevLog(args: unknown[], level: number): boolean {
+    if (!isDev || level >= 50) {
+        return false;
+    }
+
+    const message = getLogMessage(args);
+    return DEV_SUPPRESSED_LOG_PATTERNS.some((pattern) => pattern.test(message));
+}
+
+/** 메인 로거 — 파일에만 기록 (CLI 출력 없음) */
+const loggerStreams: Array<pino.StreamEntry<pino.Level>> = [
+    ...(appLog.enabled
+        ? [
+              {
+                  level,
+                  stream: createDatePrefixedLogStream({
+                      logDir,
+                      filename: appLog.filename,
+                      frequency: appLog.frequency,
+                      maxFiles: appLog.maxFiles,
+                  }),
+              },
+          ]
+        : []),
+    ...(errorLog.enabled
+        ? [
+              {
+                  level: "error" as const,
+                  stream: createDatePrefixedLogStream({
+                      logDir,
+                      filename: errorLog.filename,
+                      frequency: errorLog.frequency,
+                      maxFiles: errorLog.maxFiles,
+                  }),
+              },
+          ]
+        : []),
+];
+
+export const logger = pino(
+    {
+        level,
+        hooks: {
+            logMethod(args, method, levelNumber) {
+                if (shouldSuppressDevLog(args, levelNumber)) {
+                    return;
+                }
+                method.apply(this, args);
+            },
+        },
+    },
+    pino.multistream(loggerStreams),
+);
+
+/** 접근 로그 전용 로거 — 날짜-prefix access 로그 파일에 기록 (dev 포함) */
+export const accessLogger: pino.Logger | null = access.enabled
+    ? pino(
+          { level: "info" },
+          createDatePrefixedLogStream({
+              logDir,
+              filename: access.filename,
+              frequency: access.frequency,
+              maxFiles: access.maxFiles,
+          }),
+      )
+    : null;

package/src/system/middleware/_db-ref.ts

@@ -0,0 +1,26 @@
+/**
+ * DB store 전역 참조 — 순환 참조 방지용 내부 모듈
+ */
+
+import type { Kysely } from "kysely";
+
+type KyselyDb = Kysely<any>;
+
+let _db: KyselyDb | null = null;
+let _dbGroups: Record<string, KyselyDb> = {};
+
+export function _setDbRef(
+    db: KyselyDb | null,
+    groups: Record<string, KyselyDb>,
+): void {
+    _db = db;
+    _dbGroups = groups;
+}
+
+export function _getDb(): KyselyDb | null {
+    return _db;
+}
+
+export function _getDbGroup(group: string): KyselyDb | null {
+    return _dbGroups[group] ?? null;
+}

package/src/system/middleware/_push-ref.ts

@@ -0,0 +1,28 @@
+/**
+ * Push Service 전역 참조 — 순환 참조 방지용 내부 모듈
+ *
+ * plugins/push/index.ts 에서 서비스 시작 시 _setPushServiceRef() 를 호출한다.
+ * system/push/sender.ts 에서 _getPushService() 로 서비스를 사용한다.
+ */
+
+export interface PushServiceRef {
+    enqueueJob(job: {
+        account_seq: number;
+        title: string;
+        body: string;
+        data?: Record<string, string>;
+        ref_entity?: string;
+        ref_seq?: number;
+        provider?: string;
+    }): Promise<void>;
+}
+
+let _pushService: PushServiceRef | null = null;
+
+export function _setPushServiceRef(svc: PushServiceRef | null): void {
+    _pushService = svc;
+}
+
+export function _getPushService(): PushServiceRef | null {
+    return _pushService;
+}

package/src/system/middleware/access-log.ts

@@ -0,0 +1,34 @@
+/**
+ * Access Log 플러그인 — HTTP 요청/응답을 access.log 파일에 기록
+ *
+ * server.json의 logging.access.enabled 가 true 일 때만 활성화됩니다.
+ * 기록 항목: method, url, statusCode, 응답시간(ms), IP, requestId, User-Agent
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { accessLogger } from "../logging/logger.ts";
+import { parseUserAgent } from "../utils/user-agent.ts";
+
+export default fp(async (app: FastifyInstance) => {
+    if (!accessLogger) return;
+
+    const logger = accessLogger;
+    app.addHook("onResponse", (request, reply, done) => {
+        const userAgent = parseUserAgent(request.headers["user-agent"]);
+        logger.info({
+            requestId: request.id,
+            method: request.method,
+            url: request.url,
+            statusCode: reply.statusCode,
+            responseTime: Math.round(reply.elapsedTime),
+            ip: request.ip,
+            userAgent: userAgent.raw || null,
+            platform: userAgent.platform ?? null,
+            deviceType: userAgent.deviceType ?? null,
+            browser: userAgent.browser ?? null,
+            browserVersion: userAgent.browserVersion ?? null,
+        });
+        done();
+    });
+});