NextPDF Gotenberg の概要

概要

NextPDF Gotenberg は、NextPDF と外部の Gotenberg サービスをつなぐ軽量なブリッジです。NextPDF がネイティブにレンダリングできない Office ドキュメントを受け取り、そのドキュメントを HTTP 経由で Gotenberg インスタンスへ送信し、PDF を受け取って、その PDF をアプリケーションへ渡します。以降の後処理は、NextPDF のほかの機能群が引き継ぎます。

このパッケージは小さく、動作が明示的です。レンダラーは組み込まず、LibreOffice を起動せず、ブラウザも実行しません。変換はいずれも、Gotenberg エンドポイントへの 1 回のマルチパート HTTP リクエストとして行われます。そのエンドポイントは利用者側で運用し、設定でブリッジの接続先として指定します。

.docx、.xlsx、.pptx、.odt、.ods、または .odp のソースファイルを NextPDF パイプライン内で PDF として扱いたい場合は、このブリッジを使用します。PDF の生成後に行うすべての処理（署名、PDF/A 変換、ウォーターマーク付与、結合）は、NextPDF 自体または nextpdf/premium パッケージを通じて実行します。

ブリッジが依存するもの

ブリッジには、PHP パッケージ以外の実行時依存関係が 1 つあります。ブリッジから HTTPS 経由で到達できる 稼働中の Gotenberg サービス です。

ブリッジは Gotenberg のインストール、管理、監視を行いません。Gotenberg は利用者自身でデプロイし（アップストリームプロジェクトがコンテナイメージを公開しています）、その可用性、キャパシティ、ネットワーク公開範囲に責任を持ちます。
ブリッジは Gotenberg の LibreOffice 変換ルート と通信します。リクエスト URL は <apiUrl>/forms/libreoffice/convert として組み立てられます。ここで <apiUrl> は、設定するベース URL です。このルートによって、ブリッジがサポートする形式のセットが決まります。
ヘルスプローブは、HTTP HEAD リクエストで <apiUrl>/health にアクセスし、500 未満のステータスをすべて利用可能とみなします。

変換は利用者が運用するサービス内で行われるため、ブリッジの動作は、実行中の Gotenberg のバージョンに依存します。ブリッジは固定された形式のマルチパートリクエストを送信し、ルートパス（/forms/libreoffice/convert）とヘルスパス（/health）だけが、ブリッジが前提とする Gotenberg 側の契約です。デプロイのベースラインについては /integrations/gotenberg/install/ を、サービスのハードニングについては /integrations/gotenberg/security-and-operations/ を参照してください。

サポートされるドキュメント形式

ブリッジは、OfficeFormat 型に列挙されている形式だけを変換します。各形式はファイル拡張子から検出されます（大文字・小文字を区別せず、先頭のドットも許容されます）。その後、各形式は固定の MIME タイプを付けて Gotenberg へ送信されます。

形式	拡張子	Gotenberg へ送信される MIME タイプ
Word（OOXML）	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel（OOXML）	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint（OOXML）	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

このリストがすべてです。このセット以外の拡張子では、ネットワークリクエストが行われる前に ValueError を発生させるため、ブリッジが記述できない変換を試みることはありません。ブリッジは「あらゆる Office ファイル」や「すべてのドキュメント形式」をサポートするとは主張していません。ブリッジがサポートするのは上記の 6 つの形式です。これらが、コードが認識する 6 つであり、テストスイートが実際に検証する 6 つだからです。

レガシーなバイナリ形式（.doc、.xls、.ppt）、リッチテキスト（.rtf）、プレーンテキスト、CSV、および画像形式は、ブリッジが認識するセットには含まれません。Gotenberg 自体の LibreOffice ルートは、より幅広い入力を受け付ける場合があります。ブリッジは意図的に列挙済みのセットへ範囲を絞ることで、形式検出、MIME タイプ、結果のメタデータの一貫性と検証可能性を常に保っています。

変換の流れ

変換は、単一の線形なパスです。どのバイトもプロセスの外へ出る前に、各ステップで検証されます。

設定を検査します。空の API URL の場合は、変換例外で即座に失敗します。
API URL を検証します。HTTPS が必須であり、ホストは名前解決のうえスクリーニングされ、プライベートアドレスや予約済みアドレスを指せないようにします。解決されたアドレスのセットは、後でピン留めするために記録されます。
入力を読み取ります（ファイル変換の場合、トラバーサルを防ぐためにパスがまず正規化されます）。その拡張子が OfficeFormat にマッピングされます。
バイト長を設定された最大値と照合し、ファイル名はトラバーサルシーケンス、スラッシュ、ヌルバイト、制御文字についてスクリーニングされます。
検証と接続の間のギャップを塞ぐため、リクエストの直前にアドレスのセットを再チェックします。
multipart/form-data のボディを構築し、設定されていればベアラートークンを付けて、LibreOffice ルートへ POST します。
レスポンスを解析します。ステータスは 200 でなければならず、Content-Type は application/pdf を含む必要があり、ボディは %PDF シグネチャで始まらなければなりません。これらの条件が満たされた場合にのみ、結果を返します。

ステップ 1〜7 のいずれかで失敗した場合、部分的または未検証の結果は返さず、型付き例外を発生させます。正確な例外とそのトリガーは /integrations/gotenberg/troubleshooting/. に一覧化されています。

返ってくるもの

変換が成功すると、結果オブジェクトが返されます。このオブジェクトは、生の PDF バイト、変換元のソース形式、および任意のレンダリング時間の計測値を保持し、有効性チェック（%PDF で始まる空でないボディ）とバイトサイズのアクセサーを公開します。これらのバイトは通常の PDF ストリームなので、ディスクへ書き込む、クライアントへストリーミングする、追加処理のために NextPDF ドキュメントへ渡す、といった使い方ができます。

ブリッジが担わない範囲

ブリッジは変換と検証を担います。次のことは行いません。

出力の署名、暗号化、線形化、または PDF/A 変換。これらは後処理の責務であり、NextPDF コアまたは nextpdf/premium が扱います。
失敗したリクエストの再試行、作業のキューイング、または結果のキャッシュ。これらはアプリケーションレベルの責務です。 /integrations/gotenberg/production-usage/ では、それらをブリッジの外側のどこに追加すればよいかを示しています。
Gotenberg サービスのライフサイクル管理。デプロイと運用は /integrations/gotenberg/security-and-operations/. で扱っています。

エディションと後処理

OSS コアは、変換された PDF をそのまま書き出せます。変換済みドキュメントへの署名、PDF/A アーカイブプロファイルの生成、またはウォーターマークの付与が必要な場合は、nextpdf/premium パッケージがそれらの機能を追加します。ブリッジ自体はエディションに依存せず、PDF を生成します。その PDF をどう扱うかによって、商用エディションが必要かどうかが決まります。

Pro エディションで利用できる PAdES ベースラインは B-B のみです。長期検証プロファイル（B-T、B-LT、B-LTA）は、Pro エディションに含まれません。また、このブリッジでも提供されません。推測しないでください。このパッケージが存在することを根拠に、タイムスタンプや LTV の機能を備えていると推測しないでください。