Pro エディション

Output Pipeline

概要

Output Pipeline は、PDF ステップの宣言的なマニフェストを依存関係の順序で実行し、ステップごとのリトライと stop-on-error オプションを備えます。一部のステップタイプは、追加の Enterprise Pack ケーパビリティを必要とします。

提供とライセンス

この機能は NextPDF Pro（nextpdf/pro）に含まれ、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントは、この機能のクラスをロードしません。エディションを比較してライセンスを取得する。

パイプラインエグゼキューター自体は Pro エディションの一部です。3 つのステップタイプは、加えて名前付きの Enterprise Pack ケーパビリティを必要とします。redaction ステップは Privacy Pack ケーパビリティを、extraction と OCR オーバーレイのステップは Intelligence Pack ケーパビリティを必要とします。ライセンスのないゲート対象ステップは、実行時にフェイルクローズドとなり（失敗したステップ結果を返し、そのリゾルバーは決して呼び出されません）、実行全体を中断することはありません。

インストール

composer require nextpdf/pro:^3

コードは NextPDF\Pro\OutputPipeline 名前空間の下にあります。

概念の概要

PipelineExecutor は PipelineManifest を受け取り、ステップをトポロジカル順序に並べ替え、各ステップを StepResolverRegistry に登録されたリゾルバーへディスパッチします。ステップの出力は、下流のステップのために PipelineContext に保存されます。エグゼキューターはグローバルタイムアウトを強制し、ステップごとのリトライをサポートし、指定したステップから再開できます。リクエストハンドラーから直接ではなく、非同期のジョブワーカー内で実行されるように設計されています。

組み込みのステップタイプには、generate、merge、split、inspect、compress、sign、convert が含まれます。redaction、extraction、OCR オーバーレイのステップタイプはケーパビリティでライセンスされ、Enterprise Pack ケーパビリティに対応付けられます。

この仕組みである理由

エグゼキューターはオーケストレーションのみを担います。ステップを並べ替え、ライセンスゲートを強制し、各ステップを登録されたリゾルバーへディスパッチしますが、PDF の処理自体は一切行いません。この分離により、1 つのマニフェストは、この逐次的な PHP パスを通じて、あるいはステップを並列にディスパッチする帯域外ワーカーを通じて実行でき、呼び出し側のコードを変更する必要はありません。この設計はリクエストハンドラーではなく非同期のジョブワーカーを対象とします。多段階のパイプラインは日常的にリクエストの予算を超えて長引き、キューはワーカーを追加することでスループットをスケールさせるためです。グローバルタイムアウトが同じ理由でステップ間にチェックされます。1 つのステップ全体がリゾルバーに渡される作業の単位であり、オーケストレーターはそのリゾルバーの実行に立ち入りません。失敗は、スローされる例外ではなくステップごとの StepResult 値として表面化するため、1 つの失敗したステップがワーカーの報告する集約的な PipelineResult を崩壊させることは決してありません。

設計の背景：大量文書生成。

振る舞いの契約

execute($manifest, $variables) は、全体のステータス、ステップごとの結果、所要時間、完了および失敗したステップの数を伴う結果を返します。
ステップはトポロジカル順序で実行されます。あるステップタイプにリゾルバーが存在しない場合は、明確なメッセージを伴う失敗したステップになります。
PipelineOptions::$stopOnError は最初の失敗で実行を停止します。そうでない場合、実行は継続し、最終ステータスはいずれの失敗も反映します。
グローバルタイムアウトが設定されている場合、次のステップが開始する前にそれを超過すると、パイプラインは失敗します。
ステップごとのリトライは、構成された最大値で境界が設けられます。リトライされるのは非終端的な失敗のみです。
resume-from-step は、指定したステップに到達するまで前のステップをスキップします。
ケーパビリティでゲートされたステップタイプは、必要な Pack ケーパビリティが存在しない場合、実行時にライセンスエラーコードを伴ってフェイルクローズドとなります。リゾルバーは決して呼び出されません。

コードサンプル — クイックスタート

以下は、文書化された公開 API を反映したものです。このモジュールについては、リポジトリに実行可能な例は付属していません。

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$result = (new PipelineExecutor($stepResolverRegistry))->execute($manifest);

コードサンプル — 本番

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$executor = new PipelineExecutor($stepResolverRegistry);

// Invoke from an async job worker, not a request handler.
$result = $executor->execute($manifest, ['customerName' => 'Acme']);

if ($result->status !== \NextPDF\Pro\OutputPipeline\PipelineStatus::Completed) {
    foreach ($result->stepResults as $stepResult) {
        // Inspect per-step error detail.
    }
}

エッジケースと落とし穴

パイプラインは、ジョブシステムを通じて非同期に実行されることを意図しています。インラインで実行すると、パイプライン全体の所要時間にわたって呼び出し元がブロックされます。
リゾルバーが登録されていないステップタイプは、（stop-on-error が設定されていない限り）パイプライン全体を中断するのではなく、そのステップを失敗させます。
グローバルタイムアウトはステップ間でチェックされ、ステップの途中ではチェックされません。長時間実行されるステップは、チェックが発火する前に予算を超過する可能性があります。

パフォーマンス

総所要時間は、ステップの所要時間の合計にリトライのオーバーヘッドを加えたものです。グローバルタイムアウトが最悪ケースの実時間に境界を設けます。公表されたスループット値はありません。パイプラインのコストは、含めるステップが支配的です。代表的なマニフェストで測定してください。

セキュリティに関する注意

エグゼキューターは入力ドキュメントと変数をステップリゾルバーに渡します。それらを信頼できないものとして扱い、各リゾルバー内で検証してください。ケーパビリティでゲートされたステップは、ライセンスがない場合にフェイルクローズドになります。エグゼキューターはドキュメントの内容をログに記録しません。

適合性

エグゼキューター自体は、フォーマット適合性に関する処理を一切行いません。適合性は、個々のステップリゾルバー（generate、merge、split、sign、convert）に依存します。執筆時点で RAG コーパスが利用できなかったため、このページは外部の節識別子を一切主張しません。

Enterprise の境界に関する注記

Enterprise は、ゲート対象のステップタイプ（redaction、extraction、OCR オーバーレイ）を振る舞いレベルでアンロックする Pack ケーパビリティを追加します。それらの Pack がなくても、パイプラインはゲートされていないすべてのステップを引き続き実行します。Pack の内部実装はここでは対象外です。

Core のフォールバック/代替手段

Pro がない場合は、NextPDF Core の API を用いて PDF 操作を命令的にオーケストレーションしてください。宣言的なマニフェスト、依存関係の順序付け、リトライは Pro の追加機能です。を参照してください。

公開の境界

このページは、外部から観測可能な振る舞いと、サポートされる公開 API サーフェスのみを記述しています。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットのプレフィックスは対象外です。