NextPDF Cloudflare Edge-Rendering-Bridge — Überblick

Auf einen Blick

nextpdf/cloudflare ist eine Edge-Rendering-Bridge. Ihre PHP-Anwendung verwaltet das HTML; der Cloudflare Worker betreibt den Headless-Browser. Die Bridge sendet das HTML über HTTPS an den Worker und erhält die gerenderten PDF-Bytes zurück. In Ihrem PHP-Prozess läuft kein Headless-Browser; für den von der Bridge verantworteten Pfad ist keine lokale Chromium-Binärdatei erforderlich.

Das Paket gehört zum NextPDF-Ökosystem und hängt von nextpdf/core^3.0 ab. Es handelt sich um Wire-Protocol-Code: Das Paket baut eine JSON-Anfrage auf, validiert Eingabe und Ziel, sendet die Anfrage über einen PSR-18-Client und parst die Antwort in ein typisiertes Ergebnisobjekt. Die Worker-Implementierung selbst ist nicht Teil dieses Pakets. Diese Bridge kommuniziert mit einem Worker, den Sie selbst bereitstellen.

Die Vertrauensgrenze

Das bestimmende Merkmal dieser Bridge ist, dass HTML eine Netzwerkgrenze überschreitet und eine Browser-Engine erreicht, die Sie nicht direkt kontrollieren. Jede Sicherheitsmaßnahme im Paket beruht auf dieser Grenze.

• HTML wird validiert, bevor es den PHP-Prozess verlässt (CloudflareSecurityPolicy::validate()).
• Die Ziel-URL wird validiert, bevor die Anfrage gesendet wird (CloudflareSecurityPolicy::validateWorkerUrl()), und zum Anfragezeitpunkt erneut geprüft, um das time-of-check/time-of-use-Fenster zu schließen (assertPinsStillValid()).
• Der Transport kann das aufgelöste IP-Set sowie den öffentlichen Schlüssel des Serverzertifikats pinnen (Transport\PinnedCurlTransport).

Wenn Sie diese Bridge für den Produktivbetrieb evaluieren, lesen Sie zuerst /integrations/cloudflare/security-and-operations/ und danach /integrations/cloudflare/quickstart/. Das Sicherheitsmodell ist keine nachträgliche Ergänzung. Es ist der Grund, warum das Paket so gestaltet ist, wie es ist.

Was es leistet

Fähigkeit	Umgesetzt durch
HTML über einen Cloudflare Worker zu PDF rendern	CloudflareHtmlRenderer::render()
Erreichbarkeitsprüfung (HTTP HEAD)	CloudflareHtmlRenderer::isAvailable()
Anbieterunabhängiger Transport	PSR-18-ClientInterface-Injektion
Eingabehärtung (Größe, Base64-Bombe, Meta-Refresh)	CloudflareSecurityPolicy::validate()
SSRF-/DNS-Rebinding-Abwehr	CloudflareSecurityPolicy::validateWorkerUrl() + assertPinsStillValid()
TLS-Public-Key-Pinning und DNS-Pinning auf cURL-Ebene	Transport\PinnedCurlTransport
Lokaler Chrome-Fallback, wenn der Worker nicht erreichbar ist	Contract\LocalRendererFactoryInterface
Parsen von Binär- und JSON-Antworten (Base64)	CloudflareResponseParser
Edge-Telemetrie (Renderzeit, Edge-Standort, Inhaltshöhe)	CloudflareRenderResult
Benutzerdefinierte Schriftarten aus einem R2-Bucket	CloudflareRenderPayload (r2FontBucket, fontFiles)
API-Schutzebene (Schlüssel-Authentifizierung, Payload-Größe, Rate Limiting)	ApiProtection
PDF-Archivierung nach R2 über die S3-kompatible API	R2ArchiveManager

Jede Zeile ist einer Klasse im Namespace NextPDF\Cloudflare zugeordnet. Geprüft wird jeweils anhand des Verhaltens dieser Klasse und ihres Tests, nicht anhand eines Spezifikationsdokuments.

Was es nicht leistet

• Es führt keinen Browser aus. Der Worker tut dies.
• Es stellt Ihren Worker nicht bereit und konfiguriert ihn nicht. Für dieses Artefakt sind Sie verantwortlich.
• Es signiert keine PDFs. Das Signieren ist Aufgabe von nextpdf/core oder der kommerziellen Editionen. Wenn Sie eine Signatur benötigen, rendern Sie zuerst und signieren Sie anschließend die zurückgegebenen Bytes mit der Engine. NextPDF Pro bietet PAdES B-B-Signaturen. Profile für die Langzeitvalidierung sind eine Enterprise-Funktion.
• Es macht keine Aussage zu Kapazitäten oder Limits der Cloudflare-Plattform. Die einzigen Größen- und Zeitlimits, die diese Dokumentation nennt, sind diejenigen, die dieses Paket in seiner eigenen Konfiguration durchsetzt (siehe /integrations/cloudflare/configuration/).

Die zwei Sicherheitsrichtlinien

Die Bridge umfasst zwei eigenständige, einander ergänzende Richtlinien; sie zu verwechseln ist der häufigste Fehler bei der Prüfung. Hier sind beide getrennt aufgeführt.

• HTML-Sicherheitsrichtlinie (HtmlSecurityPolicyInterface, Standard NextPDF\Html\DefaultHtmlSecurityPolicy, bereitgestellt von nextpdf/core): Inhaltsfilterung auf Parse-Ebene, angewendet, bevor der Inhalt den Worker erreicht. Rufen Sie sie mit getHtmlSecurityPolicy() ab.
• Cloudflare-Sicherheitsrichtlinie (CloudflareSecurityPolicy, statisch): Belange der Transportebene — Eingabegröße, Erkennung von Base64-Dekompressionsbomben, Blockieren von Meta-Refresh, HTTPS-Durchsetzung sowie SSRF-/DNS-Rebinding-Abwehr für die Worker-URL.

Der Docblock des Renderers hält diese Trennung ebenfalls fest. Diese Seite wiederholt sie, weil Prüfer im Produktivbetrieb beide Namen auf einen Blick benötigen.

Edge-Rendering-Modell

Ein einzelner render()-Aufruf führt die folgende beobachtbare Abfolge aus. Sie ist direkt aus CloudflareHtmlRenderer::render() abgeleitet.

1. Prüfung der Konfigurationsvollständigkeit (workerUrl und apiToken nicht leer). Schlägt dies fehl, greift die Bridge entweder auf einen lokalen Renderer zurück oder wirft CloudflareNotAvailableException.
2. Validierung des HTML gegen die konfigurierte Maximalgröße, die Base64-URI-Obergrenze und das Meta-Refresh-Verbot.
3. Validierung der Worker-URL; dabei wird der Host aufgelöst und das geprüfte IP-Set zurückgegeben.
4. Aufbau des Payloads (CloudflareRenderPayload).
5. Erneute Prüfung zum Nutzungszeitpunkt, ob sich die DNS-Antwort des Hosts seit Schritt 3 geändert hat.
6. Senden des HTTP-POST — über den gepinnten cURL-Transport, wenn ein IP-Set oder ein SPKI-Pin-Set vorhanden ist und eine PSR-17-ResponseFactory bereitgestellt wurde, andernfalls über den injizierten PSR-18-Client.
7. Die Antwort wird in ein CloudflareRenderResult geparst.

Jedes Throwable außer CloudflareRenderException löst den Fallback-Pfad aus. CloudflareRenderException (ein HTTP-Fehler oder eine fehlerhafte Antwort vom Worker) wird unverändert erneut geworfen. Das ist ein Fehler auf Worker-Seite, kein Erreichbarkeitsfehler; daher findet kein Fallback statt.

Siehe auch

• /integrations/cloudflare/install/ — Installation des Pakets und eines PSR-18-Clients.
• /integrations/cloudflare/configuration/ — jedes Konfigurationsfeld mit seinem quellengeprüften Standardwert.
• /integrations/cloudflare/quickstart/ — erstes lauffähiges Rendering.
• /integrations/cloudflare/production-usage/ — Fallback, Telemetrie, R2-Archivierung, API-Schutz.
• /integrations/cloudflare/security-and-operations/ — die Vertrauensgrenze im operativen Detail.
• /integrations/cloudflare/troubleshooting/ — Fehlermodi, die Exceptions zugeordnet sind.
• /integrations/cloudflare/boot-and-discovery/ — wie sich die Bridge in ein Host-Framework einklinkt.
• /integrations/cloudflare/integration/ — NextPDF über Cloudflare-Dienste ansteuern.