create-entity-app-server 0.0.3

package/src/app/plugins/distance-server/service.ts

@@ -0,0 +1,187 @@
+import { createHmac } from "node:crypto";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { logger } from "../../../system/config/env.ts";
+import { loadDistanceServerConfig } from "./config.ts";
+
+function signDistanceRequest(
+    secret: string,
+    method: string,
+    path: string,
+    timestamp: string,
+): string {
+    return createHmac("sha256", secret)
+        .update(`${method}${path}${timestamp}`)
+        .digest("hex");
+}
+
+function buildUpstreamUrl(
+    baseUrl: string,
+    path: string,
+    queryString: string,
+): string {
+    return `${baseUrl}${path}${queryString ? `?${queryString}` : ""}`;
+}
+
+function buildRequestBody(body: unknown): string | Uint8Array | undefined {
+    if (body == null) return undefined;
+    if (typeof body === "string") return body;
+    if (body instanceof Uint8Array) return body;
+    return JSON.stringify(body);
+}
+
+function copyRequestHeaders(
+    request: FastifyRequest,
+    body: string | Uint8Array | undefined,
+): Headers {
+    const headers = new Headers();
+    const accept = request.headers.accept;
+    const contentType = request.headers["content-type"];
+    const hasBody = body != null;
+    const isBinaryBody = body instanceof Uint8Array;
+
+    if (accept) headers.set("accept", accept);
+    if (isBinaryBody) {
+        headers.set("content-type", contentType || "application/octet-stream");
+    } else if (hasBody) {
+        headers.set("content-type", "application/json");
+    }
+
+    return headers;
+}
+
+function summarizeBody(text: string): string | undefined {
+    const normalized = text.trim();
+    if (!normalized) return undefined;
+    return normalized.length > 500
+        ? `${normalized.slice(0, 500)}...`
+        : normalized;
+}
+
+export async function proxyDistanceRequest(
+    request: FastifyRequest,
+    reply: FastifyReply,
+    upstreamPath: string,
+    timeout: number,
+): Promise<unknown> {
+    const config = loadDistanceServerConfig();
+    const requestId = request.headers["x-request-id"] ?? request.id;
+
+    if (!config || !config.userSecret) {
+        logger.error(
+            {
+                requestId,
+                method: request.method,
+                url: request.url,
+                upstreamPath,
+            },
+            "distance-server proxy is not configured",
+        );
+        reply.code(503).send({
+            error: "distance-server user proxy is not configured",
+        });
+        return;
+    }
+
+    const method = request.method.toUpperCase();
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const queryString = request.url.split("?")[1] ?? "";
+    const body = buildRequestBody(request.body);
+    const headers = copyRequestHeaders(request, body);
+    logger.info(
+        {
+            requestId,
+            method,
+            url: request.url,
+            upstreamPath,
+            requestBodyType:
+                request.body == null
+                    ? String(request.body)
+                    : Buffer.isBuffer(request.body)
+                      ? "buffer"
+                      : typeof request.body,
+            proxiedBodyType:
+                body == null
+                    ? String(body)
+                    : body instanceof Uint8Array
+                      ? "uint8array"
+                      : typeof body,
+        },
+        "distance-server proxy request start",
+    );
+
+    headers.set("x-role", "user");
+    headers.set("x-timestamp", timestamp);
+    headers.set(
+        "x-signature",
+        signDistanceRequest(config.userSecret, method, upstreamPath, timestamp),
+    );
+
+    const upstreamUrl = buildUpstreamUrl(config.url, upstreamPath, queryString);
+
+    try {
+        const response = await fetch(upstreamUrl, {
+            method,
+            headers,
+            body,
+            signal: AbortSignal.timeout(config.timeout ?? timeout),
+        });
+
+        reply.code(response.status);
+
+        const contentType = response.headers.get("content-type");
+        if (contentType) {
+            reply.header("content-type", contentType);
+        }
+
+        const text = await response.text();
+
+        logger.info(
+            {
+                requestId,
+                method,
+                url: request.url,
+                upstreamUrl,
+                upstreamStatus: response.status,
+                responseContentType: contentType,
+                responseLength: text.length,
+            },
+            "distance-server proxy response received",
+        );
+
+        if (response.status >= 500) {
+            logger.error(
+                {
+                    requestId,
+                    method,
+                    url: request.url,
+                    upstreamUrl,
+                    upstreamStatus: response.status,
+                    upstreamBody: summarizeBody(text),
+                },
+                "distance-server upstream returned server error",
+            );
+        }
+
+        if (!text) {
+            return null;
+        }
+
+        if (contentType?.includes("application/json")) {
+            return JSON.parse(text);
+        }
+
+        return text;
+    } catch (err) {
+        logger.error(
+            {
+                err,
+                requestId,
+                method,
+                url: request.url,
+                upstreamUrl,
+            },
+            "distance-server proxy request failed",
+        );
+        throw err;
+    }
+}

