create-entity-app-server 0.0.3

package/src/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/src/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/src/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);
+        }
+    }
+}

package/src/app/plugins/sms/providers/aws-sns.ts

@@ -0,0 +1,182 @@
+/**
+ * AWS SNS SMS 프로바이더 (국제 SMS)
+ *
+ * Go 엔티티서버 `internal/sms/client_aws_sns.go`에서 포팅
+ *
+ * 인증: AWS Signature V4 (직접 구현, SDK 미사용)
+ * URL: POST https://sns.{region}.amazonaws.com
+ * Content-Type: application/x-www-form-urlencoded; charset=utf-8
+ * MMS 미지원
+ */
+
+import { createHmac, createHash } from "node:crypto";
+import type { SmsClient, SendRequest, SendResult, SmsProviderConfig } from "../types/index.ts";
+
+const TIMEOUT_MS = 30_000;
+
+export class AWSSNSClient implements SmsClient {
+    private readonly region: string;
+    private readonly accessKey: string;
+    private readonly secretKey: string;
+    /** Transactional | Promotional */
+    private readonly smsType: string;
+
+    constructor(cfg: SmsProviderConfig) {
+        this.region = cfg.region ?? "ap-northeast-2";
+        this.accessKey = cfg.access_key ?? "";
+        this.secretKey = cfg.secret_key ?? "";
+        // api_key 필드를 SMS 타입으로 재활용 (Go 원본 동일)
+        this.smsType = cfg.api_key || "Transactional";
+    }
+
+    name(): string {
+        return "aws_sns";
+    }
+
+    async send(req: SendRequest): Promise<SendResult> {
+        if (req.type.toLowerCase() === "mms") {
+            throw new Error("AWS SNS does not support MMS");
+        }
+
+        const phoneNumber = normalizePhoneE164(req.receiver);
+        const host = `sns.${this.region}.amazonaws.com`;
+        const url = `https://${host}`;
+
+        const params = new URLSearchParams();
+        params.set("Action", "Publish");
+        params.set("Message", req.content);
+        params.set("PhoneNumber", phoneNumber);
+        params.set("Version", "2010-03-31");
+        params.set(
+            "MessageAttributes.entry.1.Name",
+            "AWS.SNS.SMS.SMSType",
+        );
+        params.set(
+            "MessageAttributes.entry.1.Value.DataType",
+            "String",
+        );
+        params.set(
+            "MessageAttributes.entry.1.Value.StringValue",
+            this.smsType,
+        );
+
+        if (req.sender) {
+            params.set(
+                "MessageAttributes.entry.2.Name",
+                "AWS.SNS.SMS.SenderID",
+            );
+            params.set(
+                "MessageAttributes.entry.2.Value.DataType",
+                "String",
+            );
+            params.set(
+                "MessageAttributes.entry.2.Value.StringValue",
+                req.sender,
+            );
+        }
+
+        const bodyStr = params.toString();
+        const now = new Date();
+        const amzDate = now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+        const dateStamp = amzDate.slice(0, 8);
+
+        // AWS Signature V4
+        const contentType =
+            "application/x-www-form-urlencoded; charset=utf-8";
+        const payloadHash = sha256(bodyStr);
+
+        const canonicalRequest = [
+            "POST",
+            "/",
+            "",
+            `content-type:${contentType}`,
+            `host:${host}`,
+            `x-amz-date:${amzDate}`,
+            "",
+            "content-type;host;x-amz-date",
+            payloadHash,
+        ].join("\n");
+
+        const credentialScope = `${dateStamp}/${this.region}/sns/aws4_request`;
+        const stringToSign = [
+            "AWS4-HMAC-SHA256",
+            amzDate,
+            credentialScope,
+            sha256(canonicalRequest),
+        ].join("\n");
+
+        const signingKey = deriveSigningKey(
+            this.secretKey,
+            dateStamp,
+            this.region,
+            "sns",
+        );
+        const signature = hmac(signingKey, stringToSign).toString("hex");
+
+        const authorization = `AWS4-HMAC-SHA256 Credential=${this.accessKey}/${credentialScope}, SignedHeaders=content-type;host;x-amz-date, Signature=${signature}`;
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": contentType,
+                    Host: host,
+                    "X-Amz-Date": amzDate,
+                    Authorization: authorization,
+                },
+                body: bodyStr,
+                signal: controller.signal,
+            });
+
+            const text = await response.text();
+
+            if (!response.ok) {
+                throw new Error(
+                    `AWS SNS error: status=${response.status}, body=${text}`,
+                );
+            }
+
+            // XML에서 <MessageId>...</MessageId> 추출
+            const match = text.match(/<MessageId>([^<]+)<\/MessageId>/);
+            return {
+                provider_msg_id: match?.[1] ?? "",
+                status_code: String(response.status),
+            };
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+
+/** 한국 전화번호를 E.164 형식으로 정규화 */
+function normalizePhoneE164(phone: string): string {
+    if (phone.startsWith("+")) return phone;
+    const cleaned = phone.replace(/[^0-9]/g, "");
+    if (cleaned.startsWith("0")) {
+        return "+82" + cleaned.slice(1);
+    }
+    return "+" + cleaned;
+}
+
+function sha256(data: string): string {
+    return createHash("sha256").update(data, "utf-8").digest("hex");
+}
+
+function hmac(key: Buffer | string, data: string): Buffer {
+    return createHmac("sha256", key).update(data, "utf-8").digest();
+}
+
+function deriveSigningKey(
+    secret: string,
+    dateStamp: string,
+    region: string,
+    service: string,
+): Buffer {
+    const kDate = hmac(Buffer.from("AWS4" + secret, "utf-8"), dateStamp);
+    const kRegion = hmac(kDate, region);
+    const kService = hmac(kRegion, service);
+    return hmac(kService, "aws4_request");
+}

