create-entity-app-server 0.0.3

package/src/system/public-api.ts

@@ -0,0 +1,140 @@
+/**
+ * Gateway 앱 코드(app/)에서 사용하는 공개 API
+ *
+ * 개발: @gateway/api → ./src/system/public-api.ts  (tsconfig paths)
+ * 배포: @gateway/api → ./system-api.js              (dist/tsconfig.json paths)
+ *
+ * import 예시:
+ *   import { ok, fail, logger, entityServer } from "@gateway/api";
+ *   import type { EntityHook } from "@gateway/api";
+ */
+
+export { ok, fail } from "./http/response.ts";
+export { env } from "./config/env.ts";
+export { logger } from "./logging/logger.ts";
+export { logFmt } from "./logging/log-format.ts";
+export { serverConfig } from "./config/server.ts";
+export { ensurePluginEntities } from "./entity-server/bootstrap.ts";
+export {
+    sha256,
+    sha256Hex,
+    encryptAesCbc,
+    decryptAesCbc,
+    encrypt3DesCbc,
+    decrypt3DesCbc,
+    hmacSha256,
+} from "./crypto/cipher.ts";
+export { _setPushServiceRef as registerPushService } from "./middleware/_push-ref.ts";
+export type { PushServiceRef } from "./middleware/_push-ref.ts";
+export { entityServer } from "./config/entity-server.ts";
+export {
+    setSharedLayout,
+    setTemplateDir,
+    renderTemplate,
+    renderString,
+    replaceVars,
+    clearTemplateCache,
+} from "./email/template-engine.ts";
+export { sendEmail } from "./email/sender.ts";
+export type { SendEmailParams } from "./email/sender.ts";
+export { sendPush, sendPushAll } from "./push/sender.ts";
+export type { SendPushParams, SendPushAllParams } from "./push/sender.ts";
+export type {
+    EntityHook,
+    UserInfo,
+    SubmitContext,
+    DeleteContext,
+} from "./hooks/types.ts";
+export {
+    registerWithdrawHook,
+    runWithdrawHooks,
+} from "./hooks/withdraw-hooks.ts";
+export type { WithdrawHookFn } from "./hooks/withdraw-hooks.ts";
+export {
+    AppError,
+    BadRequestError,
+    UnauthorizedError,
+    ForbiddenError,
+    NotFoundError,
+    ConflictError,
+    ValidationError,
+} from "./utils/errors.ts";
+
+// Cache
+export { cache } from "./cache/index.ts";
+export type { CacheStore, CacheDriver } from "./cache/index.ts";
+
+// Kysely 유틸리티 re-export
+export { sql } from "kysely";
+
+// Kysely Database 인터페이스 — DB 직접 접속 시 테이블 타입 매핑
+// DB를 직접 쓰지 않는다면 사용할 필요 없습니다.
+// DB 직접 쿼리 예제: src/app/routes/example-db/
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface Database {
+    [key: string]: any; // 테이블 타입은 프로젝트에서 직접 확장하세요
+}
+
+// DB 헬퍼
+import type { FastifyRequest } from "fastify";
+import { BadRequestError as _BadRequestError } from "./utils/errors.ts";
+import { _getDb, _getDbGroup } from "./middleware/_db-ref.ts";
+
+// 분산 락
+export { acquireLock, releaseLock } from "./scheduler/distributed-lock.ts";
+
+// Cron 유틸리티
+export {
+    createCron,
+    validateCron,
+    describeCron,
+    nextRuns,
+} from "./scheduler/cron-utils.ts";
+export type { CreateCronOptions, CronHandle } from "./scheduler/cron-utils.ts";
+
+// 공통 유틸리티 — 타입 변환
+export { toNumber, toString, toBool } from "./utils/coerce.ts";
+
+// 공통 유틸리티 — HTTP 클라이언트
+export { fetchWithTimeout, fetchJson } from "./utils/http-client.ts";
+
+// 공통 유틸리티 — 포맷팅
+export {
+    extractDigits,
+    normalizePhoneE164,
+    formatSqlDateTime,
+    formatBizNum,
+} from "./utils/format.ts";
+
+// 공통 유틸리티 — 설정 헬퍼
+export { substituteEnvVars } from "./config/env-substitution.ts";
+export { resolveConfigsDir } from "./config/config-path.ts";
+export { resolveModulePath } from "./config/module-path.ts";
+export { loadJsonConfig } from "./config/json-config.ts";
+
+// 공통 유틸리티 — 암호화 / 해시
+export { generateVerificationCode } from "./crypto/random.ts";
+export { hashString, hashBuffer } from "./crypto/hash.ts";
+
+// 비밀번호 정책
+export {
+    validatePassword,
+    loadPasswordPolicy,
+} from "./security/password-policy.ts";
+export type { PasswordPolicy } from "./security/password-policy.ts";
+
+/** Kysely DB 인스턴스를 반환한다. group 생략 시 default 그룹 */
+export function dbConn(group?: string) {
+    if (group) {
+        const db = _getDbGroup(group);
+        if (!db) {
+            throw new _BadRequestError(`Database group "${group}" not found`);
+        }
+        return db;
+    }
+    const db = _getDb();
+    if (!db) {
+        throw new _BadRequestError("Database not configured");
+    }
+    return db;
+}