package/src/app/plugins/distance-server/types/index.ts

@@ -0,0 +1,8 @@
+/** configs/plugins/distance-server/config.json 스키마 */
+export interface DistanceServerConfig {
+    enabled: boolean; // 플러그인 활성화 여부
+    minify?: boolean; // 빌드 시 난독화 여부
+    url: string; // Rust distance-server URL
+    userSecret?: string; // distance-server user HMAC secret
+    timeout?: number; // 프록시 타임아웃 (ms)
+}

package/src/app/plugins/example/config.json

@@ -0,0 +1,6 @@
+{
+    "_comment": "예제 플러그인 — 새 플러그인 개발 시 이 파일을 복사해서 시작하세요",
+    "enabled": false,
+    "deploy": true,
+    "minify": false
+}

package/src/app/plugins/example/config.ts

@@ -0,0 +1,46 @@
+/**
+ * example 플러그인 설정 로더
+ *
+ * 플러그인 디렉토리의 config.json을 읽어 ExampleConfig를 반환합니다.
+ * 파일이 없거나 enabled: false이면 null을 반환합니다.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { ExampleConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+/** example 설정을 로드한다 */
+export function loadExampleConfig(): ExampleConfig | null {
+    try {
+        let raw = readFileSync(CONFIG_PATH, "utf-8");
+
+        // 환경변수 치환: ${VAR} → process.env.VAR
+        raw = raw.replace(
+            /\$\{([^}]+)\}/g,
+            (_match, name) => process.env[name] ?? "",
+        );
+
+        const cfg: ExampleConfig = JSON.parse(raw);
+
+        if (cfg.enabled === false) {
+            logger.info("Example plugin disabled in config");
+            return null;
+        }
+
+        // TODO: 기본값 보정이 필요하면 여기에 추가합니다.
+
+        return cfg;
+    } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            logger.info("Example config not found, plugin skipped");
+        } else {
+            logger.error({ err }, "Failed to load example config");
+        }
+        return null;
+    }
+}

package/src/app/plugins/example/docs/README.md

@@ -0,0 +1,64 @@
+# Example 플러그인 (개발 템플릿)
+
+새 플러그인을 개발할 때 참고하는 템플릿입니다. 기본 CRUD 구조, 엔티티 등록, 서비스 패턴이 포함되어 있습니다.
+
+> 프로덕션에서는 `enabled: false`로 유지하거나 해당 폴더를 복사해 새 플러그인을 만드세요.
+
+---
+
+## 플러그인 생성 절차
+
+1. `src/app/plugins/example/` 폴더를 복사해 새 폴더 이름으로 변경
+2. `config.json`에서 `enabled: true` 설정
+3. `types/` — 플러그인 설정 타입 및 데이터 타입 정의
+4. `entities/` — 테이블 스키마 JSON 추가
+5. `service.ts` — 비즈니스 로직 구현
+6. `entity-adapter.ts` — DB 쿼리 어댑터 구현
+7. `handlers.ts` — 요청 핸들러 구현
+8. `routes.ts` — 라우트 등록
+9. `index.ts` — 플러그인 초기화 (엔티티 등록, 서비스 시작, 데코레이션)
+
+---
+
+## 기본 파일 구조
+
+```
+example/
+├── config.json          # 플러그인 설정
+├── config.ts            # 설정 로드 헬퍼
+├── index.ts             # 플러그인 진입점 (초기화)
+├── routes.ts            # HTTP 라우트 등록
+├── service.ts           # 비즈니스 로직
+├── entity-adapter.ts    # DB 쿼리 어댑터
+├── handlers.ts          # 요청 핸들러
+├── types/
+│   └── index.ts         # 타입 정의
+└── entities/
+    └── example.json     # 엔티티 스키마
+```
+
+---
+
+## 기본 CRUD 엔드포인트 패턴
+
+| 메서드   | 경로    | 설명      |
+| -------- | ------- | --------- |
+| `GET`    | `/`     | 목록 조회 |
+| `GET`    | `/:seq` | 단건 조회 |
+| `POST`   | `/`     | 생성      |
+| `PUT`    | `/:seq` | 수정      |
+| `DELETE` | `/:seq` | 삭제      |
+
+---
+
+## config.json
+
+```json
+{
+    "enabled": false,
+    "deploy": true,
+    "minify": false
+}
+```
+
+> 새 플러그인 개발 시 `enabled: true`로 변경하고, 프로덕션에서 사용하지 않을 경우 `deploy: false`로 빌드에서 제외하세요.

