本番環境での NextPDF Gotenberg

概要

このブリッジは、検証処理を伴う単一の同期 HTTP ラウンドトリップです。リトライ、キューイング、キャッシュ、レート制限は行いません。これらの処理は、ブリッジの外側にあるアプリケーション側の責務です。このページでは、それぞれをどこに配置すべきか、ブリッジが何を保証するかを示し、残りを正しく構築できるようにします。

すべての変換は、自分で運用していてもプロセス内では制御できないサービスへのリモート呼び出しとして扱ってください。そのレイテンシと障害を前提に設計してください。

設定とシークレットの取得

GotenbergConfig は API URL を保持し、認証が有効な場合はベアラートークンも保持します。トークンフィールドには #[\SensitiveParameter] が付与されているため、スタックトレースでは伏せられます。ただし、それがどこから供給されるかは引き続き利用者の責任です。

トークンは、プロセス起動時にシークレットマネージャーまたは注入された環境値から取得してください。トークンをコミットしたり、イメージに同梱される設定ファイルへ置いたりしないでください。
設定は、変換ごとではなく、リクエストスコープごと、またはワーカーごとに一度だけ構築してください。設定はイミュータブルで、保持コストもわずかです。
GotenbergConfig::fromArray() は設計上、不正な入力を許容します。つまり、黙ってデフォルト値で置き換えます。本番環境では、fromArray() を呼び出す前に、ソース配列を自分で検証してください。そうすれば、URL の欠落は、後で変換ごとに発生する Invalid Gotenberg configuration: apiUrl is empty 例外ではなく、ブートパスでの設定エラーとして表面化します。

タイムアウト

timeout（秒単位、デフォルトは 30）は、cURL 固定トランスポートによって適用される厳格な転送タイムアウトです。LibreOffice を介した Office 変換は瞬時には完了しません。大きいドキュメントや複雑なドキュメントほど時間がかかります。タイムアウトは、実際のドキュメントで測定した変換レイテンシをもとに、余裕を持たせて設定してください。上流のゲートウェイや PHP の max_execution_time よりも小さく保ってください。そうすれば、プロセスが強制終了される前にブリッジが先にタイムアウトし、型付き例外を受け取れます。

注入された PSR-18 クライアントパス（responseFactory が注入されていない場合、またはピンのない素の IP URL の場合）に依存しているときは、ブリッジはそのクライアントに timeout 値を適用しません。PSR-18 クライアント側にもタイムアウトを設定し、どちらのトランスポートにも上限が課されるようにしてください。

リトライ

ブリッジは呼び出しごとに正確に 1 回だけリクエストを実行し、リトライは一切行いません。リトライロジックは呼び出し側に追加し、安全に実装してください。

リトライは、トランスポートレベルの障害（原因が PSR-18 クライアント例外である GotenbergConvertException）と、冪等なサーバーエラー（HTTP 502、503、504）の場合に限ってください。すべての GotenbergConvertException を無差別にリトライしないでください。400 系のレスポンスは通常、入力が誤っていることを意味し、リトライしても同じように失敗します。
上限付きの指数バックオフをジッター付きで使用してください。負荷のかかった変換サービスは 503 を返します。これを連打すると、障害をさらに悪化させます。
総試行回数と総実時間に上限を設けてください。変換はもともと遅いため、上限のないリトライはテールレイテンシを何倍にも増やします。
再検証は自動で行われます。リトライされた各呼び出しでは URL 検証とアドレスの再チェックが再実行されるため、リトライによって SSRF ガードを誤って回避することはできません。

並行処理とキャパシティ

各変換は、リクエスト中ずっと、Gotenberg 側で 1 つの接続と 1 つの LibreOffice ワーカーを占有します。ブリッジ自体はステートレスで、多数のワーカーから並行して安全に使用できます。ただし、Gotenberg サービスの変換キャパシティには限りがあります。

