背景処理の実行文脈をリクエストごとに持つ (#317)

[kojira]

何が壊れていたか

deferBackground() が参照する ExecutionContext を runtime.ts のモジュール変数に置いていた。Cloudflare Workers は1つのアイソレートで複数リクエストを同時に捌くため、

1. リクエストA がログイン処理に入り、bindEnv(env, ctxA) で _ctx = ctxA
2. A が外向き fetch（連携先のアイコン取得など）で待ちに入る
3. その間にリクエストB が来て bindEnv(env, ctxB) → _ctx = ctxB に上書き
4. A が再開して deferBackground(work) を呼ぶと、A の仕事が B の waitUntil に載る

B のレスポンスが先に終わると、A の背景処理は走り切る前に打ち切られうる。運用側から見える形は「送ったはずのメールが出ない」「取り込んだはずのアイコンが保存されない」「最終アクセス時刻が記録されない」で、いずれも例外は出ないので静かに落ちる。#313 でアイコン取り込みがログインのホットパスに載ったため、踏む頻度が上がっていた。

直し方

実行文脈を AsyncLocalStorage に移し、Worker のエントリ（fetch / scheduled）で1回だけ張る。

• apps/server/src/runtime.ts:57 — ctxStore。deferBackground は ctxStore.getStore() から自分のリクエストの ctx を取る
• apps/server/src/runtime.ts:65 — runWithExecutionContext(ctx, fn)
• apps/server/src/worker.ts:642 — fetch が張る。bindEnv から ctx 引数を落とした
• apps/server/src/worker.ts:659 — scheduled（cron）も自分の文脈を張る。以前は文脈なしでその場 await に落ちていた

Hono の Context を引き回さなかった理由: deferBackground の呼び出し元は db/repositories/notifications.ts などリポジトリ層まで深い。c を引数で通すと db 層が HTTP フレームワークに依存し、通り道の全ハンドラを書き換えることになる。AsyncLocalStorage なら呼び出し側の書き方を一切変えずに文脈だけをリクエストへ閉じ込められる（nodejs_compat は既に有効）。到達経路を1本に保つため、モジュール変数の控えは残していない。文脈の外（テストからの直接呼び出し）では従来どおりその場で await する。

テストが噛むことの確認

apps/server/test/runtime-execution-context.test.ts を追加。A が待っている間に B が丸ごと走り切る状況を作り、A の背景処理が A の ctx に付くことを見る。

仕組みだけを修正前（モジュール変数）に戻すと落ちる:

 FAIL  test/runtime-execution-context.test.ts > 背景処理の実行文脈はリクエストごと (#317) > A が待っている間に B が入っても、A の背景処理は A の ctx に付く
AssertionError: expected [] to deeply equal [ Promise{…} ]

- Expected
+ Received

- [
-   Promise {},
- ]
+ []

A の ctx は空＝A の仕事は B の ctx に載っていた、という #317 そのものの形。

監査した呼び出し元

deferBackground の全10か所（一斉連絡、アイコン取り込み、最終アクセス時刻、通知作成2か所、事前アンケート、スケジュール資料メタ2か所、一斉連絡の再送、アイコン配信キャッシュ）を確認。いずれも HTTP ルートか cron からしか到達せず、モジュールスコープで走るものは無い。cron は文脈を張るようにしたので、リマインダー配下の背景処理も自分の ctx に載る。

メール送信・OG取得の予算（takeEmailSlot / takeOgFetchSlot）はアイソレート共有のモジュール変数のまま。暴走防止の安全弁で、多めに数えて送信を控える側に倒れるだけなので取りこぼしにはならない。設計doc に明記した。

設計doc

docs/design.md に「バックグラウンド処理の実行文脈 (#317)」節を追加。なぜリクエストごとに持つ必要があるか、なぜ AsyncLocalStorage か、文脈を張るのはエントリ1か所だけ、という制約を書いた。

Closes #317

🤖 Generated with Claude Code

https://claude.ai/code/session_01SLkuubF8cHzSnnsv4fN9DA