NextPDF: ponte di rendering edge per Cloudflare — panoramica

In sintesi

nextpdf/cloudflare è un ponte di rendering edge. L’applicazione PHP mantiene l’HTML, mentre il browser headless è in carico a un Worker Cloudflare. Il ponte invia l’HTML al Worker tramite HTTPS e riceve in risposta i byte del PDF renderizzato. Nessun browser headless viene eseguito all’interno del processo PHP e non è richiesto alcun binario Chromium locale nel percorso gestito dal ponte.

Il pacchetto appartiene all’ecosistema NextPDF e dipende da nextpdf/core^3.0. È codice per il protocollo wire: costruisce una richiesta JSON, valida l’input e la destinazione, invia la richiesta tramite un client PSR-18 e analizza la risposta producendo un oggetto risultato tipizzato. L’implementazione del Worker non fa parte di questo pacchetto. Il ponte dialoga con un Worker distribuito autonomamente.

Il confine di fiducia

La caratteristica distintiva di questo ponte è che l’HTML attraversa un confine di rete e raggiunge un motore browser non controllato direttamente. Ogni controllo di sicurezza del pacchetto nasce da tale confine.

L’HTML viene validato prima di lasciare il processo PHP (CloudflareSecurityPolicy::validate()).
L’URL di destinazione viene validato prima dell’invio della richiesta (CloudflareSecurityPolicy::validateWorkerUrl()) e nuovamente validato al momento della richiesta per chiudere la finestra time-of-check/time-of-use (assertPinsStillValid()).
Il trasporto può applicare il pinning al set di IP risolto e alla chiave pubblica del certificato del server (Transport\PinnedCurlTransport).

Se si valuta questo ponte per la produzione, leggere /integrations/cloudflare/security-and-operations/ prima di /integrations/cloudflare/quickstart/. Il modello di sicurezza non è un componente accessorio. È la ragione per cui il pacchetto ha questa forma.

Cosa fa

Funzionalità	Supportata da
Rendering di HTML in PDF tramite un Worker Cloudflare	`CloudflareHtmlRenderer::render()`
Sonda di raggiungibilità (HTTP `HEAD`)	`CloudflareHtmlRenderer::isAvailable()`
Trasporto indipendente dal fornitore	Iniezione di `ClientInterface` PSR-18
Hardening dell’input (dimensione, bomba base64, meta-refresh)	`CloudflareSecurityPolicy::validate()`
Difesa da SSRF / DNS-rebinding	`CloudflareSecurityPolicy::validateWorkerUrl()` + `assertPinsStillValid()`
Pinning della chiave pubblica TLS, DNS fissato a livello cURL	`Transport\PinnedCurlTransport`
Fallback su Chrome locale quando il Worker è irraggiungibile	`Contract\LocalRendererFactoryInterface`
Analisi delle risposte binarie e JSON (base64)	`CloudflareResponseParser`
Telemetria edge (tempo di rendering, posizione edge, altezza del contenuto)	`CloudflareRenderResult`
Font personalizzati da un bucket R2	`CloudflareRenderPayload` (`r2FontBucket`, `fontFiles`)
Livello di protezione dell’API (autenticazione a chiave, dimensione del payload, limitazione della frequenza)	`ApiProtection`
Archiviazione dei PDF su R2 tramite l’API compatibile con S3	`R2ArchiveManager`

Ogni riga corrisponde a una classe nel namespace NextPDF\Cloudflare. Ogni riga è verificata rispetto al comportamento di quella classe e al relativo test, non rispetto a una specifica.

Cosa non fa

Non esegue un browser. Lo fa il Worker.
Non distribuisce né configura il Worker. Questo artefatto resta di proprietà dell’utente.
Non firma i PDF. La firma spetta a nextpdf/core o alle edizioni commerciali. Quando serve firmare, eseguire prima il rendering, poi firmare con il motore i byte restituiti. NextPDF Pro fornisce la firma PAdES B-B. I profili di validazione a lungo termine sono una funzionalità Enterprise.
Non dichiara alcuna capacità né alcun limite della piattaforma Cloudflare. Gli unici limiti di dimensione e di tempo indicati in questa documentazione sono quelli che il pacchetto applica nella propria configurazione (vedere /integrations/cloudflare/configuration/).

Le due politiche di sicurezza

Il ponte include due politiche distinte e complementari, e confonderle è l’errore di revisione più comune. Eccole entrambe.

Politica di sicurezza HTML (HtmlSecurityPolicyInterface, predefinita NextPDF\Html\DefaultHtmlSecurityPolicy, fornita da nextpdf/core): filtraggio del contenuto a livello di parsing, applicato prima che il contenuto raggiunga il Worker. La si recupera con getHtmlSecurityPolicy().
Politica di sicurezza Cloudflare (CloudflareSecurityPolicy, statica): aspetti a livello di trasporto — dimensione dell’input, rilevamento di bombe di decompressione base64, blocco del meta-refresh, imposizione di HTTPS e difesa da SSRF / DNS-rebinding sull’URL del Worker.

Il docblock stesso del renderer dichiara questa separazione. Questa pagina lo ribadisce perché i revisori di produzione hanno bisogno di entrambi i nomi nella stessa schermata.

Modello di rendering edge

Una singola chiamata a render() esegue la seguente sequenza osservabile. La sequenza è ricavata direttamente da CloudflareHtmlRenderer::render().

Verifica della completezza della configurazione (workerUrl e apiToken non vuoti). Se fallisce, il ponte ricade su un renderer locale oppure solleva CloudflareNotAvailableException.
Validazione dell’HTML rispetto alla dimensione massima configurata, al limite massimo per gli URI base64 e al divieto di meta-refresh.
Validazione dell’URL del Worker, che risolve l’host e restituisce il set di IP verificato.
Costruzione del payload (CloudflareRenderPayload).
Nuova verifica, al momento dell’uso, che la risposta DNS dell’host non sia cambiata dal passaggio 3.
Invio del POST HTTP: tramite il trasporto cURL con pinning quando esiste un set di IP o un set di pin SPKI ed è stata fornita una ResponseFactory PSR-17; in caso contrario, tramite il client PSR-18 iniettato.
La risposta viene analizzata in un CloudflareRenderResult.

Qualsiasi throwable diverso da CloudflareRenderException attiva il percorso di fallback. CloudflareRenderException (un errore HTTP o una risposta malformata proveniente dal Worker) viene rilanciata senza modifiche. È un guasto lato Worker, non un guasto di raggiungibilità, quindi non ricade sul fallback.

Vedere anche

/integrations/cloudflare/install/ — installare il pacchetto e un client PSR-18.
/integrations/cloudflare/configuration/ — ogni campo di configurazione, con il relativo valore predefinito verificato sul sorgente.
/integrations/cloudflare/quickstart/ — un primo rendering eseguibile.
/integrations/cloudflare/production-usage/ — fallback, telemetria, archiviazione su R2, protezione dell’API.
/integrations/cloudflare/security-and-operations/ — il confine di fiducia nel dettaglio operativo.
/integrations/cloudflare/troubleshooting/ — modalità di guasto mappate alle eccezioni.
/integrations/cloudflare/boot-and-discovery/ — come il ponte si inserisce in un framework ospitante.
/integrations/cloudflare/integration/ — pilotare NextPDF attraverso i servizi Cloudflare.