create-entity-app-server 0.0.3

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

@@ -0,0 +1,326 @@
+/**
+ * Push EntityAdapter — Entity Server 어댑터
+ *
+ * entity-server-client를 통해 push_log, account_device 엔티티에 접근.
+ * DB 큐 패턴: pending → processing → sent/failed
+ *
+ * Go 엔티티서버 `internal/push/entity_adapter.go` 에서 포팅
+ */
+
+import { entityServer, logger } from "@gateway/api";
+import type { PushQuerier, PendingPushLog, DeviceInfo } from "./types/index.ts";
+
+/** 재시도 불가 오류 키워드 */
+const NON_RETRY_KEYWORDS = [
+    "not configured",
+    "invalid argument",
+    "not_found",
+    "unregistered",
+    "baddevicetoken",
+    "expiredtoken",
+    "invalid token",
+];
+
+/** 재시도 백오프: 10s × 2^(retryCount-1), max 10분 */
+function retryBackoffMs(retryCount: number): number {
+    if (retryCount <= 0) return 0;
+    const shift = Math.min(retryCount - 1, 8);
+    const ms = 10_000 * Math.pow(2, shift);
+    return Math.min(ms, 10 * 60 * 1000);
+}
+
+/** stale processing 기준 시간 (ms) */
+const STALE_AFTER_MS = 2 * 60 * 1000;
+
+function shouldRetry(
+    errMsg: string,
+    retryCount: number,
+    maxRetries: number,
+): boolean {
+    if (retryCount >= maxRetries) return false;
+    const lower = errMsg.toLowerCase().trim();
+    if (!lower) return true;
+    for (const kw of NON_RETRY_KEYWORDS) {
+        if (lower.includes(kw)) return false;
+    }
+    return true;
+}
+
+function truncateError(msg: string): string {
+    return msg.length <= 500 ? msg : msg.slice(0, 500);
+}
+
+export class PushEntityAdapter implements PushQuerier {
+    constructor(private readonly maxRetries: number = 3) {}
+
+    /** 특정 계정의 push 활성 디바이스 목록을 조회한다 */
+    async listDevicesForAccount(accountSeq: number): Promise<DeviceInfo[]> {
+        const resp = await entityServer.list("account_device", {
+            account_seq: accountSeq,
+            push_enabled: true,
+            page: 1,
+            limit: 50,
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<
+            string,
+            unknown
+        >[];
+        const devices: DeviceInfo[] = [];
+
+        for (const item of items) {
+            const token = String(item.push_token ?? "");
+            if (!token) continue;
+            devices.push({
+                seq: Number(item.seq ?? 0),
+                account_seq: Number(item.account_seq ?? accountSeq),
+                platform: String(item.platform ?? "fcm").toLowerCase(),
+                push_token: token,
+            });
+        }
+        return devices;
+    }
+
+    /** push_log(pending) 레코드를 생성한다 */
+    async submitPushLog(data: Record<string, unknown>): Promise<void> {
+        await entityServer.submit("push_log", data);
+    }
+
+    /** pending 로그를 processing으로 claim하여 반환한다 */
+    async claimPendingPushLogs(limit: number): Promise<PendingPushLog[]> {
+        const now = Date.now();
+
+        // pending 조회
+        const pendingResp = await entityServer.list("push_log", {
+            status: "pending",
+            page: 1,
+            limit,
+            order: "seq",
+        } as any);
+
+        // stale processing 조회 (오래된 것 포함)
+        const processingResp = await entityServer.list("push_log", {
+            status: "processing",
+            page: 1,
+            limit,
+            order: "seq",
+        } as any);
+
+        const pending = ((pendingResp.data as any)?.items ?? []) as Record<
+            string,
+            unknown
+        >[];
+        const processing = ((processingResp.data as any)?.items ??
+            []) as Record<string, unknown>[];
+
+        const candidates: Record<string, unknown>[] = [...pending];
+
+        // stale processing 추가 (2분 이상 경과한 것만)
+        for (const item of processing) {
+            const attemptTime = String(item.attempt_time ?? "");
+            if (!attemptTime) {
+                candidates.push(item);
+                continue;
+            }
+            const dt = Date.parse(attemptTime);
+            if (!isNaN(dt) && now - dt >= STALE_AFTER_MS) {
+                candidates.push(item);
+            }
+        }
+
+        const logs: PendingPushLog[] = [];
+
+        for (const item of candidates) {
+            if (logs.length >= limit) break;
+
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+
+            const status = String(item.status ?? "");
+            const retryCount = Number(item.retry_count ?? 0);
+
+            // retry backoff: 이전 attempt_time + backoff 경과 여부 확인
+            if (status === "pending" && retryCount > 0) {
+                const attemptTime = String(item.attempt_time ?? "");
+                if (attemptTime) {
+                    const dt = Date.parse(attemptTime);
+                    if (!isNaN(dt) && now < dt + retryBackoffMs(retryCount)) {
+                        continue; // 아직 backoff 중
+                    }
+                }
+            }
+
+            // processing으로 claim
+            try {
+                await entityServer.submit("push_log", {
+                    seq,
+                    status: "processing",
+                    attempt_time: new Date().toISOString(),
+                });
+            } catch (err) {
+                logger.warn(
+                    { err, seq },
+                    "Push: failed to claim push_log, skipping",
+                );
+                continue;
+            }
+
+            let pushData: Record<string, string> | undefined;
+            const pdStr = String(item.push_data ?? "");
+            if (pdStr) {
+                try {
+                    pushData = JSON.parse(pdStr) as Record<string, string>;
+                } catch {
+                    // ignore
+                }
+            }
+
+            logs.push({
+                log_seq: seq,
+                account_seq: Number(item.account_seq ?? 0),
+                device_seq: Number(item.device_seq ?? 0),
+                platform: String(item.platform ?? "fcm"),
+                device_token: String(item.device_token ?? ""),
+                title: String(item.title ?? ""),
+                body: String(item.body ?? ""),
+                push_data: pushData,
+                ref_entity: String(item.ref_entity ?? ""),
+                ref_seq: Number(item.ref_seq ?? 0),
+                retry_count: retryCount,
+                provider: String(item.provider ?? ""),
+            });
+        }
+
+        return logs;
+    }
+
+    /** push_log 상태를 갱신한다 (재시도 로직 포함) */
+    async updatePushLogStatus(
+        logSeq: number,
+        status: string,
+        errMsg: string,
+    ): Promise<void> {
+        if (status === "sent") {
+            await entityServer.submit("push_log", {
+                seq: logSeq,
+                status: "sent",
+                sent_time: new Date().toISOString(),
+                error_message: "",
+            });
+            return;
+        }
+
+        if (status === "failed") {
+            // 재시도 여부 판단을 위해 현재 retry_count 조회
+            let retryCount = 0;
+            try {
+                const resp = await entityServer.list("push_log", {
+                    seq: logSeq,
+                    page: 1,
+                    limit: 1,
+                } as any);
+                const items = ((resp.data as any)?.items ?? []) as Record<
+                    string,
+                    unknown
+                >[];
+                if (items.length > 0) {
+                    retryCount = Number(items[0]!.retry_count ?? 0);
+                }
+            } catch {
+                // 조회 실패 시 재시도 없이 failed
+            }
+
+            if (shouldRetry(errMsg, retryCount, this.maxRetries)) {
+                await entityServer.submit("push_log", {
+                    seq: logSeq,
+                    status: "pending",
+                    retry_count: retryCount + 1,
+                    attempt_time: new Date().toISOString(),
+                    error_message: truncateError(errMsg),
+                });
+            } else {
+                await entityServer.submit("push_log", {
+                    seq: logSeq,
+                    status: "failed",
+                    error_message: truncateError(errMsg),
+                });
+            }
+            return;
+        }
+
+        // 기타 상태
+        await entityServer.submit("push_log", {
+            seq: logSeq,
+            status,
+            ...(errMsg ? { error_message: truncateError(errMsg) } : {}),
+        });
+    }
+
+    /** 서버 시작 시 processing 상태의 레코드를 pending으로 복구한다 */
+    async resetStalePushLogs(): Promise<void> {
+        const resp = await entityServer.list("push_log", {
+            status: "processing",
+            page: 1,
+            limit: 500,
+            order: "seq",
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<
+            string,
+            unknown
+        >[];
+        const now = Date.now();
+        let resetCount = 0;
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+
+            const attemptTime = String(item.attempt_time ?? "");
+            if (attemptTime) {
+                const dt = Date.parse(attemptTime);
+                if (!isNaN(dt) && now - dt < STALE_AFTER_MS) {
+                    continue; // 아직 stale 아님
+                }
+            }
+
+            const retryCount = Number(item.retry_count ?? 0);
+
+            try {
+                if (retryCount >= this.maxRetries) {
+                    await entityServer.submit("push_log", {
+                        seq,
+                        status: "failed",
+                        error_message: "max retries exceeded (stale recovery)",
+                    });
+                } else {
+                    await entityServer.submit("push_log", {
+                        seq,
+                        status: "pending",
+                        attempt_time: "",
+                    });
+                }
+                resetCount++;
+            } catch (err) {
+                logger.warn(
+                    { err, seq },
+                    "Push: failed to reset stale push_log",
+                );
+            }
+        }
+
+        if (resetCount > 0) {
+            logger.info(
+                `Push: reset ${resetCount} stale processing push_log records to pending`,
+            );
+        }
+    }
+
+    /** 만료된 토큰을 가진 디바이스의 push_enabled를 false로 변경한다 */
+    async disableDeviceToken(deviceSeq: number): Promise<void> {
+        await entityServer.submit("account_device", {
+            seq: deviceSeq,
+            push_enabled: false,
+        });
+    }
+}

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

@@ -0,0 +1,193 @@
+/**
+ * Push 알림 라우트 핸들러
+ *
+ * Go 엔티티서버 `internal/handler/push_handler.go` 에서 포팅
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, BadRequestError, entityServer } from "@gateway/api";
+import { parseUserAgent } from "../../../system/utils/user-agent.ts";
+import type { PushService } from "./service.ts";
+
+let pushService: PushService | null = null;
+
+export function initHandlers(svc: PushService): void {
+    pushService = svc;
+}
+
+/** POST /api/v1/push/send — 푸시 알림 발송 큐 등록 */
+export async function handleSend(
+    req: FastifyRequest<{
+        Body: {
+            account_seq: number;
+            title: string;
+            body: string;
+            data?: Record<string, string>;
+            ref_entity?: string;
+            ref_seq?: number;
+            provider?: string;
+        };
+    }>,
+    reply: FastifyReply,
+): Promise<void> {
+    if (!pushService) {
+        reply.code(503).send(fail("Push service not available"));
+        return;
+    }
+
+    const b = req.body;
+    if (!b.account_seq || b.account_seq <= 0) {
+        throw new BadRequestError("account_seq is required");
+    }
+    if (!b.title) {
+        throw new BadRequestError("title is required");
+    }
+    if (!b.body) {
+        throw new BadRequestError("body is required");
+    }
+
+    await pushService.enqueueJob({
+        account_seq: b.account_seq,
+        title: b.title,
+        body: b.body,
+        data: b.data,
+        ref_entity: b.ref_entity,
+        ref_seq: b.ref_seq,
+        provider: b.provider,
+    });
+
+    reply.send(ok({ message: "Push notification queued for delivery" }));
+}
+
+/**
+ * POST /api/v1/push/broadcast — 여러 계정에 동시 발송
+ * account_seqs 배열을 받아 각 계정에 푸시를 큐에 등록한다
+ */
+export async function handleBroadcast(
+    req: FastifyRequest<{
+        Body: {
+            account_seqs: number[];
+            title: string;
+            body: string;
+            data?: Record<string, string>;
+            ref_entity?: string;
+            provider?: string;
+        };
+    }>,
+    reply: FastifyReply,
+): Promise<void> {
+    if (!pushService) {
+        reply.code(503).send(fail("Push service not available"));
+        return;
+    }
+
+    const b = req.body;
+    if (!Array.isArray(b.account_seqs) || b.account_seqs.length === 0) {
+        throw new BadRequestError("account_seqs must be a non-empty array");
+    }
+    if (!b.title) {
+        throw new BadRequestError("title is required");
+    }
+    if (!b.body) {
+        throw new BadRequestError("body is required");
+    }
+
+    let queued = 0;
+    for (const accountSeq of b.account_seqs) {
+        if (!accountSeq || accountSeq <= 0) continue;
+        try {
+            await pushService.enqueueJob({
+                account_seq: accountSeq,
+                title: b.title,
+                body: b.body,
+                data: b.data,
+                ref_entity: b.ref_entity,
+                provider: b.provider,
+            });
+            queued++;
+        } catch {
+            // 개별 실패는 무시하고 계속
+        }
+    }
+
+    reply.send(
+        ok({
+            message: `Push notifications queued for ${queued} accounts`,
+            queued,
+        }),
+    );
+}
+
+/** GET /api/v1/push/status/:seq — 발송 상태 조회 */
+export async function handleStatus(
+    req: FastifyRequest<{ Params: { seq: string } }>,
+    reply: FastifyReply,
+): Promise<void> {
+    reply.send(
+        ok({
+            message:
+                "Use entity API: GET /api/v1/entity/push_log/{seq} to check push delivery status",
+        }),
+    );
+}
+
+/**
+ * POST /api/v1/push/device — 디바이스 토큰 등록/갱신
+ *
+ * device_id 기준으로 account_device 를 upsert한다.
+ */
+export async function handleDeviceRegister(
+    req: FastifyRequest<{
+        Body: {
+            device_id: string;
+            push_token: string;
+            platform?: string;
+            device_type?: string;
+            browser?: string;
+            browser_version?: string;
+        };
+    }>,
+    reply: FastifyReply,
+): Promise<void> {
+    const accountSeq = (req as any).user?.account_seq as number | undefined;
+    if (!accountSeq || accountSeq <= 0) {
+        reply.code(401).send(fail("Authentication required"));
+        return;
+    }
+
+    const b = req.body;
+    if (!b.device_id) throw new BadRequestError("device_id is required");
+    if (!b.push_token) throw new BadRequestError("push_token is required");
+
+    const userAgent = parseUserAgent(req.headers["user-agent"]);
+
+    const result = await entityServer.registerPushDevice(
+        accountSeq,
+        b.device_id,
+        b.push_token,
+        {
+            platform: b.platform ?? userAgent.platform,
+            deviceType: b.device_type ?? userAgent.deviceType,
+            browser: b.browser ?? userAgent.browser,
+            browserVersion: b.browser_version ?? userAgent.browserVersion,
+            pushEnabled: true,
+        },
+    );
+
+    reply.send(ok({ seq: result.seq }));
+}
+
+/**
+ * DELETE /api/v1/push/device/:seq — 디바이스 푸시 수신 비활성화
+ */
+export async function handleDeviceUnregister(
+    req: FastifyRequest<{ Params: { seq: string } }>,
+    reply: FastifyReply,
+): Promise<void> {
+    const seq = parseInt(req.params.seq, 10);
+    if (!seq || seq <= 0) throw new BadRequestError("Invalid device seq");
+
+    await entityServer.disablePushDevice(seq);
+
+    reply.send(ok({ message: "Device push disabled" }));
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Push 알림 Fastify 플러그인
+ *
+ * 설정 로드 → 프로바이더 클라이언트 생성 → Entity Adapter 주입 →
+ * PushService 시작 → app.pushService 데코레이터 등록
+ *
+ * Go 엔티티서버 `internal/push/` + `cmd/setup.go` 에서 포팅
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { loadPushConfig } from "./config.ts";
+import { createPushProvider } from "./providers/index.ts";
+import { PushService } from "./service.ts";
+import { PushEntityAdapter } from "./entity-adapter.ts";
+import { initHandlers } from "./handlers.ts";
+import type { PushProvider } from "./types/index.ts";
+import { registerPushService } from "@gateway/api";
+
+declare module "fastify" {
+    interface FastifyInstance {
+        pushService: PushService | null;
+    }
+}
+
+/** Push 알림 플러그인을 등록한다 */
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadPushConfig();
+
+        if (!config) {
+            app.decorate("pushService", null);
+            return;
+        }
+
+        // 프로바이더 클라이언트 생성
+        const providers = new Map<string, PushProvider>();
+        for (const [name, provCfg] of Object.entries(config.providers ?? {})) {
+            try {
+                const provider = createPushProvider(provCfg);
+                providers.set(name, provider);
+                app.log.info(
+                    `Push provider registered: ${name} (${provCfg.driver})`,
+                );
+            } catch (err) {
+                app.log.error(
+                    err,
+                    `Failed to create Push provider: ${name} (${provCfg.driver})`,
+                );
+            }
+        }
+
+        if (providers.size === 0) {
+            app.log.warn(
+                "Push: no valid providers configured, service disabled",
+            );
+            app.decorate("pushService", null);
+            registerPushService(null);
+            return;
+        }
+
+        const service = new PushService(config, providers);
+
+        // Entity Adapter 주입
+        service.setQuerier(new PushEntityAdapter(config.max_retries));
+
+        // 핸들러에 서비스 주입
+        initHandlers(service);
+
+        // 서비스 시작 (dispatch loop)
+        await service.start();
+
+        // system/push/sender.ts 에서 사용할 전역 참조 등록
+        registerPushService(service);
+
+        app.decorate("pushService", service);
+
+        // graceful shutdown
+        app.addHook("onClose", async () => {
+            registerPushService(null);
+            await service.stop();
+        });
+    },
+    { name: "push-plugin" },
+);