@aiquants/daily-report 0.9.1 → 0.10.0

package/src/server/service.ts

@@ -165,6 +165,51 @@ export type DailyReportService = ReturnType<typeof createDailyReportService>
  * Creates the daily-report data-access service bound to the injected dependencies.
  * 注入された依存に束縛された日報データアクセスサービスを生成する処理。
  */
+type DatePattern = "YYYY-MM-DD HH:mm:ss" | "YYYY-MM-DD"
+
+/**
+ * Formats date-like values to a given pattern using local-time fields (no Intl allocation).
+ * 日付相当の値をローカル時刻フィールドで指定パターンへ整形する処理 (Intl 非生成)。
+ *
+ * ローカル時刻フィールドの手組み整形。旧実装 (ja-JP ロケール + 2-digit toLocale*) と出力互換。
+ * ❗ toLocale* 系へ戻さないこと: あれは呼び出しごとに Intl.DateTimeFormat を生成し
+ * (実測 約 66μs/呼)、全量 ids の 227k 行 map で 15〜20 秒の同期 CPU 洪水になる。
+ * business-date / SSE の全応答が人質化した実害バグの根本原因だった。
+ * モジュールスコープの export であり、バレル (src/server.ts の `export *`) 経由で
+ * `@aiquants/daily-report/server` の公開 API の一部になる (テストからの直接検証と
+ * ホスト側での汎用日時整形の再利用を意図した、意図的な公開)。
+ * 1000 年未満の年は旧実装 (年ゼロ詰めなし) から意図的に乖離し、ISO 準拠の 4 桁ゼロ詰めで出す
+ * (負の年は符号を除いた絶対値を 4 桁詰め。DB の date/datetime からは到達しない文字列入力のみの領域)。
+ */
+export const formatDateValue = (value: Date | string | null | undefined, pattern: DatePattern): string | null => {
+    // null / undefined / 空文字は null に正規化
+    if (!value) {
+        return null
+    }
+
+    // Date 以外 (文字列) は Date コンストラクタで解釈
+    const dateValue = value instanceof Date ? value : new Date(value)
+    if (Number.isNaN(dateValue.getTime())) {
+        // 解釈不能な文字列は原文のまま返す (旧実装と同一の不変挙動)
+        return typeof value === "string" ? value : null
+    }
+
+    // 年月日をゼロ詰めで組み立てる (負の年は符号を除いた絶対値を 4 桁詰め = ISO 8601 拡張表記に整合。
+    // String(-5).padStart は "00-5" と符号ごと詰めてしまうため符号を分離する)
+    const year = dateValue.getFullYear()
+    const yyyy = year < 0 ? `-${String(-year).padStart(4, "0")}` : String(year).padStart(4, "0")
+    const mm = String(dateValue.getMonth() + 1).padStart(2, "0")
+    const dd = String(dateValue.getDate()).padStart(2, "0")
+    if (pattern === "YYYY-MM-DD") {
+        return `${yyyy}-${mm}-${dd}`
+    }
+    // 時分秒付きパターン
+    const hh = String(dateValue.getHours()).padStart(2, "0")
+    const mi = String(dateValue.getMinutes()).padStart(2, "0")
+    const ss = String(dateValue.getSeconds()).padStart(2, "0")
+    return `${yyyy}-${mm}-${dd} ${hh}:${mi}:${ss}`
+}
+
 export function createDailyReportService(config: DailyReportServiceConfig) {
     const { db, tables, userTable: users, resolveUserId, encodeUserId, redis, cache: sqlResultCache, epochs } = config
     const { hub: DailyReportHub, internal: DailyReportInternal, comment: DailyReportCommentModel, label: DailyReportLabel, hubLabel: DailyReportHub_Label, userStatus: DailyReportUserStatus } = tables
@@ -212,28 +257,6 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         }
     }
 
