Descripción general del puente de representación en el borde de NextPDF para Cloudflare

De un vistazo

nextpdf/cloudflare es un puente de representación en el borde. La aplicación PHP mantiene el HTML; un Worker de Cloudflare mantiene el navegador sin interfaz gráfica. El puente envía el HTML al Worker por HTTPS y recibe de vuelta los bytes del PDF representado. No se ejecuta ningún navegador sin interfaz gráfica dentro del proceso PHP ni se requiere ningún binario local de Chromium en la ruta gestionada por el puente.

El paquete pertenece al ecosistema de NextPDF y depende de nextpdf/core^3.0. Es código de protocolo de transporte: construye una petición JSON, valida la entrada y el destino, envía la petición mediante un cliente PSR-18 y analiza la respuesta para convertirla en un objeto de resultado tipado. La implementación del Worker no forma parte de este paquete. Este puente se comunica con un Worker que se despliega por separado.

El límite de confianza

La característica que define este puente es que el HTML cruza un límite de red y llega a un motor de navegador que no se controla directamente desde el proceso PHP. Cada control de seguridad del paquete existe por ese límite.

• El HTML se valida antes de abandonar el proceso de PHP (CloudflareSecurityPolicy::validate()).
• La URL de destino se valida antes de enviar la petición (CloudflareSecurityPolicy::validateWorkerUrl()) y se vuelve a validar en el momento de la petición para cerrar la ventana time-of-check/time-of-use (assertPinsStillValid()).
• El transporte puede fijar el conjunto de IP resueltas y la clave pública del certificado del servidor (Transport\PinnedCurlTransport).

Si se evalúa este puente para producción, conviene leer /integrations/cloudflare/security-and-operations/ antes que /integrations/cloudflare/quickstart/. El modelo de seguridad no es un complemento: es la razón por la que el paquete tiene esta forma.

Qué hace

Capacidad	Respaldada por
Representar HTML como PDF a través de un Worker de Cloudflare	CloudflareHtmlRenderer::render()
Sondeo de disponibilidad (HTTP HEAD)	CloudflareHtmlRenderer::isAvailable()
Transporte independiente del proveedor	Inyección de ClientInterface PSR-18
Endurecimiento de la entrada (tamaño, bomba base64, meta-refresh)	CloudflareSecurityPolicy::validate()
Defensa frente a SSRF / reasignación de DNS	CloudflareSecurityPolicy::validateWorkerUrl() + assertPinsStillValid()
Fijación de la clave pública TLS y del DNS en la capa de cURL	Transport\PinnedCurlTransport
Reserva local con Chrome cuando el Worker es inaccesible	Contract\LocalRendererFactoryInterface
Análisis de respuestas binarias y JSON (base64)	CloudflareResponseParser
Telemetría del borde (tiempo de representación, ubicación del borde, altura del contenido)	CloudflareRenderResult
Fuentes personalizadas desde un bucket de R2	CloudflareRenderPayload (r2FontBucket, fontFiles)
Capa de protección de la API (autenticación por clave, tamaño del cuerpo, limitación de tasa)	ApiProtection
Archivado de PDF en R2 a través de la API compatible con S3	R2ArchiveManager

Cada fila corresponde a una clase del espacio de nombres NextPDF\Cloudflare. Cada una se verifica frente al comportamiento de esa clase y su prueba, no frente a un documento de especificación.

Qué no hace

• No ejecuta ningún navegador. Lo hace el Worker.
• No despliega ni configura el Worker. La responsabilidad de ese artefacto corresponde al proyecto integrador.
• No firma PDF. La firma corresponde a nextpdf/core o a las ediciones comerciales. Cuando sea necesario firmar, represente primero y, a continuación, firme los bytes devueltos con el motor. NextPDF Pro proporciona firma PAdES B-B. Los perfiles de validación a largo plazo son una capacidad de Enterprise.
• No afirma ninguna capacidad ni límite de la plataforma de Cloudflare. Los únicos límites de tamaño y tiempo que indica esta documentación son los que este paquete impone en su propia configuración (consulte /integrations/cloudflare/configuration/).

Las dos políticas de seguridad

El puente incorpora dos políticas distintas y complementarias, y confundirlas es el error de revisión más habitual. A continuación, se describe cada una.

• Política de seguridad de HTML (HtmlSecurityPolicyInterface, valor predeterminado NextPDF\Html\DefaultHtmlSecurityPolicy, proporcionada por nextpdf/core): filtrado de contenido en la capa de análisis, aplicado antes de que el contenido llegue al Worker. Se obtiene con getHtmlSecurityPolicy().
• Política de seguridad de Cloudflare (CloudflareSecurityPolicy, estática): controles de la capa de transporte: tamaño de la entrada, detección de bombas de descompresión base64, bloqueo de meta-refresh, imposición de HTTPS y defensa frente a SSRF / reasignación de DNS en la URL del Worker.

El propio docblock del renderizador establece esta separación. Esta página la reafirma porque los revisores de producción necesitan ambos nombres en una misma pantalla.

Modelo de representación en el borde

Una única llamada a render() ejecuta la siguiente secuencia observable. Esta secuencia se lee directamente de CloudflareHtmlRenderer::render().

1. Comprobación de la integridad de la configuración (workerUrl y apiToken no vacíos). En caso de fallo, el puente recurre a un renderizador local o lanza CloudflareNotAvailableException.
2. Validación del HTML frente al tamaño máximo configurado, el límite de URI base64 y la prohibición de meta-refresh.
3. Validación de la URL del Worker, que resuelve el host y devuelve el conjunto de direcciones IP verificadas.
4. Construcción del cuerpo (CloudflareRenderPayload).
5. Nueva comprobación, en el momento de uso, de que la respuesta DNS del host no ha cambiado desde el paso 3.
6. Envío del POST HTTP: mediante el transporte cURL fijado cuando existe un conjunto de IP o un conjunto de pines SPKI y se ha proporcionado una ResponseFactory PSR-17; en caso contrario, mediante el cliente PSR-18 inyectado.
7. La respuesta se analiza para convertirla en un CloudflareRenderResult.

Cualquier excepción lanzada distinta de CloudflareRenderException activa la ruta de reserva. CloudflareRenderException (un error HTTP o una respuesta mal formada del Worker) se vuelve a lanzar sin cambios. Es un fallo del lado del Worker, no un fallo de disponibilidad, por lo que no se recurre a la reserva.

Véase también

• /integrations/cloudflare/install/ — instalación del paquete y de un cliente PSR-18.
• /integrations/cloudflare/configuration/ — todos los campos de configuración, con su valor predeterminado verificado en el código fuente.
• /integrations/cloudflare/quickstart/ — una primera representación ejecutable.
• /integrations/cloudflare/production-usage/ — reserva, telemetría, archivado en R2, protección de la API.
• /integrations/cloudflare/security-and-operations/ — el límite de confianza en detalle operativo.
• /integrations/cloudflare/troubleshooting/ — modos de fallo correlacionados con excepciones.
• /integrations/cloudflare/boot-and-discovery/ — cómo se conecta el puente a un framework anfitrión.
• /integrations/cloudflare/integration/ — uso de NextPDF a través de los servicios de Cloudflare.