create-entity-app-server 0.0.3

package/src/app/plugins/push/providers/apns.ts

@@ -0,0 +1,152 @@
+/**
+ * APNs (Apple Push Notification service) HTTP/2 JWT 프로바이더
+ *
+ * Go 엔티티서버 `internal/push/apns.go` 에서 포팅
+ *
+ * 인증: .p8 ECDSA(ES256) 비공개 키 → JWT → APNs Authorization 헤더
+ * API: https://api.push.apple.com/3/device/{token} (production)
+ *      https://api.sandbox.push.apple.com/3/device/{token} (sandbox)
+ *
+ * Node.js 18+ 의 net/http 는 HTTP/2를 자동 협상하지 않으므로
+ * undici fetch (Node.js 내장)를 사용하고, apns-collapse-id 미사용 단순 알림에는
+ * HTTP/1.1 fallback도 실제로는 작동하지만 Apple 권장은 HTTP/2.
+ *
+ * JWT는 ~55분 캐시 후 자동 갱신 (Apple 권장: 최대 1시간).
+ */
+
+import { readFileSync } from "node:fs";
+import jwt from "jsonwebtoken";
+import type { PushProvider } from "../types/index.ts";
+import { isApnsTokenExpiredError } from "./utils.ts";
+
+const APNS_ENDPOINT_PRODUCTION = "https://api.push.apple.com/3/device/%s";
+const APNS_ENDPOINT_SANDBOX = "https://api.sandbox.push.apple.com/3/device/%s";
+/** JWT 갱신 여유 시간 (ms): 55분 */
+const TOKEN_TTL_MS = 55 * 60 * 1000;
+
+interface TokenCache {
+    token: string;
+    issuedAt: number; // Date.now()
+}
+
+export class ApnsProvider implements PushProvider {
+    private readonly keyId: string;
+    private readonly teamId: string;
+    private readonly bundleId: string;
+    private readonly production: boolean;
+    private readonly privateKey: string;
+    private tokenCache: TokenCache | null = null;
+
+    constructor(
+        keyFile: string,
+        keyId: string,
+        teamId: string,
+        bundleId: string,
+        production = false,
+    ) {
+        const raw = readFileSync(keyFile, "utf-8");
+        // .p8 PEM 검증
+        if (!raw.includes("PRIVATE KEY")) {
+            throw new Error(
+                `APNs: '${keyFile}' does not appear to be a valid .p8 PEM private key`,
+            );
+        }
+
+        this.privateKey = raw;
+        this.keyId = keyId;
+        this.teamId = teamId;
+        this.bundleId = bundleId;
+        this.production = production;
+    }
+
+    /** 단일 APNs 디바이스 토큰에 푸시 알림을 전송한다 */
+    async send(
+        deviceToken: string,
+        title: string,
+        body: string,
+        data?: Record<string, string>,
+    ): Promise<void> {
+        const authToken = this.getToken();
+        const endpoint = this.production
+            ? APNS_ENDPOINT_PRODUCTION
+            : APNS_ENDPOINT_SANDBOX;
+        const url = endpoint.replace("%s", deviceToken);
+
+        const payload: Record<string, unknown> = {
+            aps: {
+                alert: { title, body },
+                sound: "default",
+            },
+        };
+        if (data && Object.keys(data).length > 0) {
+            payload.data = data;
+        }
+
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                authorization: `bearer ${authToken}`,
+                "apns-topic": this.bundleId,
+                "apns-push-type": "alert",
+                "apns-priority": "10",
+            },
+            body: JSON.stringify(payload),
+        });
+
+        if (resp.status === 200) return;
+
+        let errBody: string;
+        try {
+            errBody = await resp.text();
+        } catch {
+            errBody = `HTTP ${resp.status}`;
+        }
+
+        try {
+            const parsed = JSON.parse(errBody) as { reason?: string };
+            if (parsed.reason) {
+                throw new Error(`apns error [${resp.status}] ${parsed.reason}`);
+            }
+        } catch (parseErr) {
+            if (parseErr instanceof SyntaxError) {
+                // JSON 파싱 실패 → 원문 throw
+            } else {
+                throw parseErr;
+            }
+        }
+
+        throw new Error(
+            `apns request failed with status ${resp.status}: ${errBody}`,
+        );
+    }
+
+    /** 캐시된 JWT를 반환하거나 만료 시 새 토큰을 발급한다 */
+    private getToken(): string {
+        const now = Date.now();
+        if (this.tokenCache && now - this.tokenCache.issuedAt < TOKEN_TTL_MS) {
+            return this.tokenCache.token;
+        }
+
+        const nowSec = Math.floor(now / 1000);
+        const token = jwt.sign(
+            {
+                iss: this.teamId,
+                iat: nowSec,
+            },
+            this.privateKey,
+            {
+                algorithm: "ES256",
+                header: {
+                    alg: "ES256",
+                    kid: this.keyId,
+                },
+            } as jwt.SignOptions,
+        );
+
+        this.tokenCache = { token, issuedAt: now };
+        return token;
+    }
+}
+
+export { isApnsTokenExpiredError };

package/src/app/plugins/push/providers/fcm.ts

@@ -0,0 +1,181 @@
+/**
+ * FCM (Firebase Cloud Messaging) HTTP v1 API 프로바이더
+ *
+ * Go 엔티티서버 `internal/push/fcm.go` 에서 포팅
+ *
+ * 인증: 서비스 계정 JSON → RS256 JWT → Google OAuth2 → access token
+ * API: https://fcm.googleapis.com/v1/projects/{projectId}/messages:send
+ */
+
+import { readFileSync } from "node:fs";
+import jwt from "jsonwebtoken";
+import type { PushProvider } from "../types/index.ts";
+import { isFcmTokenExpiredError } from "./utils.ts";
+
+const FCM_ENDPOINT = "https://fcm.googleapis.com/v1/projects/%s/messages:send";
+const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const FCM_SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+/** 토큰 캐시 갱신 여유 시간 (초): 만료 100초 전에 갱신 */
+const TOKEN_REFRESH_BEFORE_SEC = 100;
+
+interface ServiceAccount {
+    type: string;
+    project_id: string;
+    private_key_id: string;
+    private_key: string;
+    client_email: string;
+    client_id: string;
+    auth_uri: string;
+    token_uri: string;
+}
+
+interface TokenCache {
+    token: string;
+    expiresAt: number; // Unix timestamp (ms)
+}
+
+export class FcmProvider implements PushProvider {
+    private readonly projectId: string;
+    private readonly serviceAccount: ServiceAccount;
+    private tokenCache: TokenCache | null = null;
+
+    constructor(projectId: string, keyFile: string) {
+        const raw = readFileSync(keyFile, "utf-8");
+        const sa = JSON.parse(raw) as ServiceAccount;
+
+        if (!sa.client_email || !sa.private_key) {
+            throw new Error(
+                `FCM: invalid service account JSON in '${keyFile}': missing client_email or private_key`,
+            );
+        }
+
+        this.projectId = projectId;
+        this.serviceAccount = sa;
+    }
+
+    /** 단일 디바이스에 푸시 알림을 전송한다 */
+    async send(
+        deviceToken: string,
+        title: string,
+        body: string,
+        data?: Record<string, string>,
+    ): Promise<void> {
+        const accessToken = await this.getAccessToken();
+        const url = FCM_ENDPOINT.replace("%s", this.projectId);
+
+        const message: Record<string, unknown> = {
+            token: deviceToken,
+            notification: { title, body },
+            android: { priority: "high" },
+            apns: {
+                payload: {
+                    aps: { sound: "default" },
+                },
+            },
+        };
+        if (data && Object.keys(data).length > 0) {
+            message.data = data;
+        }
+
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({ message }),
+        });
+
+        if (resp.ok) return;
+
+        let errBody: string;
+        try {
+            errBody = await resp.text();
+        } catch {
+            errBody = `HTTP ${resp.status}`;
+        }
+
+        // 구조화된 FCM 오류 파싱
+        try {
+            const parsed = JSON.parse(errBody) as {
+                error?: { code?: number; status?: string; message?: string };
+            };
+            const e = parsed.error;
+            if (e?.message) {
+                throw new Error(
+                    `FCM error [${e.code ?? resp.status}] ${e.status ?? ""}: ${e.message}`,
+                );
+            }
+        } catch (parseErr) {
+            if (parseErr instanceof SyntaxError) {
+                // JSON 파싱 실패 → 원문 throw
+            } else {
+                throw parseErr;
+            }
+        }
+
+        throw new Error(
+            `FCM request failed with status ${resp.status}: ${errBody}`,
+        );
+    }
+
+    /** OAuth2 Access Token을 반환한다 (캐시/갱신) */
+    private async getAccessToken(): Promise<string> {
+        const now = Date.now();
+        if (
+            this.tokenCache &&
+            this.tokenCache.expiresAt > now + TOKEN_REFRESH_BEFORE_SEC * 1000
+        ) {
+            return this.tokenCache.token;
+        }
+
+        const nowSec = Math.floor(now / 1000);
+        const assertion = jwt.sign(
+            {
+                iss: this.serviceAccount.client_email,
+                sub: this.serviceAccount.client_email,
+                aud: GOOGLE_TOKEN_URL,
+                scope: FCM_SCOPE,
+                iat: nowSec,
+                exp: nowSec + 3600,
+            },
+            this.serviceAccount.private_key,
+            {
+                algorithm: "RS256",
+                keyid: this.serviceAccount.private_key_id,
+            },
+        );
+
+        const body = new URLSearchParams({
+            grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            assertion,
+        });
+
+        const resp = await fetch(GOOGLE_TOKEN_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        });
+
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            throw new Error(
+                `FCM: failed to obtain access token (${resp.status}): ${text}`,
+            );
+        }
+
+        const tokenResp = (await resp.json()) as {
+            access_token: string;
+            expires_in: number;
+        };
+
+        this.tokenCache = {
+            token: tokenResp.access_token,
+            expiresAt: now + tokenResp.expires_in * 1000,
+        };
+
+        return this.tokenCache.token;
+    }
+}
+
+export { isFcmTokenExpiredError };

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

@@ -0,0 +1,42 @@
+/**
+ * Push 프로바이더 팩토리
+ *
+ * driver 값에 따라 FCMProvider 또는 ApnsProvider를 생성합니다.
+ */
+
+import { FcmProvider } from "./fcm.ts";
+import { ApnsProvider } from "./apns.ts";
+import { isFcmTokenExpiredError } from "./utils.ts";
+import { isApnsTokenExpiredError } from "./utils.ts";
+import type { PushProvider, PushProviderConfig } from "../types/index.ts";
+
+export { isFcmTokenExpiredError, isApnsTokenExpiredError };
+export type { PushProvider };
+
+/** 지원 드라이버 목록 */
+export const PUSH_DRIVERS = ["fcm", "apns"] as const;
+export type PushDriver = (typeof PUSH_DRIVERS)[number];
+
+/**
+ * 프로바이더 설정에서 PushProvider 인스턴스를 생성한다
+ */
+export function createPushProvider(cfg: PushProviderConfig): PushProvider {
+    switch (cfg.driver) {
+        case "fcm":
+            return new FcmProvider(cfg.project_id, cfg.key_file);
+
+        case "apns":
+            return new ApnsProvider(
+                cfg.key_file,
+                cfg.key_id,
+                cfg.team_id,
+                cfg.bundle_id,
+                cfg.production ?? false,
+            );
+
+        default: {
+            const d = (cfg as { driver: string }).driver;
+            throw new Error(`Push: unsupported driver '${d}'`);
+        }
+    }
+}

package/src/app/plugins/push/providers/utils.ts

@@ -0,0 +1,30 @@
+/**
+ * Push 프로바이더 공통 유틸리티
+ */
+
+/**
+ * FCM 오류 메시지가 토큰 만료(등록 해제)인지 확인합니다.
+ * Go `internal/push/fcm.go IsTokenExpiredError` 에서 포팅
+ */
+export function isFcmTokenExpiredError(msg: string): boolean {
+    if (!msg) return false;
+    const upper = msg.toUpperCase();
+    return (
+        upper.includes("NOT_FOUND") ||
+        upper.includes("UNREGISTERED") ||
+        upper.includes("INVALID_ARGUMENT")
+    );
+}
+
+/**
+ * APNs 오류 메시지가 토큰 만료(등록 해제)인지 확인합니다.
+ * Go `internal/push/apns.go IsAPNsTokenExpiredError` 에서 포팅
+ */
+export function isApnsTokenExpiredError(msg: string): boolean {
+    if (!msg) return false;
+    return (
+        msg.includes("BadDeviceToken") ||
+        msg.includes("Unregistered") ||
+        msg.includes("ExpiredToken")
+    );
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Push 알림 라우트 테이블
+ * 등록 경로: /api/v1/push/*
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+/** Push 라우트를 등록한다 */
+export default async function pushRoutes(app: FastifyInstance) {
+    // POST /api/v1/push/send — 단일 계정 푸시 발송 큐 등록
+    app.post("/send", h.handleSend);
+
+    // POST /api/v1/push/broadcast — 다중 계정 브로드캐스트
+    app.post("/broadcast", h.handleBroadcast);
+
+    // GET /api/v1/push/status/:seq — 발송 상태 조회 (엔티티 API 안내)
+    app.get("/status/:seq", h.handleStatus);
+    // POST /api/v1/push/device — 디바이스 토큰 등록/갱신
+    app.post("/device", h.handleDeviceRegister);
+
+    // DELETE /api/v1/push/device/:seq — 디바이스 푸시 수신 비활성화
+    app.delete("/device/:seq", h.handleDeviceUnregister);
+}