-    type DatePattern = "YYYY-MM-DD HH:mm:ss" | "YYYY-MM-DD"
-
-    /**
-     * Formats date-like values to a given pattern (ja-JP locale semantics preserved).
-     * 日付相当の値を指定パターンに整形する処理。
-     */
-    const formatDateValue = (value: Date | string | null | undefined, pattern: DatePattern): string | null => {
-        if (!value) {
-            return null
-        }
-
-        const dateValue = value instanceof Date ? value : new Date(value)
-        if (Number.isNaN(dateValue.getTime())) {
-            return typeof value === "string" ? value : null
-        }
-
-        // ja-JP ロケールの YYYY/MM/DD (HH:mm:ss) を生成しハイフン区切りへ正規化する
-        const opts: Intl.DateTimeFormatOptions = pattern === "YYYY-MM-DD HH:mm:ss" ? { year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" } : { year: "numeric", month: "2-digit", day: "2-digit" }
-        const formatted = pattern === "YYYY-MM-DD HH:mm:ss" ? dateValue.toLocaleString("ja-JP", opts) : dateValue.toLocaleDateString("ja-JP", opts)
-        return formatted.replace(/\//g, "-")
-    }
-
     /**
      * Masks a raw audit-actor value (created_by / updated_by) before client exposure.
      * 監査列 (created_by / updated_by) をクライアント公開前にマスクする処理。
@@ -529,6 +552,9 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
             snapshot,
             ttlMsOverride: ttlMsOverride ?? DAILY_REPORT_IDS_TTL_MS,
             epochKey: DAILY_REPORT_IDS_EPOCH_KEY,
+            // TTL の半分を過ぎたヒットは、返却後に裏で 1 本だけ再フェッチして差し替える。
+            // 90 秒に 1 回以上アクセスがある限り、対話リクエストはコールド (全量再クエリ) を踏まない
+            refreshAheadRatio: 0.5,
         }) as Promise<DailyReportItem[]>
     }
 

package/src/server/sse-reader.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest"
 import { createEpochStore, SqlResultCache } from "./cache"
 import type { DailyReportRedisProvider } from "./ports"
-import { DailyReportSseReader, isStreamIdLte } from "./sse-reader"
+import { DailyReportSseReader, isStreamIdLte, type StreamEntry } from "./sse-reader"
 
 /**
  * Robustness tests for the SSE fan-out reader (createClient failure recovery + id compare).
@@ -53,3 +53,250 @@ describe("DailyReportSseReader createClient failure recovery", () => {
         await reader.destroy()
     })
 })
+
+/**
+ * Fake blocking client that scripts xRead results and records every requested start id.
+ * xRead の結果をスクリプト化し、要求された開始 ID をすべて記録する偽ブロッキングクライアント。
+ *
+ * スクリプト要素 null は BLOCK タイムアウト (新着なしの null 返し) を 1 回分模す。
+ * スクリプトが尽きたら BLOCK を模して未解決 Promise で待機し、quit() で null 解決して
+ * ループを正常終了させる (実クライアントの BLOCK + 切断挙動の最小モデル)。
+ */
+class FakeBlockingClient {
+    isOpen = true
+    /** xRead が要求された開始 ID の記録 (履歴再生の有無を判定する証拠)。 */
+    readonly requestedIds: string[] = []
+    private _pendingResolve: ((v: null) => void) | undefined
+    constructor(private readonly script: Array<Array<{ id: string; message: Record<string, string> }> | null>) {}
+
+    on(_event: "error", _listener: (err: Error) => void): void {}
+
+    async xRead(streams: Array<{ key: string; id: string }>): Promise<Array<{ name: string; messages: Array<{ id: string; message: Record<string, string> }> }> | null> {
+        this.requestedIds.push(streams[0].id)
+        if (this.script.length > 0) {
+            const batch = this.script.shift()
+            // null = BLOCK タイムアウト 1 回分
+            if (batch === null || batch === undefined) return null
+            return [{ name: streams[0].key, messages: batch }]
+        }
+        // スクリプト枯渇 = 新着なし。BLOCK を模して quit まで待機する
+        return new Promise((resolve) => {
+            this._pendingResolve = resolve
+        })
+    }
+
+    async quit(): Promise<void> {
+        this.isOpen = false
+        this._pendingResolve?.(null)
+        this._pendingResolve = undefined
+    }
+}
+
+describe("DailyReportSseReader history-replay poisoning prevention", () => {
+    /**
+     * 偽クライアント列を払い出す redis プロバイダーを組み立てるヘルパー。
+     * tailId: 共有クライアントの xRevRange が返す末尾 ID ("empty" は空ストリーム、
+     * undefined は共有クライアント自体が取得不能 = "$" 縮退経路)。
+     */
+    const makeRedis = (clients: FakeBlockingClient[], tailId?: string | "empty" | "reject"): { redis: DailyReportRedisProvider; created: FakeBlockingClient[] } => {
+        const created: FakeBlockingClient[] = []
+        const queue = [...clients]
+        const sharedClient =
+            tailId === undefined
+                ? undefined
+                : ({
+                      xRevRange: async () => {
+                          // "reject" はアンカー解決の失敗 (Redis エラー) を模す
+                          if (tailId === "reject") throw new Error("xRevRange failed")
+                          return tailId === "empty" ? [] : [{ id: tailId, message: {} }]
+                      },
+                  } as unknown as Awaited<ReturnType<DailyReportRedisProvider["getClient"]>>)
+        return {
+            created,
+            redis: {
+                getClient: async () => sharedClient,
+                createClient: async () => {
+                    const client = queue.shift()
+                    if (!client) throw new Error("script exhausted: unexpected createClient call")
+                    created.push(client)
+                    return client
+                },
+            },
+        }
+    }
+
+    const silentLogger = { debug() {}, info() {}, warn() {}, error() {} }
+
+    it("ループ開始時に xRevRange でストリーム末尾へアンカーし、初回 xRead から具体 ID で読む", async () => {
+        const client = new FakeBlockingClient([])
+        const { redis } = makeRedis([client], "50-3")
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger: silentLogger })
+
+        const unsub = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(client.requestedIds.length).toBeGreaterThanOrEqual(1))
+        // "$" のまま読むと BLOCK タイムアウトごとにサーバー側で末尾へ再解決され、
+        // 再武装の合間に届いたエントリを永続的に取りこぼす。必ず具体 ID に固定されていること
+        expect(client.requestedIds[0]).toBe("50-3")
+        unsub()
+        await reader.destroy()
+    })
+
+    it("BLOCK タイムアウト (null) 後も同じ具体 ID で再武装し、その後の新着を取りこぼさない", async () => {
+        const client = new FakeBlockingClient([null, [{ id: "100-1", message: { data: JSON.stringify({ type: "report-create" }) } }]])
+        const { redis } = makeRedis([client], "50-3")
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger: silentLogger })
+
+        const entries: StreamEntry[] = []
+        const unsub = reader.subscribe((entry) => entries.push(entry))
+        await vi.waitFor(() => expect(entries.length).toBe(1))
+        expect(entries[0].id).toBe("100-1")
+        // タイムアウト前後とも具体 ID ("$" の再武装が残っていれば 2 回目が "$" になり失敗する)
+        expect(client.requestedIds.slice(0, 2)).toEqual(["50-3", "50-3"])
+        // エントリ処理後は位置が前進する
+        await vi.waitFor(() => expect(client.requestedIds.length).toBeGreaterThanOrEqual(3))
+        expect(client.requestedIds[2]).toBe("100-1")
+        unsub()
+        await reader.destroy()
+    })
+
+    it('空ストリームは "0-0" にアンカーする (履歴が無いので毒殺は構造的に不能)', async () => {
+        const client = new FakeBlockingClient([])
+        const { redis } = makeRedis([client], "empty")
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger: silentLogger })
+
+        const unsub = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(client.requestedIds.length).toBeGreaterThanOrEqual(1))
+        expect(client.requestedIds[0]).toBe("0-0")
+        unsub()
+        await reader.destroy()
+    })
+
+    it('共有クライアント取得不能時は "$" のまま縮退する ("0-0" の全履歴再生には決して戻らない)', async () => {
+        const client = new FakeBlockingClient([])
+        const { redis } = makeRedis([client], undefined)
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger: silentLogger })
+
+        const unsub = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(client.requestedIds.length).toBeGreaterThanOrEqual(1))
+        expect(client.requestedIds[0]).toBe("$")
+        unsub()
+        await reader.destroy()
+    })
+
+    it("新着エントリは従来どおり配信され、report-create でキャッシュ無効化も発火する (陽性確認)", async () => {
+        const client = new FakeBlockingClient([[{ id: "100-1", message: { data: JSON.stringify({ type: "report-create" }) } }]])
+        const { redis } = makeRedis([client], "50-3")
+        const cache = makeCache()
+        const invalidateSpy = vi.spyOn(cache, "invalidatePrefix")
+        // 実プロセスのヒット状況を模して ids バケットを播種しておく
+        await cache.getOrFetch({ cacheKey: "daily-report:ids", fetcher: async () => ["seed"] })
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache, logger: silentLogger })
+
+        const entries: StreamEntry[] = []
+        const unsub = reader.subscribe((entry) => entries.push(entry))
+        await vi.waitFor(() => expect(entries.length).toBe(1))
+        expect(entries[0].id).toBe("100-1")
+        expect(invalidateSpy).toHaveBeenCalledWith("daily-report:ids")
+        unsub()
+        await reader.destroy()
+    })
+
+    it('stop → start で前回位置 (_lastId) を保持し、"0-0" へは決して戻らない', async () => {
+        const first = new FakeBlockingClient([[{ id: "100-1", message: { data: JSON.stringify({ type: "report-create" }) } }]])
+        const second = new FakeBlockingClient([])
+        const third = new FakeBlockingClient([])
+        const { redis } = makeRedis([first, second, third], "50-3")
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger: silentLogger })
+
+        // 1 回目の購読: 末尾アンカーから開始し、"100-1" を配信して位置を進める
+        const entries: StreamEntry[] = []
+        const unsub1 = reader.subscribe((entry) => entries.push(entry))
+        await vi.waitFor(() => expect(entries.length).toBe(1))
+        unsub1() // 最後の購読者解除 → ループ停止
+
+        // 2 回目の購読: 前回位置 "100-1" から再開する (停止中の実イベントを追える)
+        const unsub2 = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(second.requestedIds.length).toBeGreaterThanOrEqual(1))
+        expect(second.requestedIds[0]).toBe("100-1")
+        unsub2()
+
+        // destroy 後の再購読はテスト専用リセット ("$") を経て、再び末尾アンカーへ解決される
+        await reader.destroy()
+        const unsub3 = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(third.requestedIds.length).toBeGreaterThanOrEqual(1))
+        expect(third.requestedIds[0]).toBe("50-3")
+        unsub3()
+        await reader.destroy()
+
+        // 全ライフサイクルを通じて "0-0" (全履歴再生) を一度も要求していないこと
+        const allIds = [first, second, third].flatMap((c) => c.requestedIds)
+        expect(allIds).not.toContain("0-0")
+    })
+
+    it("停止待ちの間に購読者が全解除されたら起動しない (購読者 0 の孤児ループ防止)", async () => {
+        const first = new FakeBlockingClient([])
+        const second = new FakeBlockingClient([])
+        const { redis, created } = makeRedis([first, second], "50-3")
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger: silentLogger })
+
+        // 購読 → ループ稼働
+        const unsub1 = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(created.length).toBe(1))
+        // 解除 (stopping 開始) → stopping 中に再購読 (起動待ち) → 即解除 (購読者 0)
+        unsub1()
+        const unsub2 = reader.subscribe(() => {})
+        unsub2()
+
+        // 停止が完了しても 2 本目のクライアントは生成されないこと (旧実装は購読者 0 でも起動した)
+        await new Promise((resolve) => setTimeout(resolve, 250))
+        expect(created.length).toBe(1)
+        expect((reader as unknown as { _state: string })._state).toBe("idle")
+        await reader.destroy()
+    })
+
+    it('アンカー解決の失敗は warn して "$" のまま縮退し、ループは通常稼働する ("0-0" へは落ちない)', async () => {
+        const client = new FakeBlockingClient([])
+        const { redis } = makeRedis([client], "reject")
+        const warns: unknown[][] = []
+        const logger = { debug() {}, info() {}, warn: (...args: unknown[]) => warns.push(args), error() {} }
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger })
+
+        const unsub = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(client.requestedIds.length).toBeGreaterThanOrEqual(1))
+        // 失敗時は "$" 縮退 (rethrow で state-stuck したり "0-0" の全履歴再生へ落ちたりしない)
+        expect(client.requestedIds[0]).toBe("$")
+        expect(warns.length).toBeGreaterThanOrEqual(1)
+        expect(String(warns[0][0])).toContain("tail anchor")
+        unsub()
+        await reader.destroy()
+    })
+
+    it("onError 省略の購読者しか居なくてもエラーはプロセスを落とさず logger.error へ落ちる", async () => {
+        // リスナー 0 の "error" emit は EventEmitter 仕様で throw し、void 呼びの
+        // _startLoop 内では unhandledRejection = プロセス危険になる。_emitError の
+        // ガードが素の emit へ退行していないことを固定する
+        let attempts = 0
+        const redis: DailyReportRedisProvider = {
+            getClient: async () => undefined,
+            createClient: async () => {
+                attempts++
+                throw new Error("connection refused")
+            },
+        }
+        const errors: unknown[][] = []
+        const logger = { debug() {}, info() {}, warn() {}, error: (...args: unknown[]) => errors.push(args) }
+        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger })
+
+        // onError を渡さない購読 → createClient 失敗 → ガード済みフォールバックが発火する
+        const unsub1 = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(errors.length).toBeGreaterThanOrEqual(1))
+        expect(String(errors[0][0])).toContain("no error listeners")
+        unsub1()
+
+        // state-stuck していないこと (再購読で再試行される)
+        const unsub2 = reader.subscribe(() => {})
+        await vi.waitFor(() => expect(attempts).toBeGreaterThanOrEqual(2))
+        unsub2()
+        await reader.destroy()
+    })
+})

package/src/server/sse-reader.ts

@@ -53,7 +53,14 @@ export class DailyReportSseReader {
     private _emitter = new EventEmitter()
     private _state: "idle" | "running" | "stopping" = "idle"
     private _refCount = 0
-    private _lastId = "0-0"
+    // "$" = 「購読開始以降の新着のみ」の番兵。ループ開始時に一度だけ具体 ID (ストリーム末尾) へ
+    // 解決される (_startLoop 参照)。❗ "0-0" を初期値にしてはならない: 初回購読でストリーム全履歴を
+    // 再生し、過去イベントの invalidatePrefix が初回コールドフェッチの書き込みガードを不成立にして
+    // キャッシュ保存を毒殺する (実測: 履歴 10,006 件の再生で ids バケットが保存されず、次のロードも
+    // 全量コールド)。起動直後のプロセスのキャッシュは空で、過去イベントの無効化は無意味。
+    // 過去分の取りこぼし補償は接続単位の catch-up (Last-Event-ID + xRange) の責務。
+    // 通常の stop/start では従来どおり前回位置を保持し、停止中の実イベントを再開時に追う
+    private _lastId = "$"
     private _client: DailyReportRedisBlockingClient | undefined
     private readonly _logger: DailyReportLogger
 
@@ -105,7 +112,7 @@ export class DailyReportSseReader {
         this._refCount = 0
         await this._stopLoop()
         this._emitter.removeAllListeners()
-        this._lastId = "0-0"
+        this._lastId = "$"
     }
 
     /**
@@ -118,6 +125,9 @@ export class DailyReportSseReader {
             await new Promise((resolve) => setTimeout(resolve, 50))
         }
         if (this._state === "running") return
+        // 停止完了を待つ間に最後の購読者が解除されていたら起動しない
+        // (購読者 0 の孤児ループが専用 Redis 接続を握り続けるのを防ぐ)
+        if (this._refCount === 0) return
 
         this._state = "running"
 
@@ -127,12 +137,12 @@ export class DailyReportSseReader {
             this._client = await this.config.redis?.createClient()
         } catch (err) {
             this._state = "idle"
-            this._emitter.emit("error", err instanceof Error ? err : new Error("Failed to create Redis client for SSE reader"))
+            this._emitError(err instanceof Error ? err : new Error("Failed to create Redis client for SSE reader"))
             return
         }
         if (!this._client) {
             this._state = "idle"
-            this._emitter.emit("error", new Error("Failed to create Redis client for SSE reader"))
+            this._emitError(new Error("Failed to create Redis client for SSE reader"))
             return
         }
 
@@ -141,6 +151,23 @@ export class DailyReportSseReader {
             this._logger.error("Redis client error:", err)
         })
 
+        // ❗ "$" は xRead ごとにサーバー側で「その時点の末尾」へ再解決されるため、BLOCK タイムアウトで
+        // 再武装する合間に届いたエントリを永続的に取りこぼす ("$" が有効なのは最初の 1 回だけ、が
+        // Redis の規約)。ループへ入る前に一度だけ具体 ID へ固定する。空ストリームの "0-0" は
+        // 履歴が存在しないので安全 (毒殺は「履歴があるのに 0-0」の場合のみ)。
+        // 解決に失敗したら "$" のまま縮退する (取りこぼし窓が残るだけで、履歴再生よりは安全)
+        if (this._lastId === "$") {
+            try {
+                const shared = await this.config.redis?.getClient()
+                if (shared) {
+                    const latest = await shared.xRevRange(this.config.streamKey, "+", "-", { COUNT: 1 })
+                    this._lastId = latest.length > 0 ? latest[0].id : "0-0"
+                }
+            } catch (err) {
+                this._logger.warn("Failed to resolve stream tail anchor; falling back to $:", err)
+            }
+        }
+
         try {
             while (this._state === "running" && this._client?.isOpen) {
                 const results = await this._client.xRead([{ key: this.config.streamKey, id: this._lastId }], { BLOCK: 5000, COUNT: 100 })
@@ -177,7 +204,7 @@ export class DailyReportSseReader {
             const isClientClosed = (err as Error)?.constructor?.name === "ClientClosedError"
             if (!isClientClosed && this._state === "running") {
                 this._logger.error("xRead loop error:", err)
-                this._emitter.emit("error", err)
+                this._emitError(err instanceof Error ? err : new Error(String(err)))
             }
         } finally {
             // クライアント切断
@@ -214,10 +241,27 @@ export class DailyReportSseReader {
             }
         }
 
-        // idle になるまで待機。_state は別の非同期ループ (connect の run ループ) が "idle" に戻すが、
-        // TS は await を跨いだクラスフィールドの変化を追えず "stopping" に過剰 narrowing するため、宣言型へキャストして比較する。
-        while ((this._state as "idle" | "running" | "stopping") !== "idle") {
+        // 自分が仕掛けた停止フェーズの完了だけを待つ。"idle" 限定で待つと、停止直後の同期的な
+        // 自動再起動 (finally 内の idle → running 遷移には await が挟まらない) に追い越された場合に
+        // このポーラが永遠に "idle" を観測できず、50ms タイマーが恒久的に残留する。
+        // "stopping" を抜けたら (idle でも running でも) 停止処理としての責務は完了している。
+        // _state は別の非同期ループが書き換えるが、TS は await を跨いだクラスフィールドの変化を
+        // 追えず "stopping" に過剰 narrowing するため、宣言型へキャストして比較する。
+        while ((this._state as "idle" | "running" | "stopping") === "stopping") {
             await new Promise((resolve) => setTimeout(resolve, 50))
         }
     }
+
+    /**
+     * Emits an "error" event only when a listener exists (bare "error" emit throws).
+     * リスナーが居るときだけ "error" イベントを emit する処理 (リスナー 0 の "error" emit は
+     * EventEmitter 仕様で throw し、非同期文脈では unhandled rejection = プロセス危険になるため)。
+     */
+    private _emitError(err: Error): void {
+        if (this._emitter.listenerCount("error") > 0) {
+            this._emitter.emit("error", err)
+        } else {
+            this._logger.error("SSE reader error (no error listeners):", err)
+        }
+    }
 }