package/src/app/plugins/example/entity-adapter.ts

@@ -0,0 +1,96 @@
+/**
+ * ExampleEntityAdapter — Entity Server 어댑터
+ *
+ * entity-server-client를 통해 엔티티에 접근하는 계층.
+ * 서비스 로직과 DB/Entity Server를 분리하기 위한 어댑터 패턴.
+ *
+ * 새 확장을 만들 때:
+ *  1. example → 모듈명으로 교체
+ *  2. Querier 인터페이스에 필요한 메서드를 선언
+ *  3. EntityAdapter 클래스에서 entityServer API를 호출하여 구현
+ */
+
+import { entityServer } from "@gateway/api";
+
+// ─── Querier Interface ───────────────────────────────────────────────────────
+
+/** 엔티티 접근 인터페이스 — 서비스에서 이 인터페이스만 의존한다 */
+export interface ExampleQuerier {
+    /** 레코드를 생성하고 seq를 반환한다 */
+    create(data: Record<string, unknown>): Promise<number>;
+
+    /** seq로 단건 조회한다 */
+    getBySeq(seq: number): Promise<Record<string, unknown> | null>;
+
+    /** 조건으로 목록을 조회한다 */
+    list(
+        filter: ExampleFilter,
+    ): Promise<{ items: Record<string, unknown>[]; total: number }>;
+
+    /** 레코드를 수정한다 */
+    update(seq: number, patch: Record<string, unknown>): Promise<void>;
+
+    /** 레코드를 삭제한다 */
+    remove(seq: number): Promise<void>;
+}
+
+export interface ExampleFilter {
+    page?: number;
+    limit?: number;
+    orderBy?: string;
+    orderDir?: "ASC" | "DESC";
+    conditions?: Record<string, unknown>;
+}
+
+// ─── Entity Adapter 구현 ────────────────────────────────────────────────────
+
+/** Entity Server 기반 Querier 구현 */
+export class ExampleEntityAdapter implements ExampleQuerier {
+    /** 대상 엔티티 이름 (entities/*.json) */
+    private readonly entity: string;
+
+    constructor(entity = "example") {
+        this.entity = entity;
+    }
+
+    async create(data: Record<string, unknown>): Promise<number> {
+        const resp = await entityServer.submit(this.entity, data);
+        return (resp as any).seq ?? 0;
+    }
+
+    async getBySeq(seq: number): Promise<Record<string, unknown> | null> {
+        const resp = await entityServer.list(this.entity, {
+            conditions: { seq },
+            limit: 1,
+        });
+        const items = ((resp as any).data?.items ??
+            (resp as any).items ??
+            []) as Record<string, unknown>[];
+        return items.length > 0 ? items[0] : null;
+    }
+
+    async list(
+        filter: ExampleFilter,
+    ): Promise<{ items: Record<string, unknown>[]; total: number }> {
+        const resp = await entityServer.list(this.entity, {
+            conditions: filter.conditions,
+            limit: filter.limit ?? 20,
+            page: filter.page ?? 1,
+            orderBy: filter.orderBy,
+            orderDir: filter.orderDir,
+        });
+        const data = (resp as any).data ?? resp;
+        return {
+            items: (data.items ?? []) as Record<string, unknown>[],
+            total: (data.total ?? 0) as number,
+        };
+    }
+
+    async update(seq: number, patch: Record<string, unknown>): Promise<void> {
+        await entityServer.submit(this.entity, { ...patch, seq });
+    }
+
+    async remove(seq: number): Promise<void> {
+        await entityServer.delete(this.entity, seq);
+    }
+}

package/src/app/plugins/example/handlers.ts