package/src/app/plugins/sms/providers/index.ts

@@ -0,0 +1,47 @@
+/**
+ * SMS 프로바이더 팩토리
+ *
+ * Go 엔티티서버 `internal/sms/client.go` NewClient에서 포팅
+ */
+
+import type { SmsClient, SmsProviderConfig } from "../types/index.ts";
+import { AligoClient } from "./aligo.ts";
+import { SolapiClient } from "./solapi.ts";
+import { PpurioClient } from "./ppurio.ts";
+import { NHNClient } from "./nhn.ts";
+import { AWSSNSClient } from "./aws-sns.ts";
+
+/**
+ * driver 이름에 따라 SmsClient 구현체를 생성한다.
+ */
+export function createSmsClient(cfg: SmsProviderConfig): SmsClient {
+    switch (cfg.driver) {
+        case "aligo":
+            return new AligoClient(cfg);
+        case "solapi":
+            return new SolapiClient(cfg);
+        case "ppurio":
+            return new PpurioClient(cfg);
+        case "nhn_cloud":
+            return new NHNClient(cfg);
+        case "aws_sns":
+            return new AWSSNSClient(cfg);
+        default:
+            throw new Error(`Unknown SMS provider driver: ${cfg.driver}`);
+    }
+}
+
+/**
+ * 메시지 내용과 이미지 유무로 메시지 타입을 자동 판정한다.
+ *
+ * Go 원본: DetermineMsgType(content string, threshold int, imageURL string) string
+ */
+export function determineMsgType(
+    content: string,
+    thresholdBytes: number,
+    imageUrl: string,
+): string {
+    if (imageUrl) return "mms";
+    if (Buffer.byteLength(content, "utf-8") > thresholdBytes) return "lms";
+    return "sms";
+}

package/src/app/plugins/sms/providers/nhn.ts