処理中の変換数を、利用者側（キュー、セマフォ、またはワーカープール）で、Gotenberg が持続的に処理できるキャパシティに合わせて制限してください。このサイジングは、このパッケージではなく Gotenberg デプロイメントの特性で決まります。詳しくは /integrations/gotenberg/security-and-operations/. を参照してください。
入力サイズの上限（maxFileSize、デフォルトは 50 MiB）は、ブリッジに組み込まれた唯一のリソース上限です。これはリクエストが送信される前にプロセス内で適用されるため、サイズ超過のファイルがサービスキャパシティを消費することは決してありません。実際のドキュメントに必要な値に合わせて、上限を下げてください。小さい上限は、大きい上限よりも低コストなサービス拒否対策になります。
プロセス内キャッシュはありません。同じドキュメントを繰り返し変換する場合は、入力のコンテンツハッシュをキーにして、生成された PDF をアプリケーション側でキャッシュしてください。

可観測性

PSR-3 ロガーを注入すると、変換リクエストごとに debug エントリが得られます。このエントリには、リクエスト URL、ファイル名、検出されたフォーマット、リクエストのコンテンツ長が含まれます。ファイルの内容やベアラートークンは 含みません。

このシグナルをメトリクスとして扱える形にしてください。フォーマットと結果ごとに変換数をカウントし、各 convertFile() / convertString() 呼び出しの前後で実時間を測り、レイテンシヒストグラムとして記録してください。ブリッジ自体はメトリクスを発行しません。
結果オブジェクトは renderTimeMs フィールドを公開しますが、統合側で計測して設定しない限り 0.0 のままです。ブリッジは Gotenberg のレスポンスからこの値を設定しません。数値が必要な場合は、自分で呼び出し時間を計測してください。
例外は型とともにログ出力してください。例外の型は、何が失敗したかを示す主要なシグナルです。カタログは /integrations/gotenberg/troubleshooting/. にあります。
isAvailable() は、変換のたびに呼ぶのではなく、レディネスエンドポイントまたはヘルスエンドポイントからプローブしてください。これは /health への HEAD です。変換のたびに実行すると、利点のないままサービスへのリクエストレートが 2 倍になります。

障害処理コントラクト

ブリッジは障害を型付き例外として表面化させ、不完全な結果や未検証の結果を返すことは決してありません。関連する保証は次のとおりです。

200 以外のステータス、application/pdf を含まない Content-Type、または %PDF で始まらないボディは、それぞれ GotenbergConvertException を発生させます。結果オブジェクトは、3 つのチェックすべてに合格した場合にのみ返されます。
PSR-18 クライアントの障害（ネットワーク障害やタイムアウトを含む）は、元の例外を原因として保持し、クライアントのコードを例外コードとして持つ GotenbergConvertException にラップされます。
検証の失敗（HTTPS 以外の URL、private/reserved アドレス、サイズ超過の入力、安全でないファイル名）は、ネットワーク通信が発生する前に RuntimeException を発生させます。
認識できないファイル拡張子は、ネットワーク通信が発生する前に ValueError を発生させます。

具体的な型をキャッチしてください。examples/convert-office-to-pdf.php のサンプルプログラムは、網羅的なキャッチ順序を示しています。/integrations/gotenberg/troubleshooting/ では、各トリガーを説明しています。

後処理の境界

ブリッジは PDF を生成したところで停止します。一般的な本番パイプラインは次のとおりです。

このブリッジで Office ドキュメントを変換します。
生成されたバイト列を NextPDF ドキュメントに読み込みます。
後処理を適用します（ページの組み立て、透かしの追加、PDF/A 変換、デジタル署名など）。

ステップ 3 は、ブリッジではなく NextPDF の責務です。署名、PDF/A プロファイル、透かしの追加は nextpdf/premium によって提供されます。変換と後処理を別個のステージとして保ち、変換の失敗と署名の失敗を独立して診断できるようにしてください。

Pro エディションの PAdES サポートは、B-B ベースラインのみです。このエディションは B-T、B-LT、B-LTA を提供しません。また、これらのプロファイルが暗黙に含まれることもありません。対象はこのブリッジを通じたドキュメント変換です。長期検証機能は別個のエディションの関心事であり、このパッケージのスコープ外です。