create-entity-app-server 0.0.4 → 0.1.14

package/dist-create/template/app/plugins/sms/entity-adapter.ts

@@ -0,0 +1,213 @@
+/**
+ * SmsQuerier — Entity Server 어댑터
+ *
+ * entity-server-client를 통해 sms_log, sms_msg 엔티티에 접근.
+ * DB 큐 패턴: pending → processing → sent/failed
+ *
+ * Go 엔티티서버 `internal/sms/entity_adapter.go`에서 포팅
+ *
+ * Note: Go의 CompareAndSwap는 구현하지 않음.
+ *       단일 Node.js 프로세스이므로 dispatch loop에서 순차 처리하여 동시성 문제 방지.
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import type { SmsQuerier, PendingSmsLog, VerificationQuerier } from "./types/index.ts";
+
+export class SmsEntityAdapter implements SmsQuerier {
+    constructor(private readonly maxRetries: number = 3) {}
+
+    /** SMS 발송 로그를 등록한다 */
+    async submitSmsLog(data: Record<string, unknown>): Promise<void> {
+        await entityServer.submit("sms_log", data);
+    }
+
+    /** 대기 중인 SMS 로그를 조회·점유한다 */
+    async claimPendingSmsLogs(limit: number): Promise<PendingSmsLog[]> {
+        const resp = await entityServer.list("sms_log", {
+            status: "pending",
+            page: 1,
+            limit,
+            order: "seq",
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<string, unknown>[];
+        const logs: PendingSmsLog[] = [];
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+
+            // pending → processing (단일 프로세스이므로 CAS 대신 직접 갱신)
+            try {
+                await entityServer.submit("sms_log", {
+                    seq,
+                    status: "processing",
+                });
+                logs.push({
+                    log_seq: seq,
+                    provider: String(item.provider ?? ""),
+                    sender: String(item.sender ?? ""),
+                    receiver: String(item.receiver ?? ""),
+                    content: String(item.content ?? ""),
+                    subject: String(item.subject ?? ""),
+                    msg_type: String(item.msg_type ?? ""),
+                    image_url: String(item.image_url ?? ""),
+                    retry_count: Number(item.retry_count ?? 0),
+                    sms_msg_seq: Number(item.sms_msg_seq ?? 0),
+                });
+            } catch (err) {
+                logger.warn(
+                    { err, seq },
+                    "SMS: failed to claim log, skipping",
+                );
+            }
+        }
+
+        return logs;
+    }
+
+    /** SMS 로그 상태를 갱신한다 */
+    async updateSmsLogStatus(
+        logSeq: number,
+        status: string,
+        providerMsgId: string,
+        errMsg: string,
+    ): Promise<void> {
+        const data: Record<string, unknown> = {
+            status,
+            provider_msg_id: providerMsgId,
+            error_message: errMsg,
+        };
+        if (status === "sent") {
+            data.sent_at = "now()";
+        }
+        await entityServer.submit("sms_log", { seq: logSeq, ...data });
+    }
+
+    /** 서버 시작 시 stale processing 로그를 복구한다 */
+    async resetStaleSmsLogs(): Promise<void> {
+        const resp = await entityServer.list("sms_log", {
+            status: "processing",
+            page: 1,
+            limit: 1000,
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<string, unknown>[];
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            const retryCount = Number(item.retry_count ?? 0);
+
+            if (seq <= 0) continue;
+
+            try {
+                if (retryCount >= this.maxRetries) {
+                    await entityServer.submit("sms_log", {
+                        seq,
+                        status: "failed",
+                        error_message: "max retries exceeded (stale recovery)",
+                    });
+                } else {
+                    await entityServer.submit("sms_log", {
+                        seq,
+                        status: "pending",
+                        retry_count: retryCount + 1,
+                    });
+                }
+            } catch (err) {
+                logger.warn(
+                    { err, seq },
+                    "SMS: failed to reset stale log",
+                );
+            }
+        }
+
+        if (items.length > 0) {
+            logger.info(
+                `SMS: reset ${items.length} stale processing logs`,
+            );
+        }
+    }
+
+    /** sms_msg 상태를 갱신한다 */
+    async updateSmsMsgStatus(
+        msgSeq: number,
+        status: string,
+    ): Promise<void> {
+        if (msgSeq <= 0) return;
+        try {
+            await entityServer.submit("sms_msg", { seq: msgSeq, status });
+        } catch (err) {
+            logger.warn(
+                { err, msgSeq },
+                "SMS: failed to update sms_msg status",
+            );
+        }
+    }
+}
+
+/** SMS 인증번호 Entity Adapter */
+export class SmsVerificationEntityAdapter implements VerificationQuerier {
+    /** 인증번호 레코드를 등록하고 seq를 반환한다 */
+    async submitVerification(
+        data: Record<string, unknown>,
+    ): Promise<number> {
+        const resp = await entityServer.submit("sms_verification", data);
+        return resp.seq ?? 0;
+    }
+
+    /** 대기 중인 인증번호 레코드를 조회한다 */
+    async findPendingVerification(
+        phone: string,
+        purpose: string,
+    ): Promise<Record<string, unknown> | null> {
+        const resp = await entityServer.list("sms_verification", {
+            phone,
+            purpose,
+            status: "pending",
+            page: 1,
+            limit: 1,
+            order: "-seq",
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<string, unknown>[];
+        return items[0] ?? null;
+    }
+
+    /** 인증번호 레코드를 갱신한다 */
+    async updateVerification(
+        seq: number,
+        data: Record<string, unknown>,
+    ): Promise<void> {
+        await entityServer.submit("sms_verification", { seq, ...data });
+    }
+
+    /** 동일 전화번호+목적의 이전 pending 건을 모두 만료시킨다 */
+    async expireOldVerifications(
+        phone: string,
+        purpose: string,
+    ): Promise<void> {
+        const resp = await entityServer.list("sms_verification", {
+            phone,
+            purpose,
+            status: "pending",
+            page: 1,
+            limit: 100,
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<string, unknown>[];
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+            try {
+                await entityServer.submit("sms_verification", {
+                    seq,
+                    status: "expired",
+                });
+            } catch {
+                // best-effort
+            }
+        }
+    }
+}

package/dist-create/template/app/plugins/sms/handlers.ts

@@ -0,0 +1,149 @@
+/**
+ * SMS 라우트 핸들러
+ *
+ * Go 엔티티서버 `internal/handler/sms_handler.go`에서 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, BadRequestError } from "@gateway/api";
+import type { SmsService } from "./service.ts";
+import type { VerificationService } from "./verification.ts";
+
+// 핸들러 팩토리에서 서비스 인스턴스를 주입받는다
+let smsService: SmsService | null = null;
+let verificationService: VerificationService | null = null;
+
+export function initHandlers(
+    sms: SmsService,
+    verification: VerificationService | null,
+): void {
+    smsService = sms;
+    verificationService = verification;
+}
+
+/** POST /api/v1/sms/send — SMS/LMS/MMS 발송 큐 등록 */
+export async function handleSend(
+    req: FastifyRequest<{
+        Body: {
+            provider?: string;
+            sender?: string;
+            receiver: string;
+            content: string;
+            subject?: string;
+            image_url?: string;
+            ref_entity?: string;
+            ref_seq?: number;
+        };
+    }>,
+    reply: FastifyReply,
+): Promise<void> {
+    if (!smsService) {
+        reply.code(503).send(fail("SMS service not available"));
+        return;
+    }
+
+    const body = req.body;
+    if (!body.receiver) {
+        throw new BadRequestError("receiver is required");
+    }
+    if (!body.content) {
+        throw new BadRequestError("content is required");
+    }
+
+    await smsService.enqueueJob({
+        provider: body.provider ?? "",
+        sender: body.sender ?? "",
+        receiver: body.receiver,
+        content: body.content,
+        subject: body.subject ?? "",
+        msg_type: "",
+        image_url: body.image_url ?? "",
+        ref_entity: body.ref_entity ?? "",
+        ref_seq: body.ref_seq ?? 0,
+        sms_msg_seq: 0,
+    });
+
+    reply.send(ok({ message: "SMS queued for delivery" }));
+}
+
+/** GET /api/v1/sms/status/:seq — 발송 상태 조회 */
+export async function handleStatus(
+    req: FastifyRequest<{ Params: { seq: string } }>,
+    reply: FastifyReply,
+): Promise<void> {
+    // 상태 조회는 엔티티 API를 직접 사용하도록 안내
+    reply.send(ok({
+        message:
+            "Use entity API: GET /api/v1/entity/sms_log/{seq} to check SMS delivery status",
+    }));
+}
+
+/** POST /api/v1/sms/verification/send — 인증번호 발송 */
+export async function handleVerificationSend(
+    req: FastifyRequest<{
+        Body: {
+            phone: string;
+            purpose?: string;
+        };
+    }>,
+    reply: FastifyReply,
+): Promise<void> {
+    if (!verificationService) {
+        reply.code(503).send(fail("SMS verification service not available"));
+        return;
+    }
+
+    const body = req.body;
+    if (!body.phone) {
+        throw new BadRequestError("phone is required");
+    }
+
+    const purpose = body.purpose ?? "signup";
+    const expiresIn = await verificationService.sendVerificationCode(
+        body.phone,
+        purpose,
+    );
+
+    reply.send(ok({ expires_in: expiresIn }));
+}
+
+/** POST /api/v1/sms/verification/verify — 인증번호 검증 */
+export async function handleVerificationVerify(
+    req: FastifyRequest<{
+        Body: {
+            phone: string;
+            purpose?: string;
+            code: string;
+        };
+    }>,
+    reply: FastifyReply,
+): Promise<void> {
+    if (!verificationService) {
+        reply.code(503).send(fail("SMS verification service not available"));
+        return;
+    }
+
+    const body = req.body;
+    if (!body.phone) {
+        throw new BadRequestError("phone is required");
+    }
+    if (!body.code) {
+        throw new BadRequestError("code is required");
+    }
+
+    const purpose = body.purpose ?? "signup";
+    const result = await verificationService.verifyCode(
+        body.phone,
+        purpose,
+        body.code,
+    );
+
+    if (!result.verified) {
+        const status = result.error ? 400 : 401;
+        const message = result.error ?? "invalid verification code";
+        reply.code(status).send(fail(message));
+        return;
+    }
+
+    reply.send(ok({ verified: true }));
+}

package/dist-create/template/app/plugins/sms/index.ts

@@ -0,0 +1,93 @@
+/**
+ * SMS Fastify 플러그인
+ *
+ * 설정 로드 → 프로바이더 클라이언트 생성 → Entity Adapter 주입 →
+ * SmsService 시작 → app.smsService 데코레이터 등록
+ *
+ * Go 엔티티서버 `internal/sms/` + `cmd/setup.go`에서 포팅
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { loadSmsConfig } from "./config.ts";
+import { createSmsClient } from "./providers/index.ts";
+import { SmsService } from "./service.ts";
+import {
+    SmsEntityAdapter,
+    SmsVerificationEntityAdapter,
+} from "./entity-adapter.ts";
+import { VerificationService } from "./verification.ts";
+import { initHandlers } from "./handlers.ts";
+import type { SmsClient } from "./types/index.ts";
+
+declare module "fastify" {
+    interface FastifyInstance {
+        smsService: SmsService | null;
+    }
+}
+
+/** SMS 플러그인을 등록한다 */
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadSmsConfig();
+
+        if (!config) {
+            app.decorate("smsService", null);
+            return;
+        }
+
+        // 프로바이더 클라이언트 생성
+        const clients = new Map<string, SmsClient>();
+        for (const [name, provCfg] of Object.entries(config.providers ?? {})) {
+            try {
+                const client = createSmsClient(provCfg);
+                clients.set(name, client);
+                app.log.info(
+                    `SMS provider registered: ${name} (${provCfg.driver})`,
+                );
+            } catch (err) {
+                app.log.error(
+                    err,
+                    `Failed to create SMS provider: ${name} (${provCfg.driver})`,
+                );
+            }
+        }
+
+        if (clients.size === 0) {
+            app.log.warn(
+                "SMS: no valid providers configured, service disabled",
+            );
+            app.decorate("smsService", null);
+            return;
+        }
+
+        const service = new SmsService(config, clients);
+
+        // Entity Adapter 주입
+        service.setQuerier(new SmsEntityAdapter(config.max_retries));
+
+        // 인증번호 서비스 초기화
+        let verificationSvc: VerificationService | null = null;
+        if (config.verification) {
+            verificationSvc = new VerificationService(
+                service,
+                new SmsVerificationEntityAdapter(),
+                config.verification,
+            );
+        }
+
+        // 핸들러에 서비스 주입
+        initHandlers(service, verificationSvc);
+
+        // 서비스 시작 (dispatch loop)
+        await service.start();
+
+        app.decorate("smsService", service);
+
+        // graceful shutdown
+        app.addHook("onClose", async () => {
+            await service.stop();
+        });
+    },
+    { name: "sms-plugin" },
+);

package/dist-create/template/app/plugins/sms/providers/aligo.ts

@@ -0,0 +1,73 @@
+/**
+ * 알리고(Aligo) SMS 프로바이더
+ *
+ * Go 엔티티서버 `internal/sms/client_aligo.go`에서 포팅
+ *
+ * 인증: API Key + User ID (폼 파라미터)
+ * URL: POST https://apis.aligo.in/send/
+ * Content-Type: application/x-www-form-urlencoded
+ */
+
+import type { SmsClient, SendRequest, SendResult, SmsProviderConfig } from "../types/index.ts";
+import { logger } from "@gateway/api";
+
+const ALIGO_API_URL = "https://apis.aligo.in/send/";
+const TIMEOUT_MS = 30_000;
+
+export class AligoClient implements SmsClient {
+    private readonly apiKey: string;
+    private readonly userId: string;
+
+    constructor(cfg: SmsProviderConfig) {
+        this.apiKey = cfg.api_key ?? "";
+        this.userId = cfg.user_id ?? "";
+    }
+
+    name(): string {
+        return "aligo";
+    }
+
+    async send(req: SendRequest): Promise<SendResult> {
+        const params = new URLSearchParams();
+        params.set("key", this.apiKey);
+        params.set("user_id", this.userId);
+        params.set("sender", req.sender);
+        params.set("receiver", req.receiver);
+        params.set("msg", req.content);
+        params.set("msg_type", req.type.toUpperCase()); // SMS, LMS, MMS
+
+        if (req.subject) params.set("title", req.subject);
+        if (req.image_url) params.set("image", req.image_url);
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+        try {
+            const response = await fetch(ALIGO_API_URL, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: params.toString(),
+                signal: controller.signal,
+            });
+
+            const body = (await response.json()) as {
+                result_code: string;
+                message: string;
+                msg_id?: string;
+            };
+
+            if (body.result_code !== "1") {
+                throw new Error(
+                    `Aligo error: code=${body.result_code}, message=${body.message}`,
+                );
+            }
+
+            return {
+                provider_msg_id: body.msg_id ?? "",
+                status_code: body.result_code,
+            };
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+}