iii-workflow-orchestration

ワークフローのオーケストレーションと永続実行

比較対象：Temporal、Airflow、Inngest

主な概念

タスクに適している場合は、以下の概念を使用してください。すべてのワークフローで、ここに示す永続化や追跡の仕組みがすべて必要になるわけではありません。

• 各パイプラインステップは、設定に基づくリトライを備えた名前付きキューで連結された登録済み関数です
• ステップの進行状況は共有状態で追跡され、ストリームを介してブロードキャストされます
• Cron トリガーで、スケジュールされたメンテナンス（例：古い注文のクリーンアップ）を処理します
• キューの動作（リトライ、バックオフ、同時実行数、FIFO）は、iii-config.yaml でキューごとに定義します

アーキテクチャ

HTTP (create order)
  → Enqueue(order-validate) → validate
    → Enqueue(order-payment) → charge-payment
      → Enqueue(order-ship) → ship
        → publish(order.fulfilled)

Cron (hourly) → cleanup-stale

Queue configs (iii-config.yaml):
  order-validate:  max_retries: 2
  order-payment:   max_retries: 5, type: fifo, concurrency: 2
  order-ship:      max_retries: 3

使用する iii プリミティブ

プリミティブ	目的
registerWorker	ワーカーを初期化し、iii に接続する
registerFunction	各パイプラインステップを定義する
trigger({ ..., action: TriggerAction.Enqueue({ queue }) })	名前付きキューを介してステップを永続的に連結する
trigger({ function_id: 'state::...', payload })	ステップの進行状況を追跡する
trigger({ ..., action: TriggerAction.Void() })	ストリームイベントを通知し、配信する
registerTrigger({ type: 'cron' })	スケジュールされたメンテナンス
registerTrigger({ type: 'http' })	エントリーポイント

リファレンス実装

注文の検証 → 決済 → 出荷のステップ、リトライ設定、ストリームベースの進行状況追跡、1 時間ごとの古い注文のクリーンアップを含む、動作する完全な例については、../references/workflow-orchestration.js を参照してください。

一般的なパターン

このパターンを使用するコードには、必要に応じて、一般に以下が含まれます。

• registerWorker(url, { workerName }) — ワーカーの初期化
• trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) }) — 名前付きキューを介したステップの永続的な連結
• trigger({ function_id: 'state::update', payload: { scope, key, ops } }) — ステップの進行状況の追跡
• リトライ／同時実行数の設定を参照するコメントを付けた名前付きキュー
• const logger = new Logger() — 各ステップの構造化ログ
• 単一の役割を担う独立した registerFunction として各ステップを定義
• trigger({ function_id: 'publish', payload, action: TriggerAction.Void() }) — 完了のブロードキャスト

このパターンの適用

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

• 各ステップでは 1 つの処理を行い、成功したら次の関数をキューに追加します
• ステップごとに異なるリトライ／同時実行数の設定が必要な場合は、iii-config.yaml で別々の名前付きキューを定義します
• 必要に応じて、監視や DLQ との関連付けのためにキューへの追加レシート（messageReceiptId）を取得します
• trackStep ヘルパーパターン（状態の更新＋ストリームイベント）は、あらゆるパイプラインで再利用できます
• ジョブがリトライを使い切ると、DLQ に移動します。デッドレターキュー HOWTO を参照してください
• 名前付きキューの DLQ は、Builtin アダプターと RabbitMQ アダプターでサポートされています（Redis は pub/sub のみです）
• Cron 式では 7 桁の数値形式を使用します：0 0 * * * * *（1 時間ごと）

エンジンの設定

パイプラインステップ用の名前付きキューは、queue_configs の下に iii-config.yaml で宣言し、キューごとにリトライ、同時実行数、FIFO の設定を指定します。注釈付きの完全な設定リファレンスについては、../references/iii-config.yaml を参照してください。

パターンの境界

• タスクが「HTTP エンドポイントを、HTTP から呼び出される registerFunction 関数としてモデル化する」ことである場合（{ path, id } 配列を反復処理して登録する場合を含む）は、iii-http-invoked-functions を優先してください。
• 永続的なステップの順序付け、キューの再試行／バックオフ、ワークフローの進捗追跡が主な課題である場合は、iii-workflow-orchestration を使用してください。

使用するタイミング

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

境界

• 無関係なタスクに対する汎用的な代替手段として、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合は、このスキルを適用してはいけません。
• このスキルの例を適用する前に、環境と安全性の制約を必ず確認してください。