[mash]

背景

Firehose Direct PUTはRecordごとに取り込み量を5 KiB単位で切り上げる。小さいJSON行を別々のRecordで送る経路では、APIバッチ化だけでは課金対象量を減らせない。

解決したい課題

呼出元が既存の行区切りを保ったまま複数payloadを1 Recordにまとめ、部分失敗・容量超過・終了時の未送信を区別して扱えるようにする。

変更内容の概要

集約はopt-inとし、呼出元が区切りを含めたbytesを渡す。ライブラリは再エンコードやイベント分断を行わない。先頭イベントの期限を固定し、送信の停滞中も独立したタイマーでRecordを確定する。

集約後も受付イベント数とFirehose Record数を別々に追跡するため、queue・retry・in-flightを同じ会計に含める。HTTP成功時の部分失敗は失敗Recordだけを同じbytesで再送し、不正応答・結果不明の通信失敗では対象全体を再送する。

保持上限は既定100,000イベント／payload 64 MiB。Recordは1〜1,024,000 B、送信バッチは最大500 Record／4,000,000 Bとする。Loopのcontext終了後は入力を閉じ、既定10秒の独立したcontextでdrainする。期限超過時は残件・残bytesをerrorに含める。

影響範囲

既定では集約を有効にしない。payloadのコピー、バイト上限、部分失敗の扱い、drainの期限は集約offでも変わる。呼出元はEnqueueとLoopのerrorを確認し、必要に応じて容量とdrain期限を指定する。

その他(補足など)

検証

• go test -race ./... 成功。raw bytesの維持、64 KiB／1,000 KiB境界、batch件数・bytes、部分失敗、429／5xx／timeout、不正応答、同時Enqueue、並列workerの起床、送信中の集約期限、キャンセル後drainを確認した。
• go build ./...、go vet ./...、golint -set_exit_status ./... 成功。
• 新しい独立レビュアーでコード・lint・簡素化・DB・コスト・Actionsを確認し、最終確認の追加指摘は0件。
• 実行環境のGoは1.26系。Go 1.14実機でのテストは実施していない。

制約・運用

メモリキューのため、プロセス消失時の永続性とexactly-onceを保証しない。結果不明の再送では複数イベントがまとまって重複し得る。通常運転の再試行回数・総時間には上限を設けず、指数バックオフと保持量上限で抑制する。ErrorHandler・observerは速やかに戻り、クライアントはcontext cancellationに従う必要がある。

SuccessfulEventsはFirehoseの受付確認を表し、S3への保存完了を表さない。既知の恒久エラーはErrorHandlerとFailedEventsへ反映し、キューが空ならLoopはnilを返す。EstimatedBillableBytesはSDK呼出し単位の概算で、SDK内部の再送・実際の受理結果を反映する請求台帳ではない。

コスト影響

Phase A（定性）のみ実施。既存Firehoseと下流S3が対象。有効化時はRecord単位の切り上げ量を減らす方向に働く。曖昧な送信結果と再試行の継続は重複取り込み・転送・保存量を増やし得る。新規AWSリソースは追加しない。呼出元アプリでの有効化・カナリア・料金削減の実測は別途行う。

分割せず作成した理由

集約により1 Recordが複数イベントを持つため、部分失敗・in-flightを含む容量計算・drain・統計も同じ単位対応を使う。これらを1つのライブラリdraftで検証し、呼出元アプリの組込みは別PRに分ける。