@@ -0,0 +1,94 @@
+/**
+ * example API 핸들러
+ *
+ * 새 확장을 만들 때:
+ *  1. example → 모듈명으로 교체
+ *  2. 각 핸들러에 비즈니스 로직을 작성
+ *  3. ensureSvc 패턴으로 서비스 비활성 시 503 반환
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+
+// ─── 헬퍼 ────────────────────────────────────────────────────────────────────
+
+/** exampleService가 없으면 503을 반환하고 null을 리턴한다 */
+const ensureSvc = (req: FastifyRequest, reply: FastifyReply) => {
+    if (!req.server.exampleService) {
+        reply.status(503).send(fail("Example plugin not enabled"));
+        return null;
+    }
+    return req.server.exampleService;
+};
+
+// ─── 핸들러 ──────────────────────────────────────────────────────────────────
+
+/** GET / — 목록 조회 */
+export async function handleList(request: FastifyRequest, reply: FastifyReply) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    // TODO: 쿼리 파라미터 파싱, 서비스 호출
+    const items: unknown[] = [];
+    return ok({ items, total: 0 });
+}
+
+/** GET /:seq — 단건 조회 */
+export async function handleGet(request: FastifyRequest, reply: FastifyReply) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { seq } = request.params as { seq: string };
+    if (!seq) {
+        return reply.status(400).send(fail("seq is required"));
+    }
+
+    // TODO: 서비스 호출
+    return reply.status(404).send(fail("not found"));
+}
+
+/** POST / — 생성 */
+export async function handleCreate(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const body = (request.body ?? {}) as Record<string, unknown>;
+
+    // TODO: 입력 검증, 서비스 호출
+    return ok({ created: true });
+}
+
+/** PUT /:seq — 수정 */
+export async function handleUpdate(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { seq } = request.params as { seq: string };
+    const body = (request.body ?? {}) as Record<string, unknown>;
+
+    // TODO: 입력 검증, 서비스 호출
+    return ok({ updated: true });
+}
+
+/** DELETE /:seq — 삭제 */
+export async function handleDelete(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const { seq } = request.params as { seq: string };
+    if (!seq) {
+        return reply.status(400).send(fail("seq is required"));
+    }
+
+    // TODO: 서비스 호출
+    return ok({ deleted: true });
+}

package/src/app/plugins/example/index.ts

@@ -0,0 +1,63 @@
+/**
+ * example 플러그인 Fastify 플러그인
+ *
+ * 설정 로드 → 엔티티 자동 등록 → 서비스 초기화 → app 데코레이터 등록 → graceful shutdown
+ *
+ * 새 플러그인을 만들 때 이 파일을 복사해서 시작하세요:
+ *  1. example → 모듈명으로 전체 교체
+ *  2. types/config.ts에 Config 인터페이스 정의
+ *  3. 플러그인 디렉토리에 config.json 작성 (enabled, minify 포함)
+ *  4. entities/*.json 에 플러그인이 사용하는 엔티티 설정 파일 추가
+ *  5. service.ts에 비즈니스 로직 구현
+ *  6. entity-adapter.ts에 Entity Server 연동 구현
+ *  7. handlers.ts에 HTTP 핸들러 작성
+ *  8. routes.ts에 라우트 테이블 선언
+ *  9. 필요하면 declare module 블록으로 app 데코레이터 타입 추가
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadExampleConfig } from "./config.ts";
+import { ExampleService } from "./service.ts";
+import { ensurePluginEntities } from "@gateway/api";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// app.exampleService 타입을 Fastify 인스턴스에 추가한다.
+// 라우트 핸들러에서 app.exampleService로 접근 가능해진다.
+declare module "fastify" {
+    interface FastifyInstance {
+        exampleService: ExampleService | null;
+    }
+}
+
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadExampleConfig();
+
+        if (!config) {
+            app.decorate("exampleService", null);
+            return;
+        }
+
+        // entities/ 폴더의 엔티티 JSON을 Go 엔티티 서버에 자동 등록
+        // 이미 존재하는 엔티티는 스킵됨 (already_exists)
+        await ensurePluginEntities(__dirname).catch((err) =>
+            app.log.warn({ err }, "Example: entity setup failed, continuing"),
+        );
+
+        const service = new ExampleService(config);
+
+        await service.start();
+
+        app.decorate("exampleService", service);
+
+        // graceful shutdown
+        app.addHook("onClose", async () => {
+            service.stop();
+        });
+    },
+    { name: "example-plugin" },
+);

package/src/app/plugins/example/routes.ts

@@ -0,0 +1,30 @@
+/**
+ * example 라우트 테이블
+ * 등록 경로: /api/v1/example/*
+ *
+ * 새 확장을 만들 때:
+ *  1. example → 모듈명으로 교체
+ *  2. 필요한 HTTP 메서드 / 경로를 추가
+ *  3. handlers.ts에 대응하는 핸들러 함수를 작성
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+/** example 라우트를 등록한다 */
+export default async function exampleRoutes(app: FastifyInstance) {
+    // GET /api/v1/example/ — 목록 조회
+    app.get("/", h.handleList);
+
+    // GET /api/v1/example/:seq — 단건 조회
+    app.get("/:seq", h.handleGet);
+
+    // POST /api/v1/example/ — 생성
+    app.post("/", h.handleCreate);
+
+    // PUT /api/v1/example/:seq — 수정
+    app.put("/:seq", h.handleUpdate);
+
+    // DELETE /api/v1/example/:seq — 삭제
+    app.delete("/:seq", h.handleDelete);
+}