package/src/system/push/sender.ts

@@ -0,0 +1,131 @@
+/**
+ * 푸시 발송 유틸리티
+ *
+ * 앱서버 PushService 를 직접 사용하여 push_log 큐에 등록한다.
+ * Go 엔티티서버 Push API 를 더 이상 경유하지 않는다.
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import { _getPushService } from "../middleware/_push-ref.ts";
+
+export interface SendPushParams {
+    /** 수신 계정 seq 배열 (1개 이상 필수) */
+    accountSeqs: number[];
+    /** 푸시 제목 */
+    title: string;
+    /** 푸시 본문 */
+    body: string;
+    /** 커스텀 페이로드 */
+    data?: Record<string, string>;
+    /** 참조 엔티티 */
+    refEntity?: string;
+    /** 참조 seq */
+    refSeq?: number;
+    /** 특정 provider 지정 */
+    provider?: string;
+}
+
+export interface SendPushAllParams {
+    /** 푸시 제목 */
+    title: string;
+    /** 푸시 본문 */
+    body: string;
+    /** 커스텀 페이로드 */
+    data?: Record<string, string>;
+    /** 참조 엔티티 */
+    refEntity?: string;
+    /** 참조 seq */
+    refSeq?: number;
+    /** 특정 provider 지정 */
+    provider?: string;
+}
+
+/**
+ * 특정 계정(들)에 푸시를 발송한다.
+ * @returns 큐에 등록된 계정 수
+ */
+export async function sendPush(params: SendPushParams): Promise<number> {
+    const svc = _getPushService();
+    if (!svc) {
+        logger.warn("sendPush: Push service not available");
+        return 0;
+    }
+
+    let queued = 0;
+    for (const accountSeq of params.accountSeqs) {
+        if (accountSeq <= 0) continue;
+        try {
+            await svc.enqueueJob({
+                account_seq: accountSeq,
+                title: params.title,
+                body: params.body,
+                data: params.data,
+                ref_entity: params.refEntity,
+                ref_seq: params.refSeq,
+                provider: params.provider,
+            });
+            queued++;
+        } catch (err) {
+            logger.warn({ err, accountSeq }, "sendPush: failed to enqueue job");
+        }
+    }
+    return queued;
+}
+
+/**
+ * 전체 push 활성 유저에 푸시를 발송한다.
+ * account_device 엔티티에서 push_enabled=true 계정을 조회하여 일괄 발송한다.
+ */
+export async function sendPushAll(
+    params: SendPushAllParams,
+): Promise<{ sent: number; failed: number }> {
+    const svc = _getPushService();
+    if (!svc) {
+        logger.warn("sendPushAll: Push service not available");
+        return { sent: 0, failed: 0 };
+    }
+
+    // push_enabled 디바이스의 고유 account_seq 목록 수집
+    let page = 1;
+    const accountSeqs = new Set<number>();
+    while (true) {
+        const resp = await entityServer.list("account_device", {
+            push_enabled: true,
+            page,
+            limit: 200,
+        } as any);
+        const items = ((resp.data as any)?.items ?? []) as Record<
+            string,
+            unknown
+        >[];
+        if (items.length === 0) break;
+        for (const item of items) {
+            const seq = Number(item.account_seq ?? 0);
+            if (seq > 0) accountSeqs.add(seq);
+        }
+        if (items.length < 200) break;
+        page++;
+    }
+
+    let sent = 0;
+    let failed = 0;
+    for (const accountSeq of accountSeqs) {
+        try {
+            await svc.enqueueJob({
+                account_seq: accountSeq,
+                title: params.title,
+                body: params.body,
+                data: params.data,
+                ref_entity: params.refEntity,
+                ref_seq: params.refSeq,
+                provider: params.provider,
+            });
+            sent++;
+        } catch {
+            failed++;
+        }
+    }
+
+    logger.info({ sent, failed }, "sendPushAll: queued");
+    return { sent, failed };
+}

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

@@ -0,0 +1,327 @@
+/**
+ * 엔티티 훅 인터셉터
+ *
+ * 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);
+}