コンテンツにスキップ
NextPDF

NextPDF Gotenberg のブートと探索

概要

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

このブリッジには、独自の自動探索メカニズムはありません。明示的なコンストラクター注入によって構築する、単純なサービスです。つまり、設定値オブジェクトに加えて PSR HTTP コラボレーターを渡します。このパッケージは、サービスプロバイダー、バンドル、コンテナ拡張を同梱しておらず、環境変数を自身で読み取ることもありません。ここでいう「探索」とは、ホストフレームワークがコラボレーターをどのように提供するかを指します。これはフレームワークの役割であり、このパッケージの役割ではありません。

ブリッジが探索される仕組み

「ブリッジが探索される仕組み」という見出しのセクション

これは自動的には探索されません。利用側が明示的に構築します。 GotenbergBridge は 4 つの引数を必須とし、3 つの省略可能な引数を受け付けます。

  • 必須: GotenbergConfig、PSR-18 クライアント、PSR-17 リクエストファクトリー、PSR-17 ストリームファクトリー。
  • 省略可能: PSR-3 ロガー、HTML セキュリティポリシー（既定では NextPDF コアの既定ポリシー）、PSR-17 レスポンスファクトリー。

レスポンスファクトリーは、cURL ピン留めトランスポートを有効化するためのスイッチです。これを提供し、ピン留めの対象（解決されたアドレス、または設定済みの SPKI ピン）がある場合、ブリッジはピン留めトランスポートを使用します。これを省略すると、注入された PSR-18 クライアントが常に使用されます。完全な引数の契約は、/integrations/gotenberg/configuration/. にあります。

ブートシーケンス

「ブートシーケンス」という見出しのセクション

登録のステップはありません。ライフサイクルは次のとおりです。

  1. ホストが PSR-18 クライアントと PSR-17 ファクトリーを解決します。これはホストのコンテナが担う処理であり、パッケージは行いません。
  2. アプリケーションは、設定ソースから GotenbergConfig を構築します。 GotenbergConfig::fromArray() は snake_case の配列を受け付け、不正な値はデフォルトに置き換えて許容します。ブートパスでソースを検証してください。これにより、URL の欠落は変換ごとではなくブート時に失敗します。
  3. アプリケーションは、設定とコラボレーターを使って GotenbergBridge を構築します。
  4. 最初の変換呼び出しで、URL の検証、SSRF とファイル名のスクリーニング、およびリクエストが実行されます。構築時には処理は行われず、ブリッジは呼び出されるまで何もしません。

コンテナのバインディング

「コンテナのバインディング」という見出しのセクション

このパッケージは、コンテナのバインディングを同梱していません。ブリッジを注入可能にするには、ホストアプリケーションのコンテナに次のように登録します。

  • 設定ソースから GotenbergConfig をバインドします。
  • PSR-18 クライアントと PSR-17 ファクトリーを、選択した実装にバインドします。
  • 上記を受け取るサービスとして GotenbergBridge をバインドします。

フレームワークネイティブの自動配線、設定の公開、サービスプロバイダーやバンドルの登録は、ここではなく、専用のフレームワーク統合パッケージに存在します。このパッケージは、意図的にフレームワーク非依存の設計を維持しています。PSR インターフェースのみに依存するため、どのコンテナ配下でも動作します。

設定の解決順序

「設定の解決順序」という見出しのセクション

このパッケージは、自身で設定を読み取ることはありません。解決順序は、アプリケーションが GotenbergConfig::fromArray() またはコンストラクターを呼び出す前に実装した内容に依存します。一般的な順序は、環境変数、公開された設定ファイル、コードのデフォルトです。その順序は、このパッケージの契約ではなく、アプリケーションの契約です。このパッケージが定義するのは、fromArray() に渡された配列で省略された各フィールドの デフォルト値 です。すなわち、空の API URL、30 秒のタイムアウト、50 MiB のサイズ上限、空の API キー、空のピンリストです。

診断

「診断」という見出しのセクション

2 つの組み込みシグナルで配線を確認できます。

  • isAvailable() は、ネットワーク通信を行わずに URL を検証したうえで、<apiUrl>/health に HEAD リクエストを送信し、ステータスが 500 未満のときに利用可能と報告します。どの失敗でも、例外をスローするのではなく false を返します。レディネスチェックから呼び出してください。
  • 正常であることが分かっている小さなドキュメントを使ったスモーク変換により、パス全体を端から端まで確認できます。これには、<apiUrl>/forms/libreoffice/convert へのマルチパートリクエストとレスポンスの検証が含まれます。

関連項目

「関連項目」という見出しのセクション
  • /integrations/gotenberg/integration/ — サービスを通じて NextPDF パイプラインを駆動する。
  • /integrations/gotenberg/install/ — パッケージとサービスのインストール。
  • /integrations/gotenberg/configuration/ — コンストラクターと設定の完全な契約。
  • /integrations/gotenberg/overview/ — 変換フローと依存関係モデル。