package/src/app/plugins/example/service.ts

@@ -0,0 +1,31 @@
+/**
+ * example 서비스
+ *
+ * TODO: 비즈니스 로직을 여기에 구현합니다.
+ */
+
+import { logger } from "@gateway/api";
+import type { ExampleConfig } from "./types/index.ts";
+import { ExampleEntityAdapter, type ExampleQuerier } from "./entity-adapter.ts";
+
+export class ExampleService {
+    private readonly config: ExampleConfig;
+    private readonly querier: ExampleQuerier;
+
+    constructor(config: ExampleConfig) {
+        this.config = config;
+        this.querier = new ExampleEntityAdapter();
+    }
+
+    /** 서비스를 시작한다 */
+    async start(): Promise<void> {
+        // TODO: 초기화 로직
+        logger.info("ExampleService started");
+    }
+
+    /** 서비스를 정지한다 */
+    stop(): void {
+        // TODO: 정리 로직
+        logger.info("ExampleService stopped");
+    }
+}

package/src/app/plugins/example/types/config.ts

@@ -0,0 +1,11 @@
+/** configs/extensions/example.json 스키마 */
+export interface ExampleConfig {
+    enabled: boolean; // 확장 활성화 여부
+
+    minify?: boolean; // 빌드 시 난독화 여부 (build:minify-plugins 적용 대상)
+
+    // TODO: 추가 설정 필드를 여기에 선언합니다.
+    // 예:
+    // api_key: string;
+    // endpoint: string;
+}

package/src/app/plugins/example/types/index.ts

@@ -0,0 +1 @@
+export * from "./config.ts";

package/src/app/plugins/friendtalk/config.example.json

@@ -0,0 +1,35 @@
+{
+    "_comment": "친구톡 설정 — enabled: false로 비활성화 상태",
+    "_note": "친구톡은 알림톡과 달리 사전 등록 템플릿 코드 없이 자유 형식으로 발송합니다. 본문 템플릿(content 패턴)은 templates/notification/friendtalk.json에 정의합니다.",
+    "_template_file": "templates/notification/friendtalk.json",
+    "enabled": false,
+    "default": "solapi",
+    "workers": 2,
+    "ad_prefix": "(광고)",
+    "default_ad": true,
+    "providers": {
+        "solapi": {
+            "driver": "solapi",
+            "_comment": "솔라피 (Solapi)",
+            "api_key": "${SOLAPI_API_KEY}",
+            "api_secret": "${SOLAPI_API_SECRET}",
+            "pf_id": "${SOLAPI_PF_ID}",
+            "api_url": "https://api.solapi.com"
+        },
+        "aligo": {
+            "driver": "aligo",
+            "_comment": "알리고",
+            "api_key": "${ALIGO_API_KEY}",
+            "user_id": "${ALIGO_USER_ID}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}"
+        },
+        "nhncloud": {
+            "driver": "nhncloud",
+            "_comment": "NHN Cloud",
+            "app_key": "${NHNCLOUD_APP_KEY}",
+            "secret_key": "${NHNCLOUD_SECRET_KEY}",
+            "plus_friend_id": "${KAKAO_PLUS_FRIEND_ID}",
+            "api_url": "https://api-friendtalk.cloud.toast.com"
+        }
+    }
+}