@@ -0,0 +1,82 @@
+/**
+ * NHN Cloud SMS 프로바이더
+ *
+ * Go 엔티티서버 `internal/sms/client_nhn.go`에서 포팅
+ *
+ * 인증: X-Secret-Key 헤더
+ * URL: POST https://api-sms.cloud.toast.com/sms/v3.0/appKeys/{appKey}/sender/sms (SMS)
+ *      POST https://api-sms.cloud.toast.com/sms/v3.0/appKeys/{appKey}/sender/mms (LMS/MMS)
+ */
+
+import type { SmsClient, SendRequest, SendResult, SmsProviderConfig } from "../types/index.ts";
+
+const NHN_BASE_URL = "https://api-sms.cloud.toast.com/sms/v3.0/appKeys";
+const TIMEOUT_MS = 30_000;
+
+export class NHNClient implements SmsClient {
+    private readonly appKey: string;
+    private readonly secretKey: string;
+
+    constructor(cfg: SmsProviderConfig) {
+        this.appKey = cfg.app_key ?? "";
+        this.secretKey = cfg.secret_key ?? "";
+    }
+
+    name(): string {
+        return "nhn_cloud";
+    }
+
+    async send(req: SendRequest): Promise<SendResult> {
+        const isSms = req.type.toLowerCase() === "sms";
+        const endpoint = isSms ? "sms" : "mms";
+        const url = `${NHN_BASE_URL}/${this.appKey}/sender/${endpoint}`;
+
+        const body: Record<string, unknown> = {
+            sendNo: req.sender,
+            recipientList: [{ recipientNo: req.receiver }],
+            body: req.content,
+        };
+
+        if (!isSms && req.subject) body.title = req.subject;
+        if (!isSms && req.image_url) {
+            body.attachFileList = [{ fileUrl: req.image_url }];
+        }
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json;charset=UTF-8",
+                    "X-Secret-Key": this.secretKey,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+
+            const result = (await response.json()) as {
+                header: {
+                    isSuccessful: boolean;
+                    resultCode: number;
+                    resultMessage: string;
+                };
+                body?: { data?: { requestId?: string } };
+            };
+
+            if (!result.header.isSuccessful) {
+                throw new Error(
+                    `NHN error: code=${result.header.resultCode}, message=${result.header.resultMessage}`,
+                );
+            }
+
+            return {
+                provider_msg_id: result.body?.data?.requestId ?? "",
+                status_code: String(result.header.resultCode),
+            };
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+}

package/src/app/plugins/sms/providers/ppurio.ts

@@ -0,0 +1,76 @@
+/**
+ * 뿌리오(Ppurio) SMS 프로바이더
+ *
+ * Go 엔티티서버 `internal/sms/client_ppurio.go`에서 포팅
+ *
+ * 인증: Bearer Token
+ * URL: POST https://api.ppurio.com/v1/message
+ * Content-Type: application/json
+ */
+
+import type { SmsClient, SendRequest, SendResult, SmsProviderConfig } from "../types/index.ts";
+
+const PPURIO_API_URL = "https://api.ppurio.com/v1/message";
+const TIMEOUT_MS = 30_000;
+
+export class PpurioClient implements SmsClient {
+    private readonly apiKey: string;
+    private readonly account: string;
+
+    constructor(cfg: SmsProviderConfig) {
+        this.apiKey = cfg.api_key ?? "";
+        this.account = cfg.account ?? "";
+    }
+
+    name(): string {
+        return "ppurio";
+    }
+
+    async send(req: SendRequest): Promise<SendResult> {
+        const body: Record<string, unknown> = {
+            account: this.account,
+            messageType: req.type.toUpperCase(),
+            content: req.content,
+            from: req.sender,
+            duplicateFlag: "N",
+            targetCount: 1,
+            targets: [{ to: req.receiver }],
+        };
+
+        if (req.subject) body.subject = req.subject;
+        if (req.image_url) body.fileUrl = req.image_url;
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+        try {
+            const response = await fetch(PPURIO_API_URL, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(
+                    `Ppurio error: status=${response.status}, body=${text}`,
+                );
+            }
+
+            const result = (await response.json()) as {
+                code?: string;
+                requestId?: string;
+            };
+            return {
+                provider_msg_id: result.requestId ?? "",
+                status_code: result.code ?? String(response.status),
+            };
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+}