Cloudflare Queues

解決する課題

外部のメッセージブローカーを別途構築・運用せず、Workers上だけで非同期のメッセージング基盤を持てます。

• アクセス急増でバックエンド処理が詰まる → キューでバッファ
• 送信側（Producer）と処理側（Consumer）を疎結合にして独立にスケールしたい
• 失敗したメッセージを安全に退避・再試行したい（Dead Letter Queue）
• Workers環境から追加のインフラなしでキューイングを使いたい

主要概念と用語

• キュー（Queue）: メッセージを保持するリソース。作成時に名前を指定し、Producer/Consumerのバインディングと紐づける
• Producer: メッセージをキューへ送信する側。Worker内でenv.QUEUE.send()またはsendBatch()を呼び出す
• Consumer: キューからメッセージを受け取り処理する側。Worker型（Push型、バッチ単位で自動起動）とHTTP Pull型（コンシューマが能動的にHTTPで取得）がある
• バッチ（Batch）: Consumer Workerに一度に渡される複数メッセージの集合。バッチサイズや待機時間（max_batch_timeout）で挙動を調整する
• リトライ（retry）: メッセージ処理に失敗した際、メッセージ単位またはバッチ単位で再試行させる操作
• ack / retry: バッチ内の各メッセージに対し、処理成功ならack()、失敗ならretry()を呼んで結果を明示する
• Dead Letter Queue（DLQ）: 最大リトライ回数を超えたメッセージの退避先として指定できる別のキュー
• 可視性タイムアウトに相当する概念: Cloudflare QueuesはPush型が基本のため、SQSのような明示的な可視性タイムアウトの概念は薄く、Consumer Worker側でのリトライ制御が中心となる

仕様・制限・クォータ

• メッセージのペイロードサイズには上限があり、大きなデータはR2などのオブジェクトストレージに置いて参照（キーやURL）だけをメッセージに載せる設計が推奨される
• 1バッチあたりのメッセージ数、バッチの最大待機時間、リトライ回数の上限などはキュー作成時・Consumer設定時にパラメータとして指定できる
• Consumer WorkerはWorkers標準のCPU時間・実行時間の制約下で動作するため、バッチ処理は時間内に収まるよう設計する
• 配信保証は**at-least-once（最低1回）**であり、まれに同一メッセージが重複して配信され得る
• Consumerには「Push型（Workerが自動起動してバッチを受け取る）」と「Pull型（HTTP APIでコンシューマ側から取得する）」の2方式があり、Workers以外の環境からの利用にはPull型が使われる

内部の仕組み

Producer WorkerがQueueバインディング経由でsend()（単一メッセージ）またはsendBatch()（複数メッセージ）を呼ぶと、メッセージはキューに蓄積されます。Push型Consumerの場合、Cloudflareの基盤がキュー内のメッセージを自動的にまとめてバッチ化し、紐づけられたConsumer Workerのqueue()ハンドラを起動してバッチを渡します。

Consumer Workerはバッチ内の各メッセージを処理し、成功したメッセージにはmessage.ack()、失敗したメッセージにはmessage.retry()を呼び出します。バッチ全体を再試行させることも、メッセージ単位で個別に結果を返すことも可能です。リトライ回数が設定した上限を超えたメッセージは、Dead Letter Queueとして指定した別のキューへ自動的に移動します。

Pull型Consumerの場合は、Workers以外の環境（外部サーバーなど）からHTTP APIでメッセージを取得し、処理後に確認応答を返す方式になります。いずれの方式でも配信保証はat-least-oneのため、重複配信を前提にConsumer側の処理を冪等に実装することが設計の中心になります。

設計パターン / ベストプラクティス

• Queues + Workers: HTTPリクエストで受けた重い処理をキューに積み、Consumer Workerで非同期に処理して応答を高速化する
• バッチ処理でスループット向上: 1件ずつではなくバッチ単位でまとめて処理し、下流サービスへの呼び出し回数を減らす
• Dead Letter Queueで失敗を退避し、原因調査後に再投入する
• 大きいペイロードはR2などに保存し、キューにはオブジェクトの参照だけを載せる
• Consumer Workerの処理時間が長くなりすぎないよう、重い処理はさらに別のキューやWorkflowsに分割する

運用・監視

• Cloudflareダッシュボードおよびオブザーバビリティ機能で、キューの滞留メッセージ数やConsumerの処理状況を確認できる
• Consumer Workerのログ・例外はWorkersのログ機能（wrangler tailやObservability）で追跡する
• 滞留の増加はConsumer側の処理遅延やエラー、下流サービス障害のシグナルになる
• Dead Letter Queueにメッセージが溜まる場合は、Consumerの処理ロジックや権限、メッセージフォーマットの不整合を確認する

コスト

メッセージの送受信操作数と保持に基づく従量課金が中心です。バッチ処理でリクエスト単価を下げるほどコスト効率が上がります。

セキュリティ

• キューへのアクセスはWorkersのバインディング経由に限定され、外部から直接キューを操作するにはCloudflareのAPIトークンによる認証が必要
• Producer/Consumerとして紐づけるWorkerのバインディング設定を最小限にし、不要なWorkerにキューへのアクセス権を与えない
• メッセージ本文に機微情報を直接含めず、必要であれば参照キーのみを載せて実データは別のストレージ側でアクセス制御する

関連サービス・比較

ハンズオン / CLI例

# キューを作成
wrangler queues create jobs-queue

# 作成したキューの一覧を確認
wrangler queues list

# wrangler.tomlでProducerバインディングを設定した後、Workerからメッセージ送信（コード例）
# [[queues.producers]]
# queue = "jobs-queue"
# binding = "QUEUE"

# wrangler.tomlでConsumerを設定（バッチサイズや最大待機時間、DLQを指定）
# [[queues.consumers]]
# queue = "jobs-queue"
# max_batch_size = 10
# max_batch_timeout = 5
# dead_letter_queue = "jobs-queue-dlq"

# Dead Letter Queue用のキューを別途作成
wrangler queues create jobs-queue-dlq

# Consumer Workerをデプロイ
wrangler deploy