Cloudflare Workers × Turso 500復旧: Codexで作った再発防止設計

この記事はCodex製です。

##依頼内容と課題

依頼は、既存プロダクトで起きた Cloudflare Workers + Turso の500障害について、技術的な根本原因と修正内容を整理し、今後Codexをどう運用に組み込むべきかまで含めて ro1.dev/memo 向けに新規記事化すること。

本件の難しさは、エラーが単一原因ではなく、次の2系統が重なっていたこと。

1. ランタイム経路問題: @libsql/client が Workers ネイティブ経路ではなく Node HTTP 系へ落ち、null.has でクラッシュ
2. 運用問題: 正常版デプロイ後に後続デプロイが上書きし、「直ったはずなのに再発」を発生させた

##アプローチ

Codexには「コード修正」だけでなく、観測性と運用統制まで同時に扱うように指示した。

1. エラー観測を強化
   Route Handler の非業務例外で name/message/stack/cause を構造化ログ出力。
2. DBクライアント境界を固定
   createClient に fetch: globalThis.fetch を明示し、Workers実行時に Node HTTP 経路へ落ちる余地を排除。
3. ビルド/デプロイ経路を安定化
   OpenNextとの整合を優先し、ビルド条件とバンドル境界の不安定要素を削減。
4. デプロイ版ドリフトを抑制
   反映後に deployments list と実行Versionを照合し、期待版が100%配信されていることを確認。
5. 修正後の再現試験
   POST /api/reveals を再実行し、成功とログ静穏化を同時確認。

この順序にした理由は、原因がアプリコードと運用の境界に跨っていたため。どちらか一方だけ触ると再発する構造だった。

##アウトプット

最終的に得たアウトプットは「障害復旧手順」ではなく「運用可能な恒久対策セット」。

###1. 実装修正の効果

1. Workers環境での libsql 通信経路を明示化できた
2. 500発生時の調査コストを、ログ不足起点の往復から解放できた
3. 問題版の混入を、デプロイ版照合で早期検出できる運用に切り替えた

###2. 今後のCodex活用方針

1. 障害対応は 再現率の数値化 を完了条件に置く
2. Codexには 修正 と同時に 観測強化 も必須タスクとして渡す
3. デプロイ後は エンドポイント合成監視 + version id 突合 を自動化する
4. 収束後は必ず技術メモ化し、次回の初速を上げる

###3. 実務での設計原則

1. ランタイム依存の暗黙分岐を減らし、通信経路を明示する
2. 業務エラーとシステムエラーを分離して記録する
3. デプロイ状態をコード外の運用要因として監視対象にする

Cloudflare Workers と外部DBの組み合わせでは、実装修正だけでは品質が安定しない。Codexを使う価値は、実装・検証・運用統制を一つの作業単位で回し、再発防止までを同時に閉じられる点にある。