Guia do desenvolvedor do Cloudflare

Visão geral

O pacote do Cloudflare move a renderização de Portable Document Format (PDF) para o limite de um Worker. Trate a renderização no Worker, o fallback local, a proteção da API e o arquivamento no R2 como recursos separados, cada um com seu próprio tratamento de falhas.

Use este guia ao criar serviços de renderização na borda, endpoints de renderização protegidos, fluxos de trabalho de arquivamento ou caminhos de fallback local com nextpdf/cloudflare.

Limite de arquitetura

Camada	Pertence a	Responsabilidade	Não coloque aqui
Endpoint da aplicação	Aplicação	Autorize o chamador, normalize a solicitação de renderização e aplique a política de negócios.	Tokens do Worker armazenados no código.
Proteção da API	nextpdf/cloudflare e aplicação	Verificações de chave de API, verificações de tamanho do payload e decisões de limite de taxa em processo.	Faturamento, direito de acesso do tenant ou aplicação de cota durável.
Renderizador do Cloudflare	nextpdf/cloudflare	Valide o Hypertext Markup Language (HTML) e o Uniform Resource Locator (URL) do Worker, envie o payload de renderização e interprete a resposta.	Renderização de templates ou consultas de domínio.
Worker	Implantação da aplicação	Executa o Browser Rendering e retorna os bytes do PDF ou um resultado estruturado.	Política de armazenamento do lado do PHP.
Fallback local	Implantação da aplicação	Renderiza quando o Worker está indisponível.	Fallback silencioso que oculta interrupções operacionais.
Arquivamento R2	nextpdf/cloudflare	Faz upload de arquivos PDF, cria chaves de objeto e gera URLs assinadas.	Metadados de negócio sensíveis sem revisão.

Ciclo de vida em tempo de execução

Etapa	Comportamento	Ação do desenvolvedor
Criação da configuração	Carrega a URL do Worker, o token de API, os timeouts, os limites de tamanho, o fallback e os pins.	Mantenha os segredos na configuração de implantação.
Proteção da solicitação	O ApiProtection opcional valida a chave, o tamanho e o limite de taxa.	Execute essa etapa antes do trabalho de renderização custoso.
Chamada do renderizador	CloudflareHtmlRenderer valida o HTML e a URL do Worker e, em seguida, envia JavaScript Object Notation (JSON).	Trate separadamente a indisponibilidade do Worker e as falhas de renderização.
Análise da resposta	CloudflareResponseParser::parse() aceita saída binária de PDF ou saída estruturada em JSON.	Rejeite saída inválida ou que não seja PDF.
Fallback local	Um renderizador local opcional trata a falha do Worker.	Injete uma factory de renderizador local apenas quando o host oferecer suporte a ela.
Arquivamento R2	R2ArchiveManager armazena os bytes do PDF e gera URLs assinadas.	Use apenas metadados não sensíveis, a menos que você os armazene intencionalmente.

Estrutura de aplicação recomendada

Caminho	Finalidade
app/Pdf/Cloudflare/*	Wrapper da aplicação para CloudflareHtmlRenderer.
app/Pdf/Workers/*	Data transfer objects (DTOs) de solicitação do Worker e política específica do endpoint.
app/Pdf/Archive/*	Orquestração do arquivamento no R2 e decisões de retenção.
app/Pdf/Fallback/*	LocalRendererFactoryInterface — implementação para fallback permitido.
tests/Pdf/Cloudflare/*	Testes de Worker indisponível, token inválido, payload e arquivamento.

Mantenha o token de API do PHP separado do token do Worker. O PHP se autentica no Worker. O Worker deve autenticar as solicitações recebidas antes de iniciar o trabalho no navegador.

<?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());
}

Padrão do renderizador

Crie o renderizador com as dependências PHP Standards Recommendation (PSR) do framework, incluindo PSR-18 e PSR-17. Mantenha o fallback local explícito para que os operadores possam ver quando o sistema deixa de usar o 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);

Padrão de arquivamento no R2

Arquive somente depois que a renderização for bem-sucedida e a política aprovar o resultado. Trate URLs públicas e URLs assinadas como decisões separadas.

<?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);
}

Não inclua nomes de clientes, endereços de email, totais de faturas ou identificadores regulamentados nos metadados do objeto, a menos que a política de retenção e acesso permita isso explicitamente.

Pontos de extensão

Ponto de extensão	Use para	Restrição
LocalRendererFactoryInterface	Fallback local por meio do Artisan ou de outro renderizador.	Deve retornar um objeto que implementa LocalRendererInterface.
ApiProtectionConfig	Política de chave de API, tamanho de payload e limite de taxa.	Os limites em memória aplicam-se por processo.
ApiKeyValidator	Validação de chave resistente a ataques de temporização e auxiliares de rotação de chaves.	Armazene os segredos fora do código-fonte.
R2ArchiveConfig	Bucket, credenciais, prefixo de caminho, endpoint e limites de tamanho.	As credenciais nunca devem ser registradas em log.
PinnedCurlTransport	Aplicação de pins de Internet Protocol (IP) e de Subject Public Key Info (SPKI).	Requer um runtime com suporte a cURL e uma response factory.
CloudflareResponseParser	Análise da resposta do Worker.	Rejeita saída de PDF inválida ou respostas de erro.

Fluxo de trabalho de desenvolvimento

1. Comece criando um caminho de renderização local.
2. Adicione a renderização no Worker com um fixture HTML pequeno e representativo.
3. Habilite a proteção da solicitação antes de expor endpoints públicos.
4. Adicione o upload para o R2 somente depois que os fluxos de renderização e resposta estiverem estáveis.
5. Teste os caminhos para Worker indisponível, token inválido, payload excedente, limite de taxa e falha do R2.
6. Adicione logs que distingam a renderização no Worker, a renderização de fallback, o upload do arquivo e a criação de URL assinada.

Tratamento de falhas

Falha	Onde deve ser tratada	Resposta recomendada
Chave de API ausente ou inválida	Camada de proteção da API.	Rejeite a solicitação antes que o trabalho de renderização comece.
Payload excedente	Proteção da API ou validação do renderizador.	Retorne uma falha de validação sem chamada ao Worker.
URL do Worker insegura	Política de segurança do renderizador.	Faça a configuração ou a solicitação falhar antes de qualquer input/output (I/O) de rede.
Worker indisponível	Limite do renderizador.	Use o fallback explícito apenas quando permitido; caso contrário, falhe de forma visível.
Falha no upload do R2	Limite de arquivamento.	Retorne a resposta do PDF se o arquivamento for opcional; falhe se o arquivamento for exigido pela política.
Falha na rotação de pins	Implantação e operações.	Faça a rotação com pins de backup e um plano de rollback.

Padrões seguros

Aspecto	Padrão	Quando substituir
Fallback	Habilitado por padrão na configuração.	Desabilite quando a renderização local violaria o isolamento da implantação.
Tamanho máximo do HTML	5,000,000 bytes.	Reduza para endpoints públicos.
Time to live (TTL) da URL assinada	3600 segundos.	Encurte-o para PDFs sensíveis.
Conjuntos de pins	Vazio.	Adicione pins apenas com um plano de rotação e pins de backup.
Exigência de chave de API	Habilitada por padrão na configuração de proteção.	Desabilite apenas para chamadas internas privadas e já autenticadas.

Lista de verificação de testes

• Os testes do renderizador cobrem HTML válido, HTML excedente, URL do Worker inválida e uma resposta de erro do Worker.
• Os testes de proteção da API cobrem uma chave ausente, uma chave inválida, um payload grande demais e um limite de taxa excedido.
• Os testes do R2 cobrem upload bem-sucedido, upload grande demais, status de falha do Hypertext Transfer Protocol (HTTP), bucket inválido e geração de URL assinada.
• Os testes de fallback verificam se o caminho do renderizador local é explícito e observável.
• Os testes de transporte cobrem IPs fixados, pins de chave pública, timeout e redirecionamentos desabilitados por política.
• Os testes de observabilidade garantem eventos de log distintos para renderização, fallback, arquivamento e criação de URL assinada.