コンテンツにスキップ
NextPDF
getnextpdf.com

Enterprise エディション

Output Pipeline — 詳細リファレンス

概要

「概要」という見出しのセクション

NextPDF\Enterprise\OutputPipeline は、多数の Pro パイプラインマニフェストを 1 つのバッチとして実行します。BatchPipelineOrchestrator は、Pro の PipelineExecutor をバッチ調整でラップします。すなわち、バッチサイズに対する有界リソースガード、任意のグローバルバッチタイムアウト、マニフェストごとの変数注入、および集計です。任意のバッチ終端コンプライアンスチェックは、完了したすべての出力を Enterprise のコンプライアンスゲートウェイを通じて再検証し、フェイルクローズします。各実行は、マニフェストごとの結果、完了数と失敗数、タイミング、および任意のコンプライアンスレポートを含む BatchPipelineResult を返します。

提供状況とライセンス

「提供状況とライセンス」という見出しのセクション

この機能は NextPDF Enterprise（nextpdf/enterprise）に同梱されており、Enterprise ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントがないデプロイメントでは、この機能のクラスは読み込まれません。エディションを比較してライセンスを取得。

ティア出力パイプラインサーフェス
Core出力パイプラインサーフェスなし。
Pro単一マニフェストパイプライン（機能 pro.output.pipeline）。
Enterpriseバッチオーケストレーション、バッチサイズ上限、バッチタイムアウト、コンプライアンスハンドオフ。

Enterprise のバッチサーフェスには、機能ごとの個別の機能コードはありません。パッケージの境界がこれをゲートします。Pro の単一マニフェスト機能 pro.output.pipeline は前提条件であり、ゲートではありません。Pro ライセンス単独では、このバッチサーフェスではなく、基盤となる単一マニフェストパイプラインのみがアンロックされます。

Terminal window
composer require nextpdf/enterprise:^3

パブリック API サーフェス

「パブリック API サーフェス」という見出しのセクション
シンボルパラメータデフォルトの挙動戻り値スロー/失敗条件備考
BatchPipelineOrchestrator::__construct()PipelineExecutor $executor, BatchPipelineConfig $config, ?ComplianceGateway $complianceGateway, ComplianceProfile $complianceProfileデフォルト構成。ゲートウェイなし。プロファイル ComplianceProfile::PdfA4—なしコンプライアンスチェックを有効にする場合はゲートウェイを注入。注入しない場合、チェック対象の全マニフェストが失敗として報告される。
BatchPipelineOrchestrator::executeBatch()list<PipelineManifest> $manifests, array<string, array<string, mixed>> $variablesMap = []マニフェストを送信順に実行。変数はマニフェスト ID で解決。BatchPipelineResultバッチが 10,000 マニフェストを超えると OverflowException。コンプライアンスチェック有効時はゲートウェイの例外（エッジケース参照）リゾルバの Throwable は決して外部に伝播しない。Pro エグゼキューターがそれらを失敗したステップ結果に格下げする。
BatchPipelineConfig::__construct()int $maxConcurrency = 4, int $timeoutMs = 0, bool $complianceCheckOnComplete = false同時実行数 4。タイムアウトなし。コンプライアンスチェックなし。—なしreadonly の値オブジェクト。timeoutMs = 0 はバッチタイムアウトを無効化。
BatchPipelineResult::__construct()list<PipelineResult> $results, int $totalManifests, int $completedCount, int $failedCount, float $durationMs, ?array $complianceReport = nullマニフェストごとの PipelineResult 値の集計。—なしreadonly。チェックが実行されない限り complianceReport は null のまま。
BatchPipelineResult::allSucceeded()—failedCount === 0 を判定。boolなし失敗ゼロでタイムアウト切り詰めされたバッチでも true を返す。エッジケース参照。
BatchPipelineResult::successRate()—completedCount / totalManifestsfloatなし空のバッチでは 1.0 を返す。
BatchPipelineResult::hasComplianceReport()—complianceReport !== null を判定。boolなし—
public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}


public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult
public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

挙動コントラクト

「挙動コントラクト」という見出しのセクション

executeBatch() は、まずバッチサイズを 10,000 マニフェストの上限に照らして検証します。上限を超えるバッチは、いずれのマニフェストも実行される前に OverflowException を発生させます。黙って劣化するものはありません。

続いてマニフェストは、Pro の PipelineExecutor を介して送信順に実行されます。各マニフェストは、$variablesMap 内でその ID をキーとする変数エントリを受け取ります。エントリのないマニフェストは空の変数マップを受け取ります。マニフェストは、その PipelineResult のステータスが Completed のときに完了としてカウントされ、それ以外の終端ステータスは失敗としてカウントされます。リゾルバの例外は外部に伝播しません。Pro エグゼキューターはすべてのリゾルバの Throwable を失敗したステップ結果に変換するため、executeBatch() は、ステップエラーでバッチの途中で中断するのではなく、常に結果を集計します。

timeoutMs がゼロより大きい場合、各マニフェストの開始前に経過時間がチェックされます。予算が使い果たされると、残りのマニフェストはスキップされます。それらは PipelineResult を生成せず、完了にも失敗にもカウントされません。totalManifests は常に送信された数を報告します。

