Output Pipeline — 詳細リファレンス

概要

このページは、NextPDF\Pro\OutputPipeline の公開サーフェスに関する詳細リファレンスです。マニフェストの構築と検証、トポロジカルな実行順序、リトライとタイムアウトのセマンティクス、resume の挙動、そして fail-closed な pack ケーパビリティゲートを扱います。すべての公開シンボルについて、パラメーター、デフォルト、失敗モードを記載します。まず Output Pipeline のケーパビリティページ を読み、ワークフローのガイダンスを確認してください。

提供状況とライセンス

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

エグゼキューターと 10 種類のステップタイプのうち 7 種類には、機能単位のフラグはありません。残る 3 種類のステップタイプは、追加で Pack ケーパビリティを必要とします。

Step type	Manifest value	Required capability	Pack
Redact	redact	pack.privacy.redact	Privacy Pack
Extract	extract	pack.intelligence.extract	Intelligence Pack
OCR overlay	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

このゲートは実行時に fail-closed で、ステップがそのリゾルバーに到達する前に強制されます。ライセンスのないゲート対象ステップは、SPEC-LIC-001 コードと必要なケーパビリティを伴う Failed のステップ結果を返し、リゾルバーは一切呼び出されません。ケーパビリティリゾルバーが注入されていないパイプラインは、すべてのゲート対象ステップを拒否します。

公開 API サーフェス

composer require nextpdf/pro:^3

nextpdf/premium メタパッケージは nextpdf/pro のコードをインストールします。このモジュールは NextPDF\Pro\OutputPipeline 名前空間の下に存在します。

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	組み込みのリゾルバーレジストリと任意の権利ソースをバインド	PipelineExecutor	宣言なし	null のケーパビリティリゾルバーはすべての pack ゲート対象ステップを拒否
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	ステップをトポロジカル順序で実行し結果を集約	PipelineResult	宣言なし。リゾルバーの失敗は Failed のステップ結果として捕捉	非同期ジョブワーカー内での実行を想定
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	構築時にステップグラフを検証	PipelineManifest	空のステップリスト、重複するステップ ID、未知の依存関係、循環、出力タイプ不整合、resume ステップ欠落で InvalidArgumentException。10 000 ステップ超で OverflowException	すべての検証は実行前に完了
PipelineManifest::topologicalOrder	なし	依存元を依存先より前に並べる	list<PipelineStep>	宣言なし	所与のマニフェストに対して決定的
PipelineManifest::getStep	string $stepId	ステップ ID による線形探索	?PipelineStep	宣言なし	未知の ID には null
PipelineManifest::rootSteps	なし	依存を持たないステップを返す	list<PipelineStep>	宣言なし	root ステップが最初に実行
PipelineManifestBuilder::create	string $manifestId	新しいビルダーを開始	self	宣言なし	コンストラクターは private。これが唯一の入口
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	ステップを追加。null の出力タイプはステップタイプから推論	self	宣言なし	検証は build() に延期
PipelineManifestBuilder::stopOnError	bool $stop = true	最初の失敗で停止する設定	self	宣言なし	デフォルトは true
PipelineManifestBuilder::maxRetries	int $retries	ステップごとのリトライ上限を設定	self	宣言なし	デフォルトは 0（リトライなし）
PipelineManifestBuilder::timeout	int $timeoutMs	グローバルパイプラインタイムアウトを設定	self	宣言なし	0 でタイムアウト無効
PipelineManifestBuilder::resumeFrom	string $stepId	resume ポイントを設定	self	宣言なし	build() 時にそのステップが存在する必要あり
PipelineManifestBuilder::build	なし	検証済みマニフェストを構築	PipelineManifest	PipelineManifest::__construct と同様	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	イミュータブルな実行オプション	PipelineOptions	宣言なし	readonly の値オブジェクト
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	イミュータブルなステップ定義	PipelineStep	宣言なし	直接構築ではすべてのタイプで出力タイプが PDF になる
PipelineStep::isRoot	なし	ステップが依存を持たなければ true	bool	宣言なし	—
PipelineStepType (enum)	—	文字列バックの 10 ケース: generate、merge、split、inspect、compress、sign、convert、およびゲート対象の redact、extract、ocr_overlay	—	—	組み込み操作ごとに 1 ケース
PipelineStepType::requiresPack	なし	Redact、Extract、OcrOverlay で true	bool	宣言なし	その他のケースは false を返す
PipelineStepType::requiredCapability	なし	ゲート対象ケースをケーパビリティコードにマップ	?string	宣言なし	非ゲートケースには null
PipelineStatus (enum)	—	5 ケース: pending、running、completed、failed、cancelled	—	—	パイプラインとステップの結果で共有
PipelineStatus::isTerminal	なし	Completed、Failed、Cancelled で true	bool	宣言なし	Pending と Running は非終端
StepOutputType (enum)	—	3 ケース: pdf、json、metadata	—	—	ビルド時のエッジ検証を駆動
StepOutputType::forStepType	PipelineStepType $stepType	ステップタイプのデフォルト出力タイプ	self	宣言なし	Inspect と Extract は JSON にマップ。その他はすべて PDF
StepOutputType::isCompatibleWith	self $expectedInput	同一タイプ一致または PDF 出力で true	bool	宣言なし	ヘルパー。PDF は汎用入力
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	実行ごとのインメモリコンテキスト	PipelineContext	宣言なし	TTL、有効期限、永続化、バッキングストアなし
PipelineContext::setStepResult / ::getStepResult	string $stepId（set 時は StepResult を追加）	ステップ結果を記録または読み取り	void / ?StepResult	宣言なし	未実行のステップには null
PipelineContext::setStepOutput / ::getStepOutput	string $stepId（set 時は mixed を追加）	中間出力を保存または読み取り	void / mixed	宣言なし	欠落した出力には null
PipelineContext::hasStepResult	string $stepId	ステップが既に実行済みか	bool	宣言なし	resume チェックを支援
PipelineContext::allStepResults	なし	これまでに記録された全結果	array<string, StepResult>	宣言なし	ステップ ID をキーとする
PipelineContext::isResume	なし	あるステップから再開する実行か	bool	宣言なし	—
PipelineResult::isSuccess	なし	全体ステータスが Completed のときのみ true	bool	宣言なし	結果はエグゼキューターが生成
PipelineResult::getStepResult	string $stepId	ID で 1 つのステップ結果を検索	?StepResult	宣言なし	スキップまたは未知のステップには null
PipelineResult::failedSteps	なし	失敗したステップ結果を抽出	list<StepResult>	宣言なし	完全成功時は空リスト
StepResult::isSuccess	なし	ステップステータスが Completed のときのみ true	bool	宣言なし	stepId、type、status、durationMs、error、output を保持
CapabilityResolverInterface::hasCapability	string $capability	1 つのケーパビリティコードに対する肯定的な権利判定	bool	例外を投げてはならない	省略による拒否。未知・失効・未マップのコードには false

エントリーポイントのシグネチャ

final class PipelineExecutor
{
    public function __construct(
        private readonly StepResolverRegistry $registry,
        private readonly ?CapabilityResolverInterface $capabilityResolver = null,
    )

    public function execute(PipelineManifest $manifest, array $variables = []): PipelineResult
}

final class PipelineManifestBuilder
{
    public static function create(string $manifestId): self

    public function addStep(
        string $id,
        PipelineStepType $type,
        array $parameters = [],
        array $dependsOn = [],
        ?StepOutputType $outputType = null,
    ): self

    public function stopOnError(bool $stop = true): self

    public function maxRetries(int $retries): self

    public function timeout(int $timeoutMs): self

    public function resumeFrom(string $stepId): self

    public function build(): PipelineManifest
}

interface CapabilityResolverInterface
{
    public function hasCapability(string $capability): bool;
}

挙動コントラクト

マニフェストの検証

検証は PipelineManifest のコンストラクター内で、実行の前に行われます。順序としては、ステップリストは空であってはならず、ステップ数は 10 000 に制限され、敵対的に深い依存チェーンをネイティブなスタック枯渇ではなく捕捉可能な OverflowException に変換します。ステップ ID は一意である必要があり、すべての dependsOn 参照は解決される必要があり、依存グラフは非循環でなければならず、出力タイプは互換でなければならず、宣言された resume ステップは存在しなければなりません。各違反は、具体的なメッセージを伴う InvalidArgumentException を送出します。

出力タイプのチェックは、タイプが PDF 出力にマップされるステップに適用されます。そのようなステップのすべての依存は、それ自体が PDF 出力を生成しなければなりません。JSON を生成するステップタイプ（inspect、extract）への依存エッジは、本リリースではタイプチェックされません。

実行順序、再開、タイムアウト

execute($manifest, $variables) は新しい PipelineContext を構築し、トポロジカル順序を計算して、その順序でステップを逐次実行します。resume ポイントが設定されている場合、指定されたステップに到達するまで先行ステップはスキップされます。スキップされた先行ステップは再実行されず、その出力も復元されません。コンテキストは実行ごとかつインメモリであるため、スキップされた先行ステップの出力を読み取る resume 後のステップは null を観測します。

グローバルタイムアウトは、正の値のとき、各ステップの開始前にステップ間で評価されます。期限切れになるとパイプラインステータスは Failed になり、残りのステップは開始されません。すでに実行中のステップが実行途中で中断されることはないため、1 つの長いステップが予算を超過する可能性があります。

再試行と失敗の捕捉

各ステップは最大で maxRetries + 1 回の試行を受けます。成功した試行は直ちに返ります。失敗した試行 — リゾルバーからの Failed 結果、または送出された Throwable — は、試行回数が残っている限りリトライされ、最終試行の結果が返されます。リゾルバー内で送出された Throwable は、例外メッセージ（メッセージが空の場合は Unknown error）を伴う Failed のステップ結果に降格されます。したがって execute() は常に PipelineResult を返し、リゾルバーの失敗を伝播させることはありません。

登録されたリゾルバーを持たないステップタイプは、明示的なメッセージを伴う Failed のステップ結果を返し、実行は中断されません。stopOnError が true（デフォルト）の場合、実行は最初の失敗したステップで停止し、パイプラインステータスは Failed になります。false の場合、実行は継続し、いずれかのステップが失敗すれば最終ステータスは Failed、そうでなければ Completed になります。

パック機能ゲート

リゾルバーのディスパッチの前に、すべての pack ゲート対象ステップ（Redact、Extract、OcrOverlay）が、注入された CapabilityResolverInterface に対してチェックされます。このゲートは fail-closed です。リゾルバーの欠落、false の応答、未マップのケーパビリティコードは、いずれもステップを拒否します。拒否は、SPEC-LIC-001 コード、ステップタイプ、必要なケーパビリティをエラーに保持する Failed のステップ結果を生成します。ゲートによる拒否はリトライ試行を消費せず、所要時間 0.0 を報告します。リゾルバーの実装は、肯定的に保持された権利に対してのみ true を返し、例外を投げてはなりません。

結果の集約

PipelineResult は、マニフェスト ID、全体ステータス、実行順のステップごとの結果、ミリ秒単位の合計所要時間、そしてステップの総数・完了数・失敗数を報告します。stepsTotal はマニフェスト内のすべてのステップを数え、resume によってスキップされたステップや停止後に到達しなかったステップも含みます。stepsCompleted と stepsFailed は実行されたステップのみを数えます。

エッジケースと失敗モード

• エグゼキューターは、ジョブワーカー内での非同期実行を想定して設計されています。インライン利用では、パイプライン全体の所要時間にわたって呼び出し元がブロックされます。
• グローバルタイムアウトはステップ間のチェックです。単一の長いステップが予算を超過する可能性があり、実行途中でステップが中断されることはありません。
• resume は同一実行内でのみステップをスキップします。いかなるストアからも出力を復元することはなく、キャッシュされた出力を伴う実行間 resume は実装されていません。
• PipelineStep を直接構築すると、すべてのステップタイプで出力タイプが PDF にデフォルト設定されます。ビルダーを使うか、出力タイプを明示的に渡して、inspect と extract のステップが JSON 出力を宣言し、エッジ検証が意味を保つようにしてください。
• メッセージが空のリゾルバー例外は、ステップ結果内で Unknown error に正規化されます。
• ゲートまたはリゾルバー欠落によって生成された Failed のステップ結果は、所要時間 0.0 を報告します。
• PipelineResult::getStepResult() は、未知の ID に対しても、resume や停止によってスキップされたステップに対しても null を返します。stepsTotal と結果リストの長さを比較して区別してください。
• このモジュールは暗号操作を一切行わず、FIPS 固有の挙動も定義しません。sign ステップの FIPS 姿勢は、パイプラインではなく署名モジュールによって管理されます。

適合性

パイプラインは、それ自体ではフォーマット適合性に関する処理を一切行いません。生成された各成果物の適合性は、実行中のステップの背後にあるモジュール — 署名、最適化、変換など — が所有し、それらのモジュールのリファレンスページに記載されています。このページは外部の節識別子を一切主張せず、すべての記述は製品ソースに基づいています。NextPDF はいかなる認証も主張しません。

開発上の注意

• モジュールソースは @since 2.2.0 を持ちます。このリファレンスは nextpdf/pro 3.1.0 で出荷されたサーフェスを記載します。
• すべてのクラスは final であり、マニフェスト、オプション、ステップ、結果の各タイプは readonly の値オブジェクトです。ミューテートせず、新しいインスタンスを構築してください。
• StepResolverInterface と StepResolverRegistry は @internal です。ステップリゾルバーは組み込みのみで、ユーザー定義のカスタムステップハンドラーは本リリースではサポートされません。
• CapabilityResolverInterface は公開された権利のシームです。実装は省略による拒否でなければならず、デフォルトで許可してはなりません。
• この PHP エグゼキューターは、マニフェスト検証と逐次実行のパスです。本番デプロイメントでは、並列オーケストレーションのためにサイドカー経由でディスパッチする場合があります。PHP パス上のケーパビリティゲートは、いずれの場合でも独立して fail-closed です。
• 内部メカニズムの詳細はソースリポジトリの内部ドキュメントに留められ、本マニュアルの範囲外です。

公開の境界

このページは、外部から観測可能な挙動とサポートされる公開 API サーフェスのみを記載します。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットの接頭辞は範囲外です。

関連項目

• Output Pipeline — ワークフローガイダンスのケーパビリティページ。
• Output Pipeline — NextPDF Enterprise 詳細リファレンス — マニフェスト間のバッチオーケストレーション。
• Document — 詳細リファレンス
• Accelerator — 詳細リファレンス