@aiquants/daily-report 0.20.0 → 0.21.0

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

@@ -1,302 +0,0 @@
-import { describe, expect, it, vi } from "vitest"
-import { createEpochStore, SqlResultCache } from "./cache"
-import type { DailyReportRedisProvider } from "./ports"
-import { DailyReportSseReader, isStreamIdLte, type StreamEntry } from "./sse-reader"
-
-/**
- * Robustness tests for the SSE fan-out reader (createClient failure recovery + id compare).
- * SSE Fan-Out リーダーの堅牢性テスト (createClient 失敗時の復帰 + Stream ID 比較)。
- */
-
-const makeCache = () => new SqlResultCache({ defaultTtlMs: 1000 }, createEpochStore(undefined))
-
-describe("isStreamIdLte", () => {
-    it("数値比較で ms / seq を正しく順序付ける (辞書順の罠を回避)", () => {
-        expect(isStreamIdLte("100-0", "100-0")).toBe(true)
-        expect(isStreamIdLte("100-2", "100-10")).toBe(true) // 辞書順なら false になる罠
-        expect(isStreamIdLte("101-0", "100-9")).toBe(false)
-    })
-})
-
-describe("DailyReportSseReader createClient failure recovery", () => {
-    it("createClient が reject しても _state が stuck せず、再購読でループを再開できる", async () => {
-        let attempts = 0
-        const redis: DailyReportRedisProvider = {
-            getClient: async () => undefined,
-            // 1 回目は例外を投げ、2 回目は undefined を返す (どちらも復帰可能であること)
-            createClient: async () => {
-                attempts++
-                if (attempts === 1) throw new Error("connection refused")
-                return undefined
-            },
-        }
-        const reader = new DailyReportSseReader({ redis, streamKey: "test:stream", cache: makeCache(), logger: { debug() {}, info() {}, warn() {}, error() {} } })
-
-        const errors: Error[] = []
-        // 1 回目の購読 → createClient throw → error emit → _state idle へ復帰
-        const unsub1 = reader.subscribe(
-            () => {},
-            (e) => errors.push(e),
-        )
-        // マイクロタスク/ループ完了を待つ
-        await vi.waitFor(() => expect(errors.length).toBeGreaterThanOrEqual(1))
-        expect(errors[0].message).toBe("connection refused")
-        unsub1()
-
-        // 2 回目の購読 → createClient は再度呼ばれる (state-stuck していない証拠)
-        const unsub2 = reader.subscribe(
-            () => {},
-            () => {},
-        )
-        await vi.waitFor(() => expect(attempts).toBe(2))
-        unsub2()
-        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

@@ -1,267 +0,0 @@
-/**
- * Fan-Out shared reader for the daily report SSE Redis Stream.
- * 日報 SSE 用 Redis Stream の共有リーダーモジュール。
- *
- * 単一の xRead BLOCK ループで全接続にメッセージをブロードキャストし、
- * 接続ごとに Redis TCP を張る問題を解消する。
- */
-
-import { EventEmitter } from "node:events"
-import { createLogger, type DailyReportLogger, LogLevel } from "../shared/logger"
-import type { SqlResultCache } from "./cache"
-import type { DailyReportRedisBlockingClient, DailyReportRedisProvider } from "./ports"
-
-/**
- * Compares two Redis Stream IDs numerically.
- * Redis Stream ID を数値比較し、a <= b なら true を返す。
- *
- * Stream ID は `<timestamp_ms>-<sequence>` 形式。
- * 辞書順比較では sequence が可変長のとき不正確になるため、数値分割で比較する。
- */
-export const isStreamIdLte = (a: string, b: string): boolean => {
-    const [aMs, aSeq] = a.split("-").map(Number)
-    const [bMs, bSeq] = b.split("-").map(Number)
-    if (aMs !== bMs) return aMs < bMs
-    return aSeq <= bSeq
-}
-
-/** xRead 結果の 1 エントリに相当する型。 */
-export type StreamEntry = {
-    id: string
-    message: Record<string, string>
-}
-
-export type DailyReportSseReaderConfig = {
-    /** ブロッキング xRead 用の専用クライアントを生成する redis プロバイダー。 */
-    redis?: DailyReportRedisProvider
-    /** SSE Redis Stream キー。 */
-    streamKey: string
-    /** 受信メッセージに応じてローカル SQL キャッシュを無効化する対象キャッシュ。 */
-    cache: SqlResultCache
-    /** ロガー (既定は console ベース)。 */
-    logger?: DailyReportLogger
-}
-
-/**
- * Shared xRead loop that fans out entries to all active SSE connections.
- * 全 SSE 接続に対してメッセージをファンアウトする共有 xRead ループ。
- *
- * - "entry" イベント: 新着エントリ (StreamEntry) をブロードキャスト
- * - "error" イベント: 回復不能エラーをブロードキャスト
- * */
-export class DailyReportSseReader {
-    private _emitter = new EventEmitter()
-    private _state: "idle" | "running" | "stopping" = "idle"
-    private _refCount = 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
-
-    constructor(private readonly config: DailyReportSseReaderConfig) {
-        // リスナー上限を緩和 (接続数分)
-        this._emitter.setMaxListeners(0)
-        this._logger = config.logger ?? createLogger(LogLevel.INFO, "[SSE Reader]")
-    }
-
-    /**
-     * Subscribes to the shared reader. Starts the loop on first subscriber.
-     * 共有リーダーを購読する。最初の購読者でループを開始する。
-     *
-     * @param onEntry - 新着エントリのコールバック
-     * @param onError - 回復不能エラーのコールバック (省略可)
-     * @returns unsubscribe 関数。呼び出すと両リスナーを解除し、最後の購読者解除でループを停止する。
-     */
-    subscribe(onEntry: (entry: StreamEntry) => void, onError?: (err: Error) => void): () => void {
-        this._emitter.on("entry", onEntry)
-        if (onError) {
-            this._emitter.on("error", onError)
-        }
-        this._refCount++
-
-        // 最初の購読者でループ開始
-        if (this._refCount === 1) {
-            void this._startLoop()
-        }
-
-        // unsubscribe
-        return () => {
-            this._emitter.removeListener("entry", onEntry)
-            if (onError) {
-                this._emitter.removeListener("error", onError)
-            }
-            this._refCount--
-            if (this._refCount <= 0) {
-                this._refCount = 0
-                void this._stopLoop()
-            }
-        }
-    }
-
-    /**
-     * Destroys the reader for test cleanup.
-     * テストクリーンアップ用のデストラクタ。
-     */
-    async destroy(): Promise<void> {
-        this._refCount = 0
-        await this._stopLoop()
-        this._emitter.removeAllListeners()
-        this._lastId = "$"
-    }
-
-    /**
-     * Internal xRead BLOCK loop.
-     * 内部 xRead BLOCK ループ。
-     */
-    private async _startLoop(): Promise<void> {
-        // stopping 中なら完了を待つ
-        while (this._state === "stopping") {
-            await new Promise((resolve) => setTimeout(resolve, 50))
-        }
-        if (this._state === "running") return
-        // 停止完了を待つ間に最後の購読者が解除されていたら起動しない
-        // (購読者 0 の孤児ループが専用 Redis 接続を握り続けるのを防ぐ)
-        if (this._refCount === 0) return
-
-        this._state = "running"
-
-        // 専用クライアント取得。createClient が reject した場合も _state を idle へ戻し、
-        // 再購読でループを再開できるようにする (注入 redis 実装が例外を投げても state-stuck しない)。
-        try {
-            this._client = await this.config.redis?.createClient()
-        } catch (err) {
-            this._state = "idle"
-            this._emitError(err instanceof Error ? err : new Error("Failed to create Redis client for SSE reader"))
-            return
-        }
-        if (!this._client) {
-            this._state = "idle"
-            this._emitError(new Error("Failed to create Redis client for SSE reader"))
-            return
-        }
-
-        // エラーリスナー
-        this._client.on("error", (err) => {
-            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 })
-                if (!results) continue
-
-                for (const stream of results) {
-                    for (const msg of stream.messages) {
-                        this._lastId = msg.id
-                        // epoch check の補完: SSE 経由でもローカルキャッシュを即座にクリア
-                        // (epoch check が主防御線。SSE は Redis ダウン時や非 epoch 対象キャッシュへのフォールバック)
-                        try {
-                            const parsed = msg.message?.data ? JSON.parse(msg.message.data) : null
-                            const msgType = parsed?.type
-                            if (msgType === "report-create" || msgType === "report-delete" || msgType === "report-publish") {
-                                this.config.cache.invalidatePrefix("daily-report:ids")
-                            }
-                            // コメント・ステータス変更時は対象レポートの詳細キャッシュを無効化
-                            if (msgType === "comment-add" || msgType === "comment-delete" || msgType === "status-update") {
-                                const reportHubId = parsed?.reportHubId
-                                if (typeof reportHubId === "number") {
-                                    this.config.cache.invalidate(`daily-report:detail:${reportHubId}`)
-                                    this.config.cache.invalidatePrefix(`daily-report:detail:${reportHubId}:user:`)
-                                }
-                            }
-                        } catch {
-                            // JSON パースエラーは無視 (invalidation スキップ = safe 方向)
-                        }
-                        this._emitter.emit("entry", { id: msg.id, message: msg.message as Record<string, string> })
-                    }
-                }
-            }
-        } catch (err) {
-            // ClientClosedError は正常停止時に発生する
-            const isClientClosed = (err as Error)?.constructor?.name === "ClientClosedError"
-            if (!isClientClosed && this._state === "running") {
-                this._logger.error("xRead loop error:", err)
-                this._emitError(err instanceof Error ? err : new Error(String(err)))
-            }
-        } finally {
-            // クライアント切断
-            if (this._client?.isOpen) {
-                try {
-                    await this._client.quit()
-                } catch (_e) {
-                    // 切断エラーは無視
-                }
-            }
-            this._client = undefined
-            this._state = "idle"
-
-            // ループ終了後に購読者が残っていれば自動再起動
-            if (this._refCount > 0) {
-                void this._startLoop()
-            }
-        }
-    }
-
-    /**
-     * Stops the xRead loop by closing the client.
-     * クライアントを閉じて xRead ループを停止する。
-     */
-    private async _stopLoop(): Promise<void> {
-        if (this._state !== "running") return
-        this._state = "stopping"
-
-        if (this._client?.isOpen) {
-            try {
-                await this._client.quit()
-            } catch (_e) {
-                // 切断エラーは無視
-            }
-        }
-
-        // 自分が仕掛けた停止フェーズの完了だけを待つ。"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)
-        }
-    }
-}