complianceCheckOnComplete が有効な場合、オーケストレーターは、完了したすべてのマニフェストの最終 PDF を、注入された ComplianceGateway を通じて構成済みの ComplianceProfile に照らして検証します。このチェックはフェイルクローズします。

  • ゲートウェイが注入されていない場合。コンプライアンスが一度も検証されていないため、チェック対象の全マニフェストが失敗として報告される。
  • マニフェストのステップ出力から PDF 出力を解決できない場合。失敗。
  • ゲートウェイが結果を返さない場合（オプションモードでのサイドカー利用不可）。失敗。肯定的な結果がないことは合格ではない。
  • ゲートウェイが不適合を報告した場合。失敗。

最終 PDF は、完了したマニフェストのステップ出力を最後のステップから順にスキャンし、%PDF ヘッダーで始まる直接の文字列値を探すことで解決されます。ステップ出力が PDF バイト文字列をサブ配列内にネストすることはありません。直接の出力値のみが検査されます。完了しなかったマニフェストは、チェックされずにスキップされます。

コンプライアンスレポートは、profile、checked、passed、failed、failures のキーを持つ配列です。各失敗エントリは manifestId と reason を保持します。レポートは BatchPipelineResult::$complianceReport に付加され、hasComplianceReport() を介して到達できます。

コンプライアンスハンドオフは再検証の補助であり、認可制御ではありません。検出結果を報告するのみです。

エッジケースと障害モード

「エッジケースと障害モード」という見出しのセクション
  • 10,000 を超えるマニフェスト。いかなる実行も開始される前に OverflowException。
  • timeoutMs = 0 はバッチタイムアウトなしを意味します。本番環境では有限の値を設定してください。
  • タイムアウトによる切り詰め。スキップされたマニフェストはいずれのカウントにも現れないため、completedCount + failedCount が totalManifests より少なくなることがあります。allSucceeded() は failedCount === 0 のみを判定し、切り詰められたバッチに対して true を返すことがあります。切り詰めを検出するには count($result->results) を totalManifests と比較してください。
  • successRate() は空のバッチ（送信マニフェストがゼロ）に対して 1.0 を返します。
  • マニフェスト ID はバッチレベルで重複排除されません。ID を共有する 2 つのマニフェストは、どちらも実行され、同じ変数エントリを解決します。
  • 構造的なマニフェストエラー（空のステップリスト、重複するステップ ID、不明な依存関係、依存関係の循環、出力タイプの不一致、再開ステップの欠落）は、executeBatch() が呼び出される前に、マニフェストの構築時に InvalidArgumentException を発生させます。
  • コンプライアンスチェックが有効な場合、ComplianceGateway::validate() は ComplianceSidecarUnavailableException（必須モードでサイドカーが利用不可）または InvalidArgumentException（プロファイルのツールに対してバリデーターが登録されていない）をスローすることがあります。いずれの例外も、実行後、結果が構築される前に executeBatch() から伝播するため、マニフェストごとの結果は呼び出し元に失われます。オプションモードでは、ゲートウェイは代わりに null を返し、マニフェストはコンプライアンス失敗として記録されます。
  • パイプライン内のコンプライアンスハンドオフステップは、上流のステップ出力に認識可能な PDF バイトが含まれていない場合に失敗します。黙って合格することはありません。
  • このモジュールは暗号操作を一切実行しません。FIPS モードは適用されません。

適合性

「適合性」という見出しのセクション

このモジュールについて、標準への適合性は主張しません。これはオーケストレーションレイヤーです。任意のコンプライアンスチェックは、Enterprise のコンプライアンスゲートウェイとその外部バリデーターに委ねられ、それらは独自の参照を保持します。デフォルトのプロファイルは ComplianceProfile::PdfA4 です。その他のゲートウェイプロファイルは、さらなる PDF/A、PDF/UA、および PAdES ターゲットをカバーします。

コンプライアンスレポートは、選択されたプロファイルに対するバリデーターの検出結果を記述します。ドキュメントを認証したり、規制上の十分性を保証したり、法的助言を構成したりすることはありません。出力がお客様の義務を満たすかどうかの判断は、お客様の責任です。

開発ノート

「開発ノート」という見出しのセクション
  • 本番環境のデプロイメントでは、並列ワーカーのディスパッチとバックプレッシャーは別個の実行サイドカーが処理します。PHP オーケストレーターは、バッチの調整とコンプライアンスハンドオフのロジックを提供し、リクエストハンドラーから直接ではなくジョブワーカーから呼び出されます。
  • PHP のフォールバックパスは、マニフェストを逐次実行します。maxConcurrency は、サイドカー駆動のデプロイメントにおける同時ワーカーコールバックを制限します。PHP ワーカープールに対する相対的なサイジングは、オペレーターの責任です。
  • パイプライン内のコンプライアンスハンドオフステップのリゾルバは、inspect タイプのステップ用に登録された内部タイプです。それ用のパイプラインステップを直接構築するのではなく、BatchPipelineConfig を通じてバッチ終端の検証を有効にしてください。
  • PipelineManifest インスタンスは早期に構築してください。それらの構造的検証はコンストラクターで実行されるため、無効なグラフは早期に失敗し、バッチ予算を消費することはありません。

公開の境界

「公開の境界」という見出しのセクション

このページは、外部から観測可能な挙動とサポートされているパブリック API サーフェスのみを文書化します。内部名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、およびチケットのプレフィックスは対象外です。

関連項目

「関連項目」という見出しのセクション