NextPDF Cloudflare エッジレンダリングブリッジ — 概要

概要

nextpdf/cloudflare はエッジレンダリングブリッジです。PHP アプリケーションが HTML を保持し、Cloudflare Worker がヘッドレスブラウザを保持します。ブリッジは HTTPS 経由で HTML を Worker に送信し、レンダリング済みの PDF バイト列を受け取ります。PHP プロセス内でヘッドレスブラウザが動作することはなく、ブリッジが管理するパス上ではローカルの Chromium バイナリも必要ありません。

このパッケージは NextPDF エコシステムに属し、nextpdf/core^3.0 に依存します。ワイヤープロトコルを扱うコードであり、JSON リクエストを構築し、入力と宛先を検証し、PSR-18 クライアントを通じてリクエストを送信し、レスポンスを型付きの結果オブジェクトにパースします。Worker の実装そのものは、このパッケージには含まれません。このブリッジは、あなたがデプロイした Worker と通信します。

信頼境界

このブリッジを特徴づけるのは、HTML がネットワーク境界を越え、あなたが直接制御していないブラウザエンジンに到達する点です。パッケージ内のすべてのセキュリティ制御は、この境界があるからこそ設けられています。

HTML は、PHP プロセスを離れる前に検証されます（CloudflareSecurityPolicy::validate()）。
宛先 URL は、リクエストが送信される前に検証され（CloudflareSecurityPolicy::validateWorkerUrl()）、time-of-check/time-of-use の隙を塞ぐためにリクエスト時に再検証されます（assertPinsStillValid()）。
トランスポートは、解決済みの IP セットとサーバー証明書の公開鍵をピン留めできます（Transport\PinnedCurlTransport）。

このブリッジを本番運用向けに評価している場合は、/integrations/cloudflare/quickstart/ を読む前に、/integrations/cloudflare/security-and-operations/ を読んでください。セキュリティモデルはアドオンではありません。それこそが、このパッケージが現在の形をとっている理由です。

できること

機能	担当クラス
Cloudflare Worker 経由での HTML から PDF へのレンダリング	`CloudflareHtmlRenderer::render()`
到達性プローブ（HTTP `HEAD`）	`CloudflareHtmlRenderer::isAvailable()`
ベンダー非依存のトランスポート	PSR-18 `ClientInterface` の注入
入力のハードニング（サイズ、base64 爆弾、meta-refresh）	`CloudflareSecurityPolicy::validate()`
SSRF/DNS リバインディング防御	`CloudflareSecurityPolicy::validateWorkerUrl()` + `assertPinsStillValid()`
TLS 公開鍵ピン留め、cURL 層の DNS ピン留め	`Transport\PinnedCurlTransport`
Worker に到達できない場合のローカル Chrome フォールバック	`Contract\LocalRendererFactoryInterface`
バイナリおよび JSON（base64）レスポンスのパース	`CloudflareResponseParser`
エッジテレメトリ（レンダリング時間、エッジロケーション、コンテンツの高さ）	`CloudflareRenderResult`
R2 バケットからのカスタムフォント	`CloudflareRenderPayload`（`r2FontBucket`、`fontFiles`）
API 保護レイヤー（鍵認証、ペイロードサイズ、レート制限）	`ApiProtection`
S3 互換 API 経由での R2 への PDF アーカイブ	`R2ArchiveManager`

各行は NextPDF\Cloudflare 名前空間内のクラスに対応します。各行の内容は仕様書ではなく、そのクラスの挙動とテストに照らして検証されています。

行わないこと

ブラウザは起動しません。それを行うのは Worker です。
あなたの Worker のデプロイや設定は行いません。そのアーティファクトはあなたが所有します。
PDF への署名は行いません。署名は nextpdf/core または商用エディションが担当します。署名が必要な場合は、まずレンダリングを行い、その後で返されたバイト列をエンジンで署名します。NextPDF Pro は PAdES B-B 署名を提供します。長期検証（LTV）プロファイルは Enterprise の機能です。
Cloudflare プラットフォームのキャパシティや制限については何も主張しません。このドキュメントで述べるサイズおよび時間の制限は、このパッケージが自身の設定で適用するものだけです（/integrations/cloudflare/configuration/ を参照）。

2 つのセキュリティポリシー

ブリッジには、明確に区別された 2 つの相補的なポリシーがあります。レビューで最もよく見られる誤りは、両者を混同することです。それぞれを以下に示します。

HTML セキュリティポリシー（HtmlSecurityPolicyInterface、デフォルトは NextPDF\Html\DefaultHtmlSecurityPolicy、nextpdf/core が提供）。パース層におけるコンテンツフィルタリングであり、コンテンツが Worker に届く前に適用されます。getHtmlSecurityPolicy() で取得できます。
Cloudflare セキュリティポリシー（CloudflareSecurityPolicy、静的）。トランスポート層の関心事を扱います。具体的には、入力サイズ、base64 解凍爆弾の検出、meta-refresh のブロック、HTTPS の強制、そして Worker URL に対する SSRF/DNS リバインディング防御です。

レンダラー自身の docblock でも、この分離は明記されています。本番運用のレビュー担当者が両方の名前を 1 画面で確認できる必要があるため、このページでも改めて記載しています。

エッジレンダリングモデル

1 回の render() 呼び出しで、次の観測可能なシーケンスが実行されます。このシーケンスは CloudflareHtmlRenderer::render() から直接読み取られています。

設定の完全性チェック（workerUrl と apiToken が空でないこと）。失敗した場合、ブリッジはローカルレンダラーにフォールバックするか、CloudflareNotAvailableException をスローします。
設定された最大サイズ、base64 URI の上限、および meta-refresh の禁止に照らした HTML の検証。
Worker URL の検証。ホストを解決し、検証済みの IP セットを返します。
ペイロードの構築（CloudflareRenderPayload）。
利用時点で、ホストの DNS 応答がステップ 3 以降変化していないことを再チェック。
HTTP POST を送信します。IP セットまたは SPKI ピンセットが存在し、PSR-17 ResponseFactory が提供されている場合はピン留めされた cURL トランスポート経由で、それ以外の場合は注入された PSR-18 クライアント経由です。
レスポンスは CloudflareRenderResult へパースされます。

CloudflareRenderException 以外のあらゆるスロー可能なものは、フォールバックパスを起動します。CloudflareRenderException（HTTP エラー、または Worker からの不正な形式のレスポンス）は、そのまま再スローされます。これは到達性の失敗ではなく Worker 側の失敗であるため、フォールバックは行われません。