コンテンツにスキップ
NextPDF

Cloudflare 開発者ガイド

概要

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

Cloudflare パッケージは、レンダリング処理を Worker 境界へ移します。Worker レンダリング、ローカルフォールバック、API 保護、R2 アーカイブは、それぞれ独立した機能として扱い、障害時の処理も個別に行ってください。

エッジレンダリングサービス、保護されたレンダリングエンドポイント、アーカイブワークフロー、または nextpdf/cloudflare を中心としたローカルフォールバック経路を構築する際は、このガイドを参照してください。

アーキテクチャ境界

「アーキテクチャ境界」という見出しのセクション
レイヤー担当責務ここに含めないもの
アプリケーションエンドポイントアプリケーション呼び出し元の認可、レンダリング要求の正規化、ビジネスポリシーの適用。Worker トークンのコード内保存。
API 保護nextpdf/cloudflare とアプリケーションAPI キー、ペイロードサイズ、プロセス内のレート制限の判定。課金、テナント権限、永続的なクォータの適用。
Cloudflare レンダラーnextpdf/cloudflareHTML と Worker URL の検証、レンダリングペイロードの送信、レスポンスの解析。テンプレートレンダリングやドメインクエリ。
Worker（ワーカー）アプリケーションのデプロイBrowser Rendering の実行、PDF バイト列または構造化された結果の返却。PHP 側のストレージポリシー。
ローカルフォールバックアプリケーションのデプロイWorker が利用できない場合のレンダリング。運用上の障害を隠すサイレントなフォールバック。
R2 アーカイブnextpdf/cloudflarePDF のアップロード、オブジェクトキーの構築、署名付き URL の作成。レビューされていない機密性の高い業務メタデータ。

ランタイムのライフサイクル

「ランタイムのライフサイクル」という見出しのセクション
ステージ動作開発者の対応
設定の生成Worker URL、API トークン、タイムアウト、サイズ制限、フォールバック、ピンの読み込み。シークレットのデプロイ設定内での保管。
要求の保護オプションの ApiProtection による鍵、サイズ、レート制限の検証。コストの高いレンダリング処理前の実行。
レンダラーの呼び出しCloudflareHtmlRenderer による HTML と Worker URL の検証後、JSON の送信。Worker が利用できない場合とレンダリング失敗の個別処理。
レスポンスの解析CloudflareResponseParser::parse() による、バイナリ PDF または構造化された JSON 出力の受け入れ。不正な出力や PDF 以外の出力の拒否。
ローカルフォールバックオプションのローカルレンダラーによる Worker 障害の処理。ホストが対応している場合に限った、ローカルレンダラーのファクトリー注入。
R2 アーカイブR2ArchiveManager による PDF バイト列の保存と署名付き URL の作成。意図的に保存する場合を除く、メタデータ内の機密情報の除外。

推奨されるアプリケーション構成

「推奨されるアプリケーション構成」という見出しのセクション
パス用途
app/Pdf/Cloudflare/*アプリケーション側の CloudflareHtmlRenderer ラッパー。
app/Pdf/Workers/*Worker 要求 DTO とエンドポイント固有ポリシー。
app/Pdf/Archive/*R2 アーカイブのオーケストレーションと保持判断。
app/Pdf/Fallback/*LocalRendererFactoryInterface の実装（フォールバックが許可されている場合）。
tests/Pdf/Cloudflare/*Worker 停止、無効なトークン、ペイロード、アーカイブのテスト。

PHP の API トークンと Worker トークンは分けて管理してください。PHP 側は Worker に対して認証を行います。Worker は、ブラウザー処理を開始する前に、受信した要求を認証する必要があります。

<?php


use NextPDF\Cloudflare\ApiProtection;
use NextPDF\Cloudflare\ApiProtectionConfig;
use NextPDF\Cloudflare\ApiKeyValidator;


$protection = new ApiProtection(
    new ApiProtectionConfig(maxRequestsPerMinute: 30),
    new ApiKeyValidator([$expectedApiKey]),
);


$result = $protection->checkRequest(
    clientId: $clientId,
    payloadSize: strlen($html),
    apiKey: $presentedApiKey,
);


if (!$result->allowed) {
    return new JsonResponse(['error' => $result->denialReason], 429, $result->toHeaders());
}

レンダラーのパターン

「レンダラーのパターン」という見出しのセクション

フレームワークが提供する PSR-18 および PSR-17 の依存関係を使用して、レンダラーを構築します。ローカルフォールバックは明示的な設定として維持し、システムが Worker を使用しなくなったことをオペレーターが把握できるようにしてください。

<?php


use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;


$renderer = new CloudflareHtmlRenderer(
    config: CloudflareRendererConfig::fromArray([
        'worker_url' => getenv('NEXTPDF_CLOUDFLARE_WORKER_URL'),
        'api_token' => getenv('NEXTPDF_CLOUDFLARE_API_TOKEN'),
        'render_timeout' => 30,
        'max_html_size' => 1_000_000,
        'fallback_to_local' => false,
    ]),
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
);


$rendered = $renderer->render($html, widthPt: 595.28);

R2 アーカイブのパターン

「R2 アーカイブのパターン」という見出しのセクション

レンダリングが成功し、ポリシーの承認が得られた後にのみアーカイブしてください。公開 URL と署名付き URL は、別々の判断事項として扱ってください。

<?php


use NextPDF\Cloudflare\R2ArchiveManager;


$upload = $archive->upload(
    pdfData: $rendered->pdfData,
    filename: 'invoice-1234.pdf',
    metadata: [
        'document_type' => 'invoice',
    ],
);


if ($upload->isValid()) {
    $temporaryUrl = $archive->generateSignedUrl($upload->key, 600);
}

保持・アクセスポリシーで明示的に許可されていない限り、顧客名、メールアドレス、請求書の合計金額、規制対象の識別子をオブジェクトメタデータに含めないでください。

拡張ポイント

「拡張ポイント」という見出しのセクション
拡張ポイント用途制約
LocalRendererFactoryInterfaceArtisan など、別のレンダラーへのローカルフォールバック。返却オブジェクトでの LocalRendererInterface 実装が必須。
ApiProtectionConfigAPI キー、ペイロードサイズ、レート制限のポリシー。インメモリの制限はプロセスごとに適用されます。
ApiKeyValidatorタイミング攻撃に強い鍵検証と、鍵ローテーションを支援するヘルパー。シークレットのソースコード外での保管。
R2ArchiveConfigバケット、認証情報、パスのプレフィックス、エンドポイント、サイズ制限。認証情報は決してログに記録してはなりません。
PinnedCurlTransportIP および SPKI ピンの適用。cURL 対応ランタイムとレスポンスファクトリーが必須。
CloudflareResponseParserWorker レスポンスの解析。不正な PDF やエラーレスポンスの拒否。

開発ワークフロー

「開発ワークフロー」という見出しのセクション
  1. まず、ローカルのレンダリング経路を構築します。
  2. 代表的な小規模 HTML フィクスチャを使って Worker レンダリングを追加します。
  3. 公開エンドポイントの公開前に、要求の保護を有効にします。
  4. レンダリングとレスポンスのフローが安定してから、R2 アップロードを追加します。
  5. Worker 停止、無効なトークン、過大なペイロード、レート制限、R2 障害の各経路をテストします。
  6. Worker レンダリング、フォールバックレンダリング、アーカイブのアップロード、署名付き URL の作成を識別できるログを追加します。

障害処理

「障害処理」という見出しのセクション
障害処理すべき場所推奨される対応
API キーが欠落している、または無効であるAPI 保護レイヤー。レンダリング処理開始前の拒否。
過大なペイロードAPI 保護、またはレンダラーの検証。Worker を呼び出さない検証失敗の返却。
安全でない Worker URLレンダラーのセキュリティポリシー。ネットワーク I/O 前の設定または要求レベルでの失敗。
Worker が利用できないレンダラー境界。許可されている場合に限った明示的フォールバックの使用。それ以外の場合は明示的な失敗。
R2 アップロードの失敗アーカイブ境界。アーカイブが任意の場合は PDF レスポンスの返却。ポリシーでアーカイブが必須の場合は失敗。
ピンのローテーションの失敗デプロイと運用。バックアップ用ピンとロールバック計画を用意したローテーション。

安全なデフォルト

「安全なデフォルト」という見出しのセクション
対象デフォルト上書きするタイミング
フォールバック設定のデフォルトで有効。ローカルレンダリングがデプロイの分離を損なう場合の無効化。
HTML の最大サイズ5,000,000 バイト。公開エンドポイントでの縮小。
署名付き URL の TTL3600 秒。機密性の高い PDF での短縮。
ピンのセット空。ローテーション計画とバックアップ用ピンがある場合に限ったピンの追加。
API キーの要否保護設定のデフォルトで有効。非公開で認証済みの内部呼び出しの場合に限った無効化。

テストのチェックリスト

「テストのチェックリスト」という見出しのセクション
  • レンダラーのテストでは、正常な HTML、過大な HTML、無効な Worker URL、Worker のエラーレスポンスを対象とします。
  • API 保護のテストでは、鍵の欠落、無効な鍵、過大なペイロード、レート制限の超過を対象とします。
  • R2 のテストでは、アップロードの成功、過大なアップロード、HTTP ステータスの失敗、無効なバケット、署名付き URL の生成を対象とします。
  • フォールバックのテストでは、ローカルレンダラーの経路が明示的で観測可能であることを確認します。
  • トランスポートのテストでは、固定された IP、公開鍵ピン、タイムアウト、ポリシーによって無効化されたリダイレクトを対象とします。
  • オブザーバビリティのテストでは、レンダリング、フォールバック、アーカイブ、署名付き URL の作成について、それぞれ個別のログイベントが記録されることを検証します。