@aiquants/daily-report 0.1.1

package/src/server/handlers.ts

@@ -0,0 +1,543 @@
+/**
+ * React Router loader/action factories for the daily-report HTTP surface.
+ * 日報 HTTP サーフェス向けの React Router loader / action 工場。
+ *
+ * - index.loader: 画面ルートの認証 + 難読化ユーザー ID 解決
+ * - api.loader / api.action: `:endpoint` パラメータ式の認証付き API ルーター
+ * - sse.loader: Redis Streams ベースのリアルタイム更新 SSE エンドポイント
+ */
+import { normalizeBusinessDateKey } from "../shared/business-date"
+import { createLogger, type DailyReportLogger, LogLevel } from "../shared/logger"
+import { dailyReportSseMessageSchema } from "../shared/sse-schema"
+import type { DailyReportAuthenticate, DailyReportEncodeUserId, DailyReportRedisProvider } from "./ports"
+import { jsonResponseWithETag } from "./response"
+import type { DailyReportService } from "./service"
+import type { DailyReportSseReader, StreamEntry } from "./sse-reader"
+import { isStreamIdLte } from "./sse-reader"
+
+type LoaderArgs = { request: Request; params: Record<string, string | undefined> }
+
+/** `data()` 相当の JSON レスポンス生成 (react-router 非依存)。 */
+const jsonData = (payload: unknown, init?: { status?: number }): Response =>
+    new Response(JSON.stringify(payload), {
+        status: init?.status ?? 200,
+        headers: { "Content-Type": "application/json" },
+    })
+
+export type DailyReportHandlersConfig = {
+    /** リクエスト認証ポート。 */
+    authenticate: DailyReportAuthenticate
+    /** データアクセスサービス。 */
+    service: DailyReportService
+    /** 内部数値 ID の難読化ポート。 */
+    encodeUserId: DailyReportEncodeUserId
+    /** SSE 用 redis プロバイダー (catch-up の xRange / xRevRange に使用)。 */
+    redis?: DailyReportRedisProvider
+    /** SSE Fan-Out 共有リーダー。 */
+    sseReader: DailyReportSseReader
+    /** SSE Redis Stream キー。 */
+    streamKey: string
+    /** 未ログイン時のリダイレクト先 (index.loader 用、既定 "/auth/login")。 */
+    loginRedirectPath?: string
+    /** ロガー (既定は console ベース)。 */
+    logger?: DailyReportLogger
+}
+
+/**
+ * Creates the daily-report loaders/actions bound to the injected dependencies.
+ * 注入依存に束縛された日報 loader / action 群を生成する処理。
+ */
+export function createDailyReportHandlers(config: DailyReportHandlersConfig) {
+    const { authenticate, service, encodeUserId, redis, sseReader, streamKey } = config
+    const loginRedirectPath = config.loginRedirectPath ?? "/auth/login"
+    const apiLogger = config.logger ?? createLogger(LogLevel.ERROR, "[DailyReportAPI]")
+    const sseLogger = config.logger ?? createLogger(LogLevel.INFO, "[DailyReportSSE]")
+
+    // ---------------- index (画面ルート) ----------------
+
+    /**
+     * Document loader that authenticates and resolves the obfuscated internal user id.
+     * 認証と難読化済み内部ユーザー ID の解決を行うドキュメントローダー。
+     */
+    const indexLoader = async ({ request }: LoaderArgs) => {
+        const { user, cookie } = await authenticate(request, { failureRedirect: loginRedirectPath })
+        const headers = new Headers()
+        if (cookie) {
+            headers.append("Set-Cookie", cookie)
+        }
+
+        let userId: number | null = null
+        if (user) {
+            userId = await service.getUserIdByExternalId(user.id)
+        }
+
+        const hashedUserId = userId ? encodeUserId(userId) : null
+
+        return { data: { user, userId: hashedUserId }, headers }
+    }
+
+    // ---------------- api (:endpoint ルーター) ----------------
+
+    type User = { id: string }
+    type EndpointHandler = (url: URL, cookie: string | null, request: Request, user: User) => Promise<Response>
+
+    /**
+     * Handlers for each API endpoint.
+     * 各 API エンドポイントのハンドラー定義。
+     */
+    const endpointHandlers: Record<string, EndpointHandler> = {
+        /**
+         * Retrieves daily reports for a specific business date.
+         * 指定された営業日の日報一覧を取得する。
+         */
+        "business-date": async (url, cookie, request, user) => {
+            const normalizedBusinessDate = normalizeBusinessDateKey(url.searchParams.get("businessDate"))
+            const forceRefresh = url.searchParams.get("forceRefresh") === "true"
+
+            if (!normalizedBusinessDate) {
+                return jsonResponseWithETag(request, cookie, { error: { message: "Invalid business date" } }, 400)
+            }
+            const reports = await service.getDailyReportsByBusinessDateByExternalId(normalizedBusinessDate, user.id, { forceRefresh })
+            return jsonResponseWithETag(request, cookie, { businessDate: normalizedBusinessDate, reports }, 200)
+        },
+        /**
+         * Retrieves a list of all daily report IDs.
+         * 全ての日報 ID の一覧を取得する。
+         */
+        ids: async (url, cookie, request, user) => {
+            const forceRefresh = url.searchParams.get("forceRefresh") === "true"
+            const dailyReportIds = await service.getDailyReportIdsByExternalId(user.id, { forceRefresh })
+            return jsonResponseWithETag(request, cookie, { ids: dailyReportIds }, 200)
+        },
+        /**
+         * Retrieves details for a specific daily report.
+         * 指定された日報の詳細情報を取得する。
+         */
+        report: async (url, cookie, request, user) => {
+            const param = url.searchParams.get("reportHubId")
+            const forceRefresh = url.searchParams.get("forceRefresh") === "true"
+            const parsedId = param ? Number.parseInt(param, 10) : NaN
+
+            if (!Number.isFinite(parsedId) || parsedId <= 0) {
+                return jsonResponseWithETag(request, cookie, { error: { message: "Invalid reportHubId" } }, 400)
+            }
+            const detail = await service.getDailyReportDetailByIdByExternalId(parsedId, user.id, { snapshot: true, forceRefresh })
+            if (!detail) {
+                return jsonResponseWithETag(request, cookie, { error: { message: "Report not found" } }, 404)
+            }
+            return jsonResponseWithETag(request, cookie, { report: detail }, 200)
+        },
+    }
+
+    /**
+     * Routes authenticated daily report API requests by endpoint.
+     * エンドポイントごとに認証済みの日報 API リクエストを振り分ける。
+     */
+    const apiLoader = async ({ request, params }: LoaderArgs) => {
+        const { user, cookie } = await authenticate(request, { failureRedirect: null })
+        const sanitizedCookie = cookie ?? null
+
+        if (!user) {
+            return jsonResponseWithETag(request, sanitizedCookie, { error: { message: "Unauthorized" } }, 401)
+        }
+
+        if (request.method !== "GET") {
+            return jsonResponseWithETag(request, sanitizedCookie, { error: { message: "Method not allowed" } }, 405)
+        }
+        const endpoint = params.endpoint ?? ""
+        const handler = endpointHandlers[endpoint]
+        if (!handler) {
+            return jsonResponseWithETag(request, sanitizedCookie, { error: { message: "Unknown endpoint" } }, 404)
+        }
+        const startTime = Date.now()
+        try {
+            const url = new URL(request.url)
+            return await handler(url, sanitizedCookie, request, user)
+        } catch (error) {
+            const elapsed = Date.now() - startTime
+            const err = error instanceof Error ? error : new Error(String(error))
+            apiLogger.error(`500 endpoint=${endpoint} elapsed=${elapsed}ms name=${err.name} code=${"code" in err ? (err as { code: unknown }).code : "N/A"} message=${err.message}`)
+            apiLogger.error("Stack:", err.stack)
+            return jsonResponseWithETag(request, sanitizedCookie, { error: { message: "Internal Server Error" } }, 500)
+        }
+    }
+
+    /**
+     * Handles data mutations for daily reports.
+     * 日報データの変更操作を処理するアクション。
+     */
+    const apiAction = async ({ request, params }: LoaderArgs) => {
+        const { user } = await authenticate(request, { failureRedirect: null })
+        if (!user) {
+            return jsonData({ error: "Unauthorized" }, { status: 401 })
+        }
+
+        const endpoint = params.endpoint
+        if (endpoint !== "action") {
+            return jsonData({ error: "Unknown endpoint" }, { status: 404 })
+        }
+
+        const userId = await service.getUserIdByExternalId(user.id)
+        if (!userId) {
+            return jsonData({ error: "User not found" }, { status: 404 })
+        }
+
+        const formData = await request.formData()
+        const intent = formData.get("intent")
+        const reportHubIdRaw = formData.get("reportHubId")
+        const reportHubId = reportHubIdRaw ? Number(reportHubIdRaw) : NaN
+        const businessDate = formData.get("businessDate") as string | null
+        const operationTimestamp = Number(formData.get("operationTimestamp"))
+        const clientTempId = formData.get("clientTempId") as string | null
+
+        if (!clientTempId) {
+            return jsonData({ error: "clientTempId required" }, { status: 400 })
+        }
+
+        if (intent !== "create" && (!reportHubId || Number.isNaN(reportHubId))) {
+            return jsonData({ error: "Invalid reportHubId" }, { status: 400 })
+        }
+
+        switch (intent) {
+            case "create": {
+                if (!businessDate) {
+                    return jsonData({ error: "businessDate required" }, { status: 400 })
+                }
+                const newReport = await service.createDailyReport(userId, businessDate, clientTempId)
+                return jsonData({
+                    status: "OK",
+                    intent: "create",
+                    report: newReport,
+                    reportHubId: String(newReport.reportHubId),
+                    clientTempId, // Echo back for validation
+                })
+            }
+            case "update": {
+                const title = formData.get("title") as string | undefined
+                const content = formData.get("content") as string | undefined
+                try {
+                    await service.updateDailyReport(reportHubId, userId, { title, content }, clientTempId)
+                    return jsonData({ status: "OK", intent: "update", reportHubId: String(reportHubId), clientTempId })
+                } catch (e: unknown) {
+                    if (e instanceof Error) {
+                        if (e.message === "Unauthorized") {
+                            return jsonData({ error: "Unauthorized" }, { status: 403 })
+                        }
+                        if (e.message === "Not Found") {
+                            return jsonData({ error: "Report not found" }, { status: 404 })
+                        }
+                    }
+                    throw e
+                }
+            }
+            case "publish": {
+                try {
+                    const publishedReport = await service.publishDailyReport(reportHubId, userId, clientTempId)
+                    return jsonData({ status: "OK", intent: "publish", reportHubId: String(reportHubId), clientTempId, report: publishedReport })
+                } catch (e: unknown) {
+                    if (e instanceof Error) {
+                        if (e.message === "Unauthorized") {
+                            return jsonData({ error: "Unauthorized" }, { status: 403 })
+                        }
+                        if (e.message === "Not Found") {
+                            return jsonData({ error: "Report not found" }, { status: 404 })
+                        }
+                    }
+                    throw e
+                }
+            }
+            case "delete": {
+                try {
+                    await service.deleteDailyReport(reportHubId, userId, clientTempId)
+                    return jsonData({
+                        status: "OK",
+                        intent: "delete",
+                        reportHubId: String(reportHubId),
+                        clientTempId, // Echo back for validation even on delete
+                    })
+                } catch (e: unknown) {
+                    if (e instanceof Error) {
+                        if (e.message === "Unauthorized") {
+                            return jsonData({ error: "Unauthorized" }, { status: 403 })
+                        }
+                        if (e.message === "Not Found") {
+                            return jsonData({ error: "Report not found" }, { status: 404 })
+                        }
+                    }
+                    throw e
+                }
+            }
+            case "toggleStar": {
+                const isStarredRaw = formData.get("isStarred")
+                if (isStarredRaw === null) {
+                    return jsonData({ error: "isStarred required" }, { status: 400 })
+                }
+                const isStarred = isStarredRaw === "true"
+                const updatedStatus = await service.setStarStatus(userId, reportHubId, businessDate, isStarred, clientTempId)
+                // クライアントは isStarred/isRead のみ参照する。生内部 ID (userId/created_by/updated_by) を
+                // 含む行全体は返さず、必要なフラグだけに絞る (内部 ID の自己開示防止)。
+                return jsonData({ status: "OK", intent: "toggleStar", updatedStatus: { isStarred: updatedStatus.isStarred, isRead: updatedStatus.isRead }, operationTimestamp, reportHubId: String(reportHubId), clientTempId })
+            }
+            case "toggleRead": {
+                const isReadRaw = formData.get("isRead")
+                if (isReadRaw === null) {
+                    return jsonData({ error: "isRead required" }, { status: 400 })
+                }
+                const isRead = isReadRaw === "true"
+                const updatedStatus = await service.setReadStatus(userId, reportHubId, businessDate, isRead, clientTempId)
+                // クライアントは isStarred/isRead のみ参照する (内部 ID の自己開示防止)。
+                return jsonData({ status: "OK", intent: "toggleRead", updatedStatus: { isStarred: updatedStatus.isStarred, isRead: updatedStatus.isRead }, operationTimestamp, reportHubId: String(reportHubId), clientTempId })
+            }
+            case "addComment": {
+                const content = formData.get("content") as string
+                if (!content) {
+                    return jsonData({ error: "Content required" }, { status: 400 })
+                }
+                const newComment = await service.addComment(userId, reportHubId, content, businessDate, clientTempId)
+                const safeComment = { ...newComment, userId: newComment.userId }
+                return jsonData({ status: "OK", intent: "addComment", newComment: safeComment, reportHubId: String(reportHubId), clientTempId })
+            }
+            case "deleteComment": {
+                const commentId = Number(formData.get("commentId"))
+                if (!commentId || Number.isNaN(commentId)) {
+                    return jsonData({ error: "Invalid commentId" }, { status: 400 })
+                }
+                try {
+                    await service.deleteComment(userId, reportHubId, commentId, businessDate, clientTempId)
+                    return jsonData({ status: "OK", reportHubId: String(reportHubId), deletedCommentId: String(commentId), clientTempId })
+                } catch (e: unknown) {
+                    if (e instanceof Error) {
+                        if (e.message === "Unauthorized") {
+                            return jsonData({ error: "Unauthorized" }, { status: 403 })
+                        }
+                        if (e.message === "Not Found") {
+                            return jsonData({ error: "Comment not found" }, { status: 404 })
+                        }
+                    }
+                    throw e
+                }
+            }
+            default:
+                return jsonData({ error: "Invalid intent" }, { status: 400 })
+        }
+    }
+
+    // ---------------- sse (リアルタイム更新) ----------------
+
+    /**
+     * SSE endpoint for real-time daily report updates via Redis Streams.
+     * Redis Streams を使用した日報リアルタイム更新の SSE エンドポイント。
+     */
+    const sseLoader = async ({ request, params }: LoaderArgs) => {
+        // 認証チェック
+        const { user } = await authenticate(request, { failureRedirect: null })
+        if (!user) {
+            return new Response("Unauthorized", { status: 401 })
+        }
+
+        // 内部ユーザー ID の解決
+        const internalUserId = await service.getUserIdByExternalId(user.id)
+        if (!internalUserId) {
+            return new Response("Forbidden", { status: 403 })
+        }
+
+        // エンドポイントの検証
+        if (params.endpoint !== "updates") {
+            return new Response("Not Found", { status: 404 })
+        }
+
+        // URL から lastEventId を取得 (再接続時の catch-up 用)
+        // クエリパラメータ優先、EventSource 自動再接続時の Last-Event-ID ヘッダーにフォールバック
+        const url = new URL(request.url)
+        const lastEventId = url.searchParams.get("lastEventId") || request.headers.get("Last-Event-ID")
+
+        const encoder = new TextEncoder()
+        let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null
+        let keepAliveInterval: ReturnType<typeof setInterval> | null = null
+        let unsubscribe: (() => void) | null = null
+        let isCleaningUp = false
+
+        // クリーンアップ処理
+        const cleanup = () => {
+            if (isCleaningUp) return
+            isCleaningUp = true
+
+            // keep-alive タイマー停止
+            if (keepAliveInterval) {
+                clearInterval(keepAliveInterval)
+                keepAliveInterval = null
+            }
+
+            // Fan-Out 購読解除 (entry / error 両リスナーを解除)
+            if (unsubscribe) {
+                unsubscribe()
+                unsubscribe = null
+            }
+
+            // SSE ストリームの終了
+            if (controllerRef) {
+                try {
+                    if (controllerRef.desiredSize !== null) {
+                        controllerRef.close()
+                    }
+                } catch (_e) {
+                    // ストリームが既に閉じている場合は無視
+                } finally {
+                    controllerRef = null
+                }
+            }
+
+            isCleaningUp = false
+        }
+
+        /**
+         * Processes a single Redis Stream entry and sends it to the SSE client.
+         * Redis Stream のエントリを処理し、SSE クライアントに送信する。
+         */
+        const processEntry = (entryId: string, fields: Record<string, string>) => {
+            // data フィールドの存在チェック
+            if (!fields.data) return
+
+            try {
+                const raw = JSON.parse(fields.data)
+                const result = dailyReportSseMessageSchema.safeParse(raw)
+                if (!result.success) {
+                    sseLogger.error("SSE message validation failed:", result.error.format())
+                    return // Fail-Closed: 不正なメッセージは送信しない
+                }
+                const parsed = result.data
+
+                // recipientRawUserId によるフィルタリング
+                const recipientRawUserId = typeof raw.recipientRawUserId === "number" ? raw.recipientRawUserId : undefined
+
+                if (parsed.type === "status-update") {
+                    if (recipientRawUserId === undefined || recipientRawUserId !== internalUserId) {
+                        return
+                    }
+                } else if (recipientRawUserId !== undefined && recipientRawUserId !== internalUserId) {
+                    return
+                }
+
+                // recipientRawUserId をクライアントに送信しない (内部 ID 漏洩防止)
+                let sanitizedMessage: string
+                if ("recipientRawUserId" in raw) {
+                    const { recipientRawUserId: _, ...rest } = raw
+                    sanitizedMessage = JSON.stringify(rest)
+                } else {
+                    sanitizedMessage = fields.data
+                }
+
+                // SSE フォーマットで送信 (id フィールド付き)
+                if (controllerRef && controllerRef.desiredSize !== null) {
+                    controllerRef.enqueue(encoder.encode(`id: ${entryId}\ndata: ${sanitizedMessage}\n\n`))
+                }
+            } catch (e) {
+                sseLogger.error(`[SSE:${internalUserId}] processEntry error:`, e)
+            }
+        }
+
+        const stream = new ReadableStream({
+            async start(controller) {
+                // 1. controllerRef 設定
+                controllerRef = controller
+
+                // 2. Keep-Alive: 5 秒ごとにコメントを送信して接続維持
+                keepAliveInterval = setInterval(() => {
+                    try {
+                        if (controllerRef && controllerRef.desiredSize !== null) {
+                            controllerRef.enqueue(encoder.encode(": keep-alive\n\n"))
+                        } else {
+                            cleanup()
+                        }
+                    } catch (_e) {
+                        cleanup()
+                    }
+                }, 5000)
+
+                // 3. クライアント切断時のクリーンアップ (全 await の前に登録)
+                request.signal.addEventListener("abort", () => {
+                    cleanup()
+                })
+
+                // catch-up の基準 ID (Fan-Out エントリとの重複排除に使用)
+                let lastProcessedId = lastEventId || "0-0"
+
+                // 4. Fan-Out 共有リーダーを購読 (catch-up より先に登録して取りこぼしを防止)
+                unsubscribe = sseReader.subscribe(
+                    (entry: StreamEntry) => {
+                        // catch-up 済みエントリはスキップ (重複排除)
+                        if (isStreamIdLte(entry.id, lastProcessedId)) return
+                        lastProcessedId = entry.id
+                        processEntry(entry.id, entry.message)
+                    },
+                    (err: Error) => {
+                        sseLogger.error(`[SSE:${internalUserId}] Fan-Out reader error:`, err)
+                        cleanup()
+                    },
+                )
+
+                // 5. 初回接続時: 最新 Stream ID を取得して connected の id: に使用
+                // (再接続時は lastEventId が既にあるためスキップ)
+                if (!lastEventId) {
+                    try {
+                        const client = await redis?.getClient()
+                        if (client) {
+                            const latest = await client.xRevRange(streamKey, "+", "-", { COUNT: 1 })
+                            // Fan-Out が既に lastProcessedId を進めている場合は巻き戻さない
+                            if (latest.length > 0 && !isStreamIdLte(latest[0].id, lastProcessedId)) {
+                                lastProcessedId = latest[0].id
+                            }
+                        }
+                    } catch {
+                        /* 取得失敗時は現在の lastProcessedId を維持 */
+                    }
+                }
+
+                // 6. 接続完了通知 (id: 付きで再接続時の catch-up アンカーを提供)
+                if (controllerRef && controllerRef.desiredSize !== null) {
+                    const connectedPayload = `data: ${JSON.stringify({ type: "connected" })}\n\n`
+                    const sseMessage = lastProcessedId !== "0-0" ? `id: ${lastProcessedId}\n${connectedPayload}` : connectedPayload
+                    controllerRef.enqueue(encoder.encode(sseMessage))
+                }
+
+                // 7. catch-up: lastEventId が指定されている場合、それ以降のエントリを一括取得
+                if (lastEventId) {
+                    try {
+                        const client = await redis?.getClient()
+                        if (client) {
+                            const catchUpEntries = await client.xRange(streamKey, lastEventId, "+", { COUNT: 1000 })
+                            for (const entry of catchUpEntries) {
+                                // xRange は inclusive なので lastEventId 自身はスキップ
+                                if (entry.id === lastEventId) continue
+                                // Fan-Out が xRange await 中に処理済みのエントリはスキップ (重複排除)
+                                if (isStreamIdLte(entry.id, lastProcessedId)) continue
+                                lastProcessedId = entry.id
+                                processEntry(entry.id, entry.message as Record<string, string>)
+                            }
+                        }
+                    } catch (e) {
+                        sseLogger.error(`[SSE:${internalUserId}] catch-up xRange error:`, e)
+                        // catch-up 失敗時は Fan-Out のみで継続
+                    }
+                }
+            },
+            cancel() {
+                cleanup()
+            },
+        })
+
+        return new Response(stream, {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache, no-transform",
+                Connection: "keep-alive",
+            },
+        })
+    }
+
+    return {
+        index: { loader: indexLoader },
+        api: { loader: apiLoader, action: apiAction },
+        sse: { loader: sseLoader },
+    }
+}

package/src/server/ports.ts

@@ -0,0 +1,68 @@
+/**
+ * DI ports (structural interfaces) consumed by the daily-report server layer.
+ * daily-report サーバー層が消費する DI ポート (構造的インターフェース) 群。
+ *
+ * redis / 認証 / ユーザー解決 / ID 難読化はすべてアプリ実装を注入する。
+ * redis の型は `redis` パッケージへ依存しないよう、使用する最小面のみ構造定義する。
+ */
+
+/** Redis Stream の 1 エントリ (xRead / xRange の結果要素)。 */
+export type RedisStreamMessage = {
+    id: string
+    message: Record<string, string>
+}
+
+/** 通常操作用 Redis クライアントの最小面 (共有クライアント)。 */
+export type DailyReportRedisClient = {
+    get(key: string): Promise<string | null>
+    incr(key: string): Promise<number>
+    xAdd(key: string, id: string, message: Record<string, string>, options?: unknown): Promise<string>
+    xRange(key: string, start: string, end: string, options?: { COUNT?: number }): Promise<RedisStreamMessage[]>
+    xRevRange(key: string, start: string, end: string, options?: { COUNT?: number }): Promise<RedisStreamMessage[]>
+}
+
+/** ブロッキング xRead 用 Redis クライアントの最小面 (SSE リーダー専用接続)。 */
+export type DailyReportRedisBlockingClient = {
+    isOpen: boolean
+    on(event: "error", listener: (err: Error) => void): unknown
+    xRead(streams: Array<{ key: string; id: string }>, options?: { BLOCK?: number; COUNT?: number }): Promise<Array<{ name: string; messages: RedisStreamMessage[] }> | null>
+    quit(): Promise<unknown>
+}
+
+/**
+ * Redis provider port: shared client for commands + dedicated client factory for blocking reads.
+ * Redis プロバイダーポート。コマンド用共有クライアントと、ブロッキング読み取り用専用クライアント生成を提供する。
+ */
+export type DailyReportRedisProvider = {
+    /** 共有クライアントを取得する (未接続・失敗時は undefined)。 */
+    getClient(): Promise<DailyReportRedisClient | undefined>
+    /** ブロッキング xRead 用の専用クライアントを生成する (失敗時は undefined)。 */
+    createClient(): Promise<DailyReportRedisBlockingClient | undefined>
+}
+
+/** 認証結果 (ユーザーは外部 ID を持つ最小形状)。 */
+export type DailyReportAuthResult = {
+    user?: { id: string }
+    cookie?: string
+}
+
+/**
+ * Request authentication port (e.g. session/OpenID check in the host app).
+ * リクエスト認証ポート (ホストアプリのセッション / OpenID 検証)。
+ *
+ * `failureRedirect` が文字列の場合、未認証時は実装側で redirect を throw すること。
+ * null の場合は throw せず `user` 無しで解決する。
+ */
+export type DailyReportAuthenticate = (request: Request, options: { failureRedirect: string } | { failureRedirect: null }) => Promise<DailyReportAuthResult>
+
+/**
+ * Resolves an external user id (e.g. Google sub) to the internal numeric user id.
+ * 外部ユーザー ID (例: Google sub) を内部数値ユーザー ID へ解決するポート。
+ */
+export type DailyReportResolveUserId = (externalUserId: string) => Promise<number | null>
+
+/**
+ * Obfuscates an internal numeric user id for client exposure.
+ * 内部数値ユーザー ID をクライアント公開用に難読化するポート。
+ */
+export type DailyReportEncodeUserId = (id: number) => string

package/src/server/response.ts

@@ -0,0 +1,37 @@
+/**
+ * JSON response helper with shared security headers and ETag support.
+ * 共有セキュリティヘッダーと ETag 対応を備えた JSON レスポンスヘルパー。
+ */
+import { createLogger, type DailyReportLogger, LogLevel } from "../shared/logger"
+import { generateETag } from "./etag"
+
+const defaultLogger = createLogger(LogLevel.INFO, "[Response]")
+
+/**
+ * Creates JSON response with shared security headers and ETag support.
+ * 共有のセキュリティヘッダーと ETag サポート付き JSON レスポンスを生成。
+ */
+export const jsonResponseWithETag = (request: Request, cookie: string | null, payload: Record<string, unknown>, status = 200, logger: DailyReportLogger = defaultLogger): Response => {
+    const etag = generateETag(payload)
+    const ifNoneMatch = request.headers.get("If-None-Match")
+
+    logger.info(`[jsonResponseWithETag] ETag: ${etag}, If-None-Match: ${ifNoneMatch}`)
+
+    const headers = new Headers({
+        "Content-Type": "application/json",
+        "Cache-Control": "private, max-age=0, must-revalidate",
+        "X-Content-Type-Options": "nosniff",
+        "X-Frame-Options": "DENY",
+        "Content-Security-Policy": "default-src 'none'",
+        ETag: etag,
+    })
+    if (cookie) {
+        headers.append("Set-Cookie", cookie)
+    }
+
+    if (request.method === "GET" && status === 200 && ifNoneMatch === etag) {
+        return new Response(null, { status: 304, headers })
+    }
+
+    return new Response(JSON.stringify(payload), { status, headers })
+}