ワークフローのタイムトラベル

Queuetyを使うと、ワークフローを前のステップに巻き戻し、その時点から実行を再開できます。ステップが不正な出力を生成した場合、別の設定で再試行したい場合、ワークフロー全体を再起動せずに破損データから復旧したい場合に便利です。

巻き戻しにはワークフローイベントログが必要です。対象ステップのstate_afterデータがイベントログに記録されている必要があります。

ワークフローを巻き戻す

PHP API

ワークフローIDと巻き戻し先のステップインデックスを指定してQueuety::rewind_workflow()を呼び出します。

use Queuety\Queuety;

// Rewind workflow 42 to step 1.
// The state is restored to the snapshot taken after step 1 completed,
// and step 2 is enqueued for re-execution.
Queuety::rewind_workflow( $workflow_id, to_step: 1 );

to_stepパラメーターは、完了状態を復元するステップの0始まりのインデックスです。実行は次のステップ（to_step + 1）から再開します。

CLI

wp queuety workflow rewind <id> <step>

wp queuety workflow rewind 42 1

仕組み

ワークフローをステップNまで巻き戻すと、次の処理が行われます。

1. イベントログを検索し、ステップNの完了後に記録されたstate_after値を取得します
2. スナップショットがない場合はRuntimeExceptionがスローされます
3. ワークフロー行がロックされます
4. 現在のワークフロー行にある予約済みキー（_steps、_queue、_priorityなど）を保持しつつ、ワークフロー状態をスナップショットで置き換えます
5. current_stepにN + 1を設定し、statusにrunningを設定します
6. error_messageおよびfailed_atフィールドをクリアします
7. インデックスN + 1のステップを処理対象としてキューに追加します
8. workflow_rewoundログイベントを記録します

その後、ワーカーがキューに追加されたステップを処理し、そこから通常どおりワークフローを続行します。

必要条件

巻き戻しにはイベントログ内のstate_afterデータが必要です。イベントログはすべてのstep_completedイベントについて自動的に記録します。イベントログが（WorkflowEventLog::prune()経由で）整理され、対象ステップの状態が残っていない場合、巻き戻しは失敗します。

イベントログの保持期間が、巻き戻しが必要になる可能性のある期間をカバーしていることを確認してください。

活用例

不具合のあるステップハンドラーを修正する

ステップハンドラーの不具合によって誤った出力が生成された場合は、修正版をデプロイして巻き戻せます。

// Step 2 (CallLLMHandler) produced garbled output due to a prompt bug.
// After fixing CallLLMHandler, rewind to step 1 so step 2 runs again
// with the corrected handler.
Queuety::rewind_workflow( $workflow_id, to_step: 1 );

異なる設定で再試行する

外部要因（APIのレート制限や認証情報の誤り）でステップが失敗した場合は、設定を修正してから巻き戻し、再実行します。

// Step 3 failed because the API key was expired.
// After updating the key, rewind to step 2 so step 3 retries.
Queuety::rewind_workflow( $workflow_id, to_step: 2 );

不正なデータから復旧する

前のステップで状態に不正なデータが追加された場合は、正常な状態が確認できているスナップショットまで巻き戻します。

// Step 0 fetched correct data, but step 1 corrupted it.
// Rewind to step 0 to restore the good state and re-run step 1.
Queuety::rewind_workflow( $workflow_id, to_step: 0 );

再試行との比較