永続ジョブと稼働準備

スターターのコミット 2a1a04a に同期しています。

ブラウザーへ応答した後も必ず完了すべき処理、たとえばメール送信、クレジット付与、オブジェクト削除、プライバシー関連の依頼に使います。スターターには軽量な PostgreSQL キューが含まれているため、多くのチームは Redis キューや別のワーカーサービスを先に運用せずに始められます。

バックグラウンド処理の実行と監視を決める

• Vercel では、同梱の5分間隔の cron を維持します。他のホスティングでは、スケジューラーから同じ認証付きエンドポイントを呼びます。
• 中程度の処理量で、ハンドラーが20秒以内に終わるなら、PostgreSQL キューを使い続けられます。長時間処理や高スループットが実際に必要になったときだけ専用キューへ移し、重複排除と冪等性は保ちます。
• /api/health は「プロセスが応答するか」、/api/ready は「このリリースへ本番トラフィックを送れるか」を示します。

本番準備完了の条件： テストジョブが処理され、意図的に失敗させたジョブが再試行後に確認でき、cron が重複しても副作用が二重にならず、稼働準備の失敗と失敗済みキューの増加に警告が出ることです。

なぜ作業を永続化するか

Serverless インスタンスはレスポンス直後に停止することがあります。メール、クレジット付与、オブジェクト削除、アカウントのエクスポートや消去など、必ず完了すべき作業は jobs 表へ書きます。

現在のジョブには、メール、招待、登録クレジット、Slack、ストレージ削除、予約、アカウントのライフサイクル処理があります。

キューへ登録する

await enqueueJob("welcome_email", { email, name, userUuid }, {
  dedupeKey: `welcome:${userUuid}`,
  subjectUserUuid: userUuid
});

dedupeKey により、同じジョブを重複して登録しても一件になります。対象ユーザーの UUID は、プライバシー処理でジョブを取り消し・消去するために使います。ハンドラー自体も冪等である必要があります。

既定 runner を 1 つ選ぶ

Admin /jobs は payload JSON を出さず status、attempt、due age、subject、安全な error を表示します。admin_rw は監査 note 付きで idempotent failed job の retry や standalone notification の cancel ができます。Credit、storage、lifecycle、campaign は所有 workflow から操作します。

ジョブ実行処理

GET /api/cron/jobs は Authorization: Bearer $CRON_SECRET を要求します。Vercel は五分ごとに呼び、他の環境では同じ呼び出しをスケジュールします。

実行処理は FOR UPDATE SKIP LOCKED で一件ずつ取得し、重複実行を防ぎます。処理権の期限は五分、ハンドラーの上限は20秒、全体の処理時間は40秒です。既定では最大五回、30秒から始まる指数バックオフで再試行し、結果を14日間保持します。未完了のアップロードと停滞した Stripe イベントも掃除します。

生存確認と稼働準備確認

/api/health はプロセスだけを確認します。/api/ready は環境設定、DB とマイグレーション、分散 Redis、キューの状態を確認します。重大な依存先の障害は HTTP 503、キュー障害は degraded として報告します。

定期的な監視には health、新しいバージョンへトラフィックを流す前の確認には ready を使います。200 以外の応答と失敗ジョブの増加を監視し、ジョブデータの形式変更は後方互換にします。本番のスケジュールと監視を用意したら、デプロイとセキュリティの最終確認へ進んでください。