NextPDF bridge de renderização na edge da Cloudflare — visão geral

Visão geral

nextpdf/cloudflare é um bridge de renderização na edge. O aplicativo PHP fica responsável pelo Hypertext Markup Language (HTML), enquanto um Cloudflare Worker fica responsável pelo navegador headless. O bridge envia o HTML ao Worker por Hypertext Transfer Protocol Secure (HTTPS) e recebe os bytes do Portable Document Format (PDF) renderizado. Nenhum navegador headless é executado dentro do processo PHP, e o bridge não exige um binário Chromium local no caminho sob seu controle.

O pacote faz parte do ecossistema NextPDF e depende de nextpdf/core^3.0. Trata-se de código de protocolo de comunicação: ele monta uma requisição JavaScript Object Notation (JSON), valida a entrada e o destino, envia a requisição por meio de um cliente PHP Standards Recommendation 18 (PSR-18) e transforma a resposta em um objeto de resultado tipado. A implementação do Worker fica fora deste pacote. Este bridge se comunica com o Worker que você implanta.

O limite de confiança

A principal característica deste bridge é que o HTML atravessa um limite de rede e chega a um mecanismo de navegador que você não controla diretamente. Todos os controles de segurança do pacote existem por causa desse limite.

O HTML é validado antes de sair do processo PHP (CloudflareSecurityPolicy::validate()).
O Uniform Resource Locator (URL) de destino é validado antes de a requisição ser enviada (CloudflareSecurityPolicy::validateWorkerUrl()) e, em seguida, revalidado no momento da requisição para fechar a janela time-of-check/time-of-use (assertPinsStillValid()).
O transporte pode fixar (pin) o conjunto de Internet Protocol (IP) resolvido e a chave pública do certificado do servidor (Transport\PinnedCurlTransport).

Se você está avaliando este bridge para produção, leia /integrations/cloudflare/security-and-operations/ antes de /integrations/cloudflare/quickstart/. O modelo de segurança não é um complemento; ele explica por que o pacote tem esse formato.

O que ele faz

Capacidade	Implementado por
Renderizar HTML em PDF por meio de um Cloudflare Worker	`CloudflareHtmlRenderer::render()`
Verificação de acessibilidade (Hypertext Transfer Protocol (HTTP) `HEAD`)	`CloudflareHtmlRenderer::isAvailable()`
Transporte independente de fornecedor	Injeção de `ClientInterface` PSR-18
Endurecimento da entrada (tamanho, bomba base64, meta-refresh)	`CloudflareSecurityPolicy::validate()`
Defesa contra server-side request forgery (SSRF) / DNS-rebinding (Domain Name System)	`CloudflareSecurityPolicy::validateWorkerUrl()` + `assertPinsStillValid()`
Fixação (pinning) de chave pública Transport Layer Security (TLS), DNS fixado na camada cURL	`Transport\PinnedCurlTransport`
Fallback para o Chrome local quando o Worker está inacessível	`Contract\LocalRendererFactoryInterface`
Análise de respostas binárias e JSON (base64)	`CloudflareResponseParser`
Telemetria da edge (tempo de renderização, localização da edge, altura do conteúdo)	`CloudflareRenderResult`
Fontes personalizadas de um bucket R2	`CloudflareRenderPayload` (`r2FontBucket`, `fontFiles`)
Camada de proteção da Application Programming Interface (API) (autenticação por chave, tamanho do payload, limitação de taxa)	`ApiProtection`
Arquivamento de PDF no R2 pela API compatível com S3	`R2ArchiveManager`

Cada linha corresponde a uma classe no namespace NextPDF\Cloudflare. Cada linha é verificada contra o comportamento dessa classe e seu teste, não contra um documento de especificação.

O que ele não faz

Ele não executa um navegador. O Worker faz isso.
Ele não implanta nem configura o Worker. Esse artefato é responsabilidade sua.
Ele não assina PDFs. A assinatura pertence ao nextpdf/core ou às edições comerciais. Quando você precisar de assinatura, renderize primeiro e depois assine os bytes retornados com o engine. O NextPDF Pro fornece assinatura PAdES B-B. Os perfis de validação de longo prazo são um recurso do Enterprise.
Ele não declara nenhuma capacidade nem limite da plataforma Cloudflare. Os únicos limites de tamanho e de tempo que esta documentação declara são os que este pacote aplica por meio da própria configuração (consulte /integrations/cloudflare/configuration/).

As duas políticas de segurança

O bridge carrega duas políticas distintas e complementares. Confundi-las é o erro de revisão mais comum. Veja cada uma delas.

Política de segurança de HTML (HtmlSecurityPolicyInterface, por padrão NextPDF\Html\DefaultHtmlSecurityPolicy, fornecida pelo nextpdf/core): filtragem de conteúdo na camada de parsing, aplicada antes de o conteúdo chegar ao Worker. Obtenha-a com getHtmlSecurityPolicy().
Política de segurança do Cloudflare (CloudflareSecurityPolicy, estática): preocupações da camada de transporte: tamanho da entrada, detecção de bomba de descompressão base64, bloqueio de meta-refresh, imposição de HTTPS e defesa contra SSRF / DNS-rebinding na URL do Worker.

O próprio docblock do renderizador declara essa separação. Esta página a reforça porque revisores de produção precisam ver os dois nomes na mesma tela.

Modelo de renderização na edge

Uma única chamada a render() segue esta sequência observável. A sequência vem diretamente de CloudflareHtmlRenderer::render().

Verificação de completude da configuração (workerUrl e apiToken não vazios). Se a verificação falhar, o bridge recorre a um renderizador local ou lança CloudflareNotAvailableException.
Validação do HTML em relação ao tamanho máximo configurado, ao teto de URI base64 e à proibição de meta-refresh.
Validação da URL do Worker, que resolve o host e retorna o conjunto de IPs verificado.
Construção do payload (CloudflareRenderPayload).
Uma nova verificação no momento do uso confirma que a resposta DNS do host não mudou desde o passo 3.
O POST HTTP é enviado pelo transporte cURL fixado quando existe um conjunto de IPs ou um conjunto de pins Subject Public Key Info (SPKI) e uma ResponseFactory PSR-17 foi fornecida; caso contrário, pelo cliente PSR-18 injetado.
A resposta é analisada em um CloudflareRenderResult.

Qualquer throwable diferente de CloudflareRenderException aciona o caminho de fallback. CloudflareRenderException (um erro HTTP ou uma resposta malformada do Worker) é relançada sem alteração. Trata-se de uma falha do lado do Worker, não de uma falha de acessibilidade; portanto, o bridge não recorre ao fallback.

Veja também

/integrations/cloudflare/install/ — instale o pacote e um cliente PSR-18.
/integrations/cloudflare/configuration/ — todos os campos de configuração, com o valor padrão verificado no código-fonte.
/integrations/cloudflare/quickstart/ — a primeira renderização executável.
/integrations/cloudflare/production-usage/ — fallback, telemetria, arquivamento no R2, proteção da API.
/integrations/cloudflare/security-and-operations/ — detalhes operacionais do limite de confiança.
/integrations/cloudflare/troubleshooting/ — modos de falha mapeados para exceções.
/integrations/cloudflare/boot-and-discovery/ — como o bridge se integra a um framework hospedeiro.
/integrations/cloudflare/integration/ — condução do NextPDF por meio dos serviços da Cloudflare.