Guide développeur Cloudflare

En bref

Le package Cloudflare déplace le rendu vers une frontière Worker. Traite le rendu Worker, le repli local, la protection de l’API et l’archive R2 comme des capacités distinctes, chacune avec sa propre gestion des défaillances.

Utilise ce guide lorsque tu construis des services de rendu en périphérie, des points d’accès de rendu protégés, des workflows d’archivage ou des chemins de repli local autour de nextpdf/cloudflare.

Frontière d’architecture

Couche	Responsable	Responsabilité	À exclure
Point d’accès applicatif	Application	Autoriser l’appelant, normaliser la requête de rendu et appliquer la politique métier.	Stockage du jeton Worker dans le code.
Protection de l’API	nextpdf/cloudflare et application	Décisions relatives à la clé d’API, à la taille de charge utile et à la limite de débit au sein du processus.	Facturation, droits d’accès du locataire ou application persistante des quotas.
Renderer Cloudflare	nextpdf/cloudflare	Valider le HTML et l’URL du Worker, envoyer la charge utile de rendu et analyser la réponse.	Rendu de templates ou requêtes de domaine.
Worker	Déploiement de l’application	Exécuter Browser Rendering et renvoyer les octets du PDF ou un résultat structuré.	Politique de stockage côté PHP.
Repli local	Déploiement de l’application	Effectuer le rendu lorsque le Worker est indisponible.	Repli silencieux qui masque les pannes opérationnelles.
Archive R2	nextpdf/cloudflare	Téléverser les PDF, construire les clés d’objets et créer des URL signées.	Métadonnées métier sensibles sans revue.

Cycle de vie à l’exécution

Étape	Comportement	Action du développeur
Création de la configuration	L’URL du Worker, le jeton d’API, les délais d’expiration, les limites de taille, le repli et les épinglages sont chargés.	Garde les secrets dans la configuration de déploiement.
Protection des requêtes	En option, ApiProtection valide la clé, la taille et la limite de débit.	À exécuter avant tout travail de rendu coûteux.
Appel du renderer	CloudflareHtmlRenderer valide le HTML et l’URL du Worker, puis envoie le JSON.	Gère séparément l’indisponibilité du Worker et les échecs de rendu.
Analyse de la réponse	CloudflareResponseParser::parse() accepte une sortie PDF binaire ou JSON structurée.	Rejette toute sortie non valide ou qui n’est pas un PDF.
Repli local	Un renderer local optionnel gère l’échec du Worker.	N’injecte une fabrique de renderer local que lorsque l’hôte la prend en charge.
Archive R2	R2ArchiveManager stocke les octets du PDF et crée des URL signées.	Ne conserve que des métadonnées non sensibles, sauf stockage intentionnel.

Structure d’application recommandée

Chemin	Objectif
app/Pdf/Cloudflare/*	Wrapper applicatif autour de CloudflareHtmlRenderer.
app/Pdf/Workers/*	DTO de requête Worker et politique propre au point d’accès.
app/Pdf/Archive/*	Orchestration de l’archive R2 et décisions de rétention.
app/Pdf/Fallback/*	LocalRendererFactoryInterface implémentée lorsque le repli est autorisé.
tests/Pdf/Cloudflare/*	Tests couvrant le Worker indisponible, le jeton non valide, la charge utile et l’archive.

Garde le jeton d’API PHP et le jeton Worker séparés. Le côté PHP s’authentifie auprès du Worker. Le Worker doit authentifier les requêtes entrantes avant d’effectuer le travail du navigateur.

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

Modèle de renderer

Construis le renderer avec les dépendances PSR-18 et PSR-17 fournies par ton framework. Garde le repli local explicite pour que les opérateurs voient quand le système cesse d’utiliser le 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);

Modèle d’archive R2

N’archive qu’après la réussite du rendu et l’approbation de la politique. Traite les URL publiques et les URL signées comme des décisions distinctes.

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

Ne mets pas de noms de clients, d’adresses e-mail, de montants de factures ou d’identifiants réglementés dans les métadonnées d’objets, sauf si ta politique de rétention et d’accès l’autorise explicitement.

Points d’extension

Point d’extension	À utiliser pour	Contrainte
LocalRendererFactoryInterface	Repli local vers Artisan ou un autre renderer.	Doit renvoyer un objet qui implémente LocalRendererInterface.
ApiProtectionConfig	Politique de clé d’API, de taille de charge utile et de limite de débit.	Les limites en mémoire sont par processus.
ApiKeyValidator	Validation de clé en temps constant et utilitaires de rotation de clés.	Stocke les secrets en dehors du code source.
R2ArchiveConfig	Bucket, identifiants, préfixe de chemin, endpoint et limites de taille.	Les identifiants ne doivent jamais être journalisés.
PinnedCurlTransport	Application des épinglages IP et SPKI.	Nécessite un runtime compatible cURL et une fabrique de réponses.
CloudflareResponseParser	Analyse de la réponse du Worker.	Rejette les PDF non valides ou les réponses d’erreur.

Workflow de développement

1. Construis d’abord un chemin de rendu local.
2. Ajoute le rendu Worker avec une petite fixture HTML représentative.
3. Active la protection des requêtes avant d’exposer des points d’accès publics.
4. N’ajoute le téléversement R2 qu’une fois les flux de rendu et de réponse stables.
5. Teste les chemins de Worker indisponible, de jeton non valide, de charge utile trop volumineuse, de limite de débit et d’échec R2.
6. Ajoute des logs qui distinguent le rendu Worker, le rendu de repli, le téléversement vers l’archive et la création d’URL signées.

Gestion des défaillances

Défaillance	Où elle doit être gérée	Réponse recommandée
Clé d’API manquante ou non valide	Couche de protection de l’API.	Rejeter avant de lancer le travail de rendu.
Charge utile trop volumineuse	Protection de l’API ou validation du renderer.	Renvoyer un échec de validation sans appel au Worker.
URL de Worker non sûre	Politique de sécurité du renderer.	Faire échouer la configuration ou la requête avant toute E/S réseau.
Worker indisponible	Frontière du renderer.	N’utilise un repli explicite que lorsqu’il est autorisé ; sinon, échoue de façon visible.
Échec de téléversement R2	Frontière de l’archive.	Renvoyer la réponse PDF si l’archive est optionnelle ; échouer si l’archive est requise par la politique.
Échec de rotation des épinglages	Déploiement et exploitation.	Effectuer la rotation avec des épinglages de secours et un plan de retour arrière.

Valeurs par défaut sûres

Aspect	Valeur par défaut	Quand la remplacer
Repli	Activé par défaut dans la configuration.	Désactive-le quand le rendu local violerait l’isolation du déploiement.
Taille HTML maximale	5,000,000 octets.	À abaisser pour les points d’accès publics.
TTL d’URL signée	3600 secondes.	À raccourcir pour les PDF sensibles.
Jeux d’épinglages	Vide.	N’ajoute des épinglages qu’avec un plan de rotation et des épinglages de secours.
Exigence de clé d’API	Activée par défaut dans la configuration de protection.	À désactiver uniquement pour des appels internes privés et déjà authentifiés.

Liste de contrôle des tests

• Les tests du renderer couvrent le HTML valide, le HTML trop volumineux, l’URL de Worker non valide et la réponse d’erreur du Worker.
• Les tests de protection de l’API couvrent la clé manquante, la clé non valide, la charge utile trop volumineuse et la limite de débit dépassée.
• Les tests R2 couvrent le téléversement réussi, le téléversement trop volumineux, l’échec du statut HTTP, le bucket non valide et la génération d’URL signées.
• Les tests de repli vérifient que le chemin du renderer local est explicite et observable.
• Les tests de transport couvrent les IP épinglées, les épinglages de clé publique, le délai d’expiration et les redirections désactivées par la politique.
• Les tests d’observabilité vérifient des événements de log distincts pour le rendu, le repli, l’archive et la création d’URL signées.