create-entity-app-server 0.0.3

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

@@ -0,0 +1,297 @@
+/**
+ * Push 알림 발송 서비스
+ *
+ * Go 엔티티서버 `internal/push/service.go` 에서 포팅
+ *
+ * 흐름:
+ *  1. enqueueJob() → 디바이스 조회 → push_log(pending) DB 저장
+ *  2. dispatchLoop (setInterval N초) → pending 조회 → processing claim → processOne
+ *  3. processOne → FCM/APNs 전송 → push_log 상태 갱신 (sent/failed)
+ *  4. 서버 시작 시 → resetStaleLogs → processing → pending 복구
+ */
+
+import { logger } from "@gateway/api";
+import type {
+    PushConfig,
+    PushQuerier,
+    PushJob,
+    PendingPushLog,
+    PushProvider,
+} from "./types/index.ts";
+import {
+    isFcmTokenExpiredError,
+    isApnsTokenExpiredError,
+} from "./providers/index.ts";
+
+export class PushService {
+    private readonly config: PushConfig;
+    private readonly providers: Map<string, PushProvider>;
+
+    private querier: PushQuerier | null = null;
+    private dispatchTimer: ReturnType<typeof setInterval> | null = null;
+    private running = false;
+    private activeDispatch: Promise<void> | null = null;
+
+    constructor(config: PushConfig, providers: Map<string, PushProvider>) {
+        this.config = config;
+        this.providers = providers;
+    }
+
+    setQuerier(q: PushQuerier): void {
+        this.querier = q;
+    }
+
+    getConfig(): PushConfig {
+        return this.config;
+    }
+
+    /** 서비스를 시작한다 (stale 복구 + dispatch loop) */
+    async start(): Promise<void> {
+        if (!this.querier) {
+            logger.warn("Push: querier not set, service will not start");
+            return;
+        }
+
+        // stale processing 로그 복구
+        try {
+            await this.querier.resetStalePushLogs();
+        } catch (err) {
+            logger.warn({ err }, "Push: failed to reset stale logs");
+        }
+
+        this.running = true;
+
+        const intervalMs = (this.config.dispatch_interval_sec || 5) * 1000;
+        this.dispatchTimer = setInterval(() => {
+            const p = this.dispatch().catch((err) =>
+                logger.error({ err }, "Push dispatch error"),
+            );
+            this.activeDispatch = p;
+        }, intervalMs);
+
+        logger.info(
+            `Push service started (workers=${this.config.workers}, interval=${this.config.dispatch_interval_sec}s, providers=${[...this.providers.keys()].join(",")})`,
+        );
+    }
+
+    /** 서비스를 중지한다 */
+    async stop(): Promise<void> {
+        this.running = false;
+        if (this.dispatchTimer) {
+            clearInterval(this.dispatchTimer);
+            this.dispatchTimer = null;
+        }
+        if (this.activeDispatch) {
+            try {
+                await this.activeDispatch;
+            } catch {
+                // best-effort
+            }
+        }
+        logger.info("Push service stopped");
+    }
+
+    /**
+     * Push 발송 작업을 큐에 등록한다.
+     * 계정의 디바이스를 조회하여 각 디바이스별로 push_log(pending)을 생성한다.
+     */
+    async enqueueJob(job: PushJob): Promise<void> {
+        if (!this.querier) {
+            throw new Error("Push service not initialized");
+        }
+
+        // 디바이스 조회
+        let devices;
+        try {
+            devices = await this.querier.listDevicesForAccount(job.account_seq);
+        } catch (err) {
+            logger.warn(
+                { err, account_seq: job.account_seq },
+                "Push: failed to query devices",
+            );
+            return;
+        }
+
+        if (!devices || devices.length === 0) return;
+
+        // push_data 직렬화
+        let pushDataStr = "";
+        if (job.data && Object.keys(job.data).length > 0) {
+            try {
+                pushDataStr = JSON.stringify(job.data);
+            } catch {
+                // ignore
+            }
+        }
+
+        // provider 결정
+        const providerName = job.provider || this.config.default;
+
+        // 디바이스별 push_log(pending) 생성
+        for (const device of devices) {
+            if (!device.push_token) continue;
+
+            // platform은 device.platform 우선, 없으면 provider driver 기반
+            const platform =
+                device.platform || this.getPlatformForProvider(providerName);
+
+            const logData: Record<string, unknown> = {
+                status: "pending",
+                account_seq: job.account_seq,
+                device_seq: device.seq,
+                platform,
+                device_token: device.push_token,
+                title: job.title,
+                body: job.body,
+                ref_entity: job.ref_entity || "",
+                retry_count: 0,
+                error_message: "",
+                provider: providerName,
+            };
+            if (pushDataStr) {
+                logData.push_data = pushDataStr;
+            }
+            if (job.ref_seq && job.ref_seq > 0) {
+                logData.ref_seq = job.ref_seq;
+            }
+
+            try {
+                await this.querier.submitPushLog(logData);
+            } catch (err) {
+                logger.warn(
+                    { err, device_seq: device.seq },
+                    "Push: failed to create push_log",
+                );
+            }
+        }
+    }
+
+    /** pending 로그를 가져와 발송한다 */
+    private async dispatch(): Promise<void> {
+        if (!this.running || !this.querier) return;
+
+        const logs = await this.querier.claimPendingPushLogs(
+            this.config.queue_size,
+        );
+        if (logs.length === 0) return;
+
+        // 동시 발송 (workers 수만큼 병렬)
+        const maxConcurrency = this.config.workers || 2;
+        const queue = [...logs];
+
+        const processNext = async (): Promise<void> => {
+            while (queue.length > 0 && this.running) {
+                const log = queue.shift()!;
+                await this.processOne(log);
+            }
+        };
+
+        const workers: Promise<void>[] = [];
+        for (let i = 0; i < Math.min(maxConcurrency, logs.length); i++) {
+            workers.push(processNext());
+        }
+        await Promise.allSettled(workers);
+    }
+
+    /** 단일 pending 로그를 처리한다 */
+    private async processOne(pl: PendingPushLog): Promise<void> {
+        if (!pl.device_token) {
+            await this.finalize(pl.log_seq, "failed", "empty device token");
+            return;
+        }
+
+        // provider 선택: log에 기록된 provider 우선, 없으면 platform 기반, 없으면 default
+        const providerName =
+            (pl.provider && this.providers.has(pl.provider)
+                ? pl.provider
+                : "") ||
+            this.resolveProviderByPlatform(pl.platform) ||
+            this.config.default;
+
+        const provider = this.providers.get(providerName);
+        if (!provider) {
+            await this.finalize(
+                pl.log_seq,
+                "failed",
+                `provider '${providerName}' not configured`,
+            );
+            return;
+        }
+
+        try {
+            await provider.send(
+                pl.device_token,
+                pl.title,
+                pl.body,
+                pl.push_data,
+            );
+            await this.finalize(pl.log_seq, "sent", "");
+        } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+
+            // 토큰 만료 시 디바이스 비활성화
+            const isExpired =
+                isFcmTokenExpiredError(errMsg) ||
+                isApnsTokenExpiredError(errMsg);
+
+            if (isExpired && this.querier && pl.device_seq > 0) {
+                try {
+                    await this.querier.disableDeviceToken(pl.device_seq);
+                    logger.info(
+                        {
+                            device_seq: pl.device_seq,
+                            account_seq: pl.account_seq,
+                        },
+                        "Push: disabled expired device token",
+                    );
+                } catch (disableErr) {
+                    logger.warn(
+                        { err: disableErr, device_seq: pl.device_seq },
+                        "Push: failed to disable expired token",
+                    );
+                }
+            }
+
+            await this.finalize(pl.log_seq, "failed", errMsg);
+        }
+    }
+
+    /** push_log 최종 상태를 기록한다 */
+    private async finalize(
+        logSeq: number,
+        status: string,
+        errMsg: string,
+    ): Promise<void> {
+        if (!this.querier) return;
+        try {
+            await this.querier.updatePushLogStatus(logSeq, status, errMsg);
+        } catch (err) {
+            logger.warn(
+                { err, log_seq: logSeq },
+                "Push: failed to update push_log status",
+            );
+        }
+    }
+
+    /** provider driver 이름으로 platform 문자열을 반환한다 */
+    private getPlatformForProvider(providerName: string): string {
+        const provCfg = this.config.providers[providerName];
+        if (!provCfg) return "fcm";
+        return provCfg.driver === "apns" ? "apns" : "fcm";
+    }
+
+    /**
+     * platform 문자열로 적절한 provider를 찾는다.
+     * apns 플랫폼이면 driver="apns"인 provider를 찾고,
+     * 그 외는 driver="fcm"인 provider를 찾는다.
+     */
+    private resolveProviderByPlatform(platform: string): string | null {
+        const targetDriver = platform === "apns" ? "apns" : "fcm";
+        for (const [name, cfg] of Object.entries(this.config.providers)) {
+            if (cfg.driver === targetDriver && this.providers.has(name)) {
+                return name;
+            }
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Push 알림 설정 타입 정의
+ *
+ * Go 엔티티서버 `internal/types/push_config.go` 에서 포팅
+ */
+
+export interface PushConfig {
+    enabled?: boolean;
+    default: string; // 기본 프로바이더 이름
+    workers: number; // 워커 수 (기본 2)
+    queue_size: number; // dispatch당 claim 수 (기본 50)
+    dispatch_interval_sec: number; // 디스패치 주기 초 (기본 5)
+    max_retries: number; // 최대 재시도 (기본 3)
+    providers: Record<string, PushProviderConfig>; // 프로바이더 목록 (키=provider name)
+}
+
+export type PushProviderConfig = FcmProviderConfig | ApnsProviderConfig;
+
+export interface FcmProviderConfig {
+    driver: "fcm";
+    project_id: string; // Firebase 프로젝트 ID
+    key_file: string; // 서비스 계정 JSON 파일 경로
+}
+
+export interface ApnsProviderConfig {
+    driver: "apns";
+    key_id: string; // APNs 인증 키 ID (.p8)
+    team_id: string; // Apple Team ID
+    bundle_id: string; // 앱 Bundle ID
+    key_file: string; // .p8 키 파일 경로
+    production?: boolean; // production 환경 여부 (false = sandbox)
+}

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

@@ -0,0 +1,14 @@
+export type {
+    PushConfig,
+    PushProviderConfig,
+    FcmProviderConfig,
+    ApnsProviderConfig,
+} from "./config.ts";
+
+export type {
+    PushJob,
+    PendingPushLog,
+    DeviceInfo,
+    PushQuerier,
+    PushProvider,
+} from "./job.ts";

package/src/app/plugins/push/types/job.ts

@@ -0,0 +1,79 @@
+/**
+ * Push 알림 작업·로그 타입 정의
+ *
+ * Go 엔티티서버 `internal/push/types.go` 에서 포팅
+ */
+
+/** 훅에서 생성하는 발송 작업 단위 */
+export interface PushJob {
+    /** 수신자 account seq */
+    account_seq: number;
+    /** 알림 제목 */
+    title: string;
+    /** 알림 본문 */
+    body: string;
+    /** 커스텀 페이로드 */
+    data?: Record<string, string>;
+    /** 트리거 엔티티명 */
+    ref_entity?: string;
+    /** 트리거 레코드 seq */
+    ref_seq?: number;
+    /** 특정 provider 지정 (없으면 default) */
+    provider?: string;
+}
+
+/** DB 큐에서 가져온 미발송 push_log 레코드 */
+export interface PendingPushLog {
+    log_seq: number;
+    account_seq: number;
+    device_seq: number;
+    /** 발송 채널: "fcm" | "apns" */
+    platform: string;
+    device_token: string;
+    title: string;
+    body: string;
+    push_data?: Record<string, string>;
+    ref_entity?: string;
+    ref_seq?: number;
+    retry_count: number;
+    /** 특정 provider 이름 (지정된 경우) */
+    provider?: string;
+}
+
+/** 디바이스 정보 */
+export interface DeviceInfo {
+    seq: number;
+    account_seq: number;
+    platform: string;
+    push_token: string;
+}
+
+/** push_log DB 큐 인터페이스 */
+export interface PushQuerier {
+    /** 특정 계정의 push 활성 디바이스 목록 조회 */
+    listDevicesForAccount(accountSeq: number): Promise<DeviceInfo[]>;
+    /** push_log(pending) 레코드 생성 */
+    submitPushLog(data: Record<string, unknown>): Promise<void>;
+    /** pending 로그를 processing으로 claim하여 반환 */
+    claimPendingPushLogs(limit: number): Promise<PendingPushLog[]>;
+    /** push_log 상태 갱신 */
+    updatePushLogStatus(
+        logSeq: number,
+        status: string,
+        errMsg: string,
+    ): Promise<void>;
+    /** 서버 재시작 시 processing → pending 복구 */
+    resetStalePushLogs(): Promise<void>;
+    /** 만료된 토큰 디바이스 비활성화 */
+    disableDeviceToken(deviceSeq: number): Promise<void>;
+}
+
+/** Push Provider 인터페이스 */
+export interface PushProvider {
+    send(
+        deviceToken: string,
+        title: string,
+        body: string,
+        data?: Record<string, string>,
+    ): Promise<void>;
+}

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

@@ -0,0 +1,11 @@
+# Shared (공유 리소스)
+
+플러그인 간 공유가 필요한 유틸리티나 타입을 두는 예약 폴더입니다.
+
+---
+
+현재 이 폴더는 비어 있습니다.
+
+공유 유틸리티가 필요할 경우 이 폴더에 추가하고 관련 플러그인에서 import합니다.
+
+> 외부 API 인증 헬퍼는 [`providers/`](../providers/docs/README.md)를 참고하세요.

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

@@ -0,0 +1,30 @@
+{
+    "enabled": false,
+    "default": "aligo",
+    "sender": "${SMS_SENDER_NUMBER}",
+    "workers": 2,
+    "queue_size": 200,
+    "dispatch_interval_sec": 5,
+    "max_retries": 3,
+    "auto_lms": true,
+    "lms_threshold_bytes": 80,
+    "providers": {
+        "aligo": {
+            "driver": "aligo",
+            "api_key": "${ALIGO_API_KEY}",
+            "user_id": "${ALIGO_USER_ID}",
+            "sender": "${SMS_SENDER_NUMBER}"
+        }
+    },
+    "rate_limit": {
+        "per_number_per_minute": 5,
+        "per_minute": 60,
+        "per_hour": 500
+    },
+    "verification": {
+        "code_length": 6,
+        "ttl_sec": 180,
+        "max_attempts": 5,
+        "cooldown_sec": 60
+    }
+}

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

@@ -0,0 +1,33 @@
+{
+    "_comment": "SMS 발송 플러그인 — 알리고 등 프로바이더 연동, 자동 LMS 전환·인증번호 발송·발송 제한 설정 포함",
+    "enabled": false,
+    "default": "aligo",
+    "sender": "${SMS_SENDER_NUMBER}",
+    "workers": 2,
+    "queue_size": 200,
+    "dispatch_interval_sec": 5,
+    "max_retries": 3,
+    "auto_lms": true,
+    "lms_threshold_bytes": 80,
+    "providers": {
+        "aligo": {
+            "driver": "aligo",
+            "api_key": "${ALIGO_API_KEY}",
+            "user_id": "${ALIGO_USER_ID}",
+            "sender": "${SMS_SENDER_NUMBER}"
+        }
+    },
+    "rate_limit": {
+        "per_number_per_minute": 5,
+        "per_minute": 60,
+        "per_hour": 500
+    },
+    "verification": {
+        "code_length": 6,
+        "ttl_sec": 180,
+        "max_attempts": 5,
+        "cooldown_sec": 60
+    },
+    "deploy": true,
+    "minify": true
+}

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

@@ -0,0 +1,158 @@
+/**
+ * SMS 설정 로더
+ *
+ * 플러그인 디렉토리의 config.json을 읽고 환경변수 치환을 수행합니다.
+ * Go 엔티티서버 `internal/config/sms_loader.go`에서 포팅
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { SmsConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+/** SMS 설정을 로드한다 */
+export function loadSmsConfig(): SmsConfig | null {
+    try {
+        let raw = readFileSync(CONFIG_PATH, "utf-8");
+
+        // 환경변수 치환: ${VAR} → process.env.VAR
+        raw = raw.replace(
+            /\$\{([^}]+)\}/g,
+            (_match, name) => process.env[name] ?? "",
+        );
+
+        const cfg: SmsConfig = JSON.parse(raw);
+
+        if (cfg.enabled === false) {
+            logger.info("SMS plugin disabled in config");
+            return null;
+        }
+
+        // 기본값 보정
+        if (!cfg.workers || cfg.workers <= 0) cfg.workers = 2;
+        if (!cfg.queue_size || cfg.queue_size <= 0) cfg.queue_size = 200;
+        if (!cfg.dispatch_interval_sec || cfg.dispatch_interval_sec <= 0)
+            cfg.dispatch_interval_sec = 5;
+        if (!cfg.max_retries || cfg.max_retries <= 0) cfg.max_retries = 3;
+        if (cfg.auto_lms === undefined) cfg.auto_lms = true;
+        if (!cfg.lms_threshold_bytes || cfg.lms_threshold_bytes <= 0)
+            cfg.lms_threshold_bytes = 80;
+
+        // 프로바이더가 1개이고 default 미설정 시 자동 추론
+        if (
+            !cfg.default &&
+            cfg.providers &&
+            Object.keys(cfg.providers).length === 1
+        ) {
+            cfg.default = Object.keys(cfg.providers)[0];
+        }
+
+        // 검증
+        if (!cfg.providers || Object.keys(cfg.providers).length === 0) {
+            logger.error("SMS config: at least one provider is required");
+            return null;
+        }
+        if (!cfg.default) {
+            logger.error("SMS config: default provider must be specified");
+            return null;
+        }
+        const driverNames = Object.keys(cfg.providers);
+        if (!driverNames.includes(cfg.default)) {
+            logger.error(
+                `SMS config: default provider '${cfg.default}' not found in providers`,
+            );
+            return null;
+        }
+
+        // 드라이버별 필수 필드 검증
+        for (const [name, p] of Object.entries(cfg.providers)) {
+            if (!p.driver) {
+                logger.error(
+                    `SMS config: provider '${name}': driver is required`,
+                );
+                return null;
+            }
+            switch (p.driver) {
+                case "aligo":
+                    if (!p.api_key || !p.user_id) {
+                        logger.error(
+                            `SMS config: provider '${p.driver}' (aligo): api_key and user_id are required`,
+                        );
+                        return null;
+                    }
+                    break;
+                case "solapi":
+                    if (!p.api_key || !p.api_secret) {
+                        logger.error(
+                            `SMS config: provider '${p.driver}' (solapi): api_key and api_secret are required`,
+                        );
+                        return null;
+                    }
+                    break;
+                case "ppurio":
+                    if (!p.account || !p.api_key) {
+                        logger.error(
+                            `SMS config: provider '${p.driver}' (ppurio): account and api_key are required`,
+                        );
+                        return null;
+                    }
+                    break;
+                case "nhn_cloud":
+                    if (!p.app_key || !p.secret_key) {
+                        logger.error(
+                            `SMS config: provider '${p.driver}' (nhn_cloud): app_key and secret_key are required`,
+                        );
+                        return null;
+                    }
+                    break;
+                case "aws_sns":
+                    if (!p.region || !p.access_key || !p.secret_key) {
+                        logger.error(
+                            `SMS config: provider '${p.driver}' (aws_sns): region, access_key, and secret_key are required`,
+                        );
+                        return null;
+                    }
+                    break;
+                default:
+                    logger.error(
+                        `SMS config: provider '${p.driver}': unknown driver`,
+                    );
+                    return null;
+            }
+        }
+
+        // 인증번호 기본값 보정
+        if (cfg.verification) {
+            if (
+                !cfg.verification.code_length ||
+                cfg.verification.code_length <= 0
+            )
+                cfg.verification.code_length = 6;
+            if (!cfg.verification.ttl_sec || cfg.verification.ttl_sec <= 0)
+                cfg.verification.ttl_sec = 180;
+            if (
+                !cfg.verification.max_attempts ||
+                cfg.verification.max_attempts <= 0
+            )
+                cfg.verification.max_attempts = 5;
+            if (
+                !cfg.verification.cooldown_sec ||
+                cfg.verification.cooldown_sec <= 0
+            )
+                cfg.verification.cooldown_sec = 60;
+        }
+
+        return cfg;
+    } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            logger.info("SMS config not found, plugin skipped");
+        } else {
+            logger.error({ err }, "Failed to load SMS config");
+        }
+        return null;
+    }
+}