iii-queue-processing

キュー処理

類似：BullMQ、Celery、SQS

主な概念

タスクに適している場合は、以下の概念を使用してください。すべてのキュー構成で、これらすべてが必要になるわけではありません。

• 名前付きキューは、queue_configs の下にある iii-config.yaml で宣言します
• 標準キューはジョブを並行して処理し、FIFO キューは順序を保持します
• TriggerAction.Enqueue({ queue }) は、名前付きキューにジョブをディスパッチします
• 失敗したジョブは、max_retries に達するまで指数バックオフで自動再試行されます
• 再試行回数を使い切ったジョブは、調査用のデッドレターキューに送られます
• 各コンシューマー関数には、ジョブのペイロードと messageReceiptId が渡されます

アーキテクチャ

プロデューサー関数
  → TriggerAction.Enqueue({ queue: 'task-queue' })
    → 名前付きキュー（標準または FIFO）
      → コンシューマーの registerFunction ハンドラー
        → 成功／バックオフによる再試行
          → デッドレターキュー（max_retries 到達後）

使用する iii プリミティブ

プリミティブ	目的
registerFunction	ジョブを処理するコンシューマーを定義します
trigger({ ..., action: TriggerAction.Enqueue({ queue }) })	名前付きキューにジョブをディスパッチします
messageReceiptId	個々のジョブ処理を確認または追跡します
queue_configs in iii-config.yaml	並列処理数と再試行回数を指定してキューを宣言します

参照実装

動作する完全なサンプルについては、../references/queue-processing.js を参照してください。ジョブをキューに登録するプロデューサーと、再試行ロジックを使ってジョブを処理するコンシューマーが含まれています。

Python 版もあります：../references/queue-processing.py

Rust 版もあります：../references/queue-processing.rs

よく使われるパターン

このパターンを使うコードには、関連する場合、通常以下が含まれます。

• registerWorker(url, { workerName }) — ワーカーを初期化します
• registerFunction(id, handler) — コンシューマーを定義します
• trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) }) — ジョブをキューに登録します
• payload.messageReceiptId — ジョブを追跡または確認します
• trigger({ function_id: 'state::set', payload }) — 処理後の結果を永続化します
• const logger = new Logger() — ジョブごとに構造化ログを記録します

このパターンの適用

タスクに該当する場合は、以下の適用方法を使用してください。

• ジョブの順序が重要な場合（例：パイプラインの各ステップを順番に実行する場合）は、FIFO キューを選択します
• ワークロードに合わせて、キュー構成の max_retries と concurrency を設定します
• 複数段階のパイプラインでは、複数のキューを連結します（キュー A のコンシューマーがキュー B に登録します）
• 冪等性を確保するため、再試行時の重複処理を避けられるよう、処理前に状態を確認します

エンジン構成

名前付きキューは、キューごとの max_retries、concurrency、type、backoff_ms とともに、queue_configs の下にある iii-config.yaml で宣言します。注釈付きの構成リファレンス全体については、../references/iii-config.yaml を参照してください。

パターンの適用範囲

• 再試行や順序制御なしのファイア・アンド・フォーゲットだけが必要なタスクでは、TriggerAction.Void() を使う iii-trigger-actions を優先してください。
• 失敗したジョブに特別な処理やアラートが必要な場合は、DLQ コンシューマー向けの iii-dead-letter-queues を優先してください。
• 分岐を伴う段階的なオーケストレーションが必要なタスクでは、iii-workflow-orchestration を優先してください。
• 主な要件が、再試行を伴う信頼性の高い非同期ジョブ実行である場合は、iii-queue-processing を使用してください。

使用するタイミング

• タスクの主な内容が iii エンジンでの iii-queue-processing に関する場合は、このスキルを使用してください。
• リクエストでこのパターンまたは同等の実装が直接求められた場合に適用します。

適用範囲

• 無関係なタスクに対する汎用的なフォールバックとして、このスキルを使用しないでください。
• より適切な iii スキルがある場合、このスキルを適用してはいけません。
• このスキルの例を適用する前に、必ず環境と安全上の制約を確認してください。