NextPDF – przegląd mostka renderowania brzegowego Cloudflare

W skrócie

nextpdf/cloudflare to mostek renderowania brzegowego. Kod Hypertext Markup Language (HTML) pozostaje po stronie aplikacji PHP, a przeglądarka bezgłowowa po stronie workera Cloudflare. Mostek wysyła HTML do workera przez Hypertext Transfer Protocol Secure (HTTPS) i odbiera wyrenderowane bajty w formacie Portable Document Format (PDF). Żadna przeglądarka bezgłowowa nie działa w procesie PHP, a mostek nie wymaga lokalnego pliku binarnego Chromium w zarządzanej przez siebie ścieżce.

Pakiet należy do ekosystemu NextPDF i zależy od nextpdf/core^3.0. To kod warstwy protokołu transmisji: buduje żądanie w formacie JavaScript Object Notation (JSON), weryfikuje dane wejściowe i miejsce docelowe, wysyła żądanie przez klienta PHP Standards Recommendation 18 (PSR-18) i parsuje odpowiedź do typowanego obiektu wyniku. Implementacja workera znajduje się poza tym pakietem. Mostek komunikuje się z workerem, który wdrażasz.

Granica zaufania

Cechą definiującą ten mostek jest to, że HTML przekracza granicę sieci i trafia do silnika przeglądarki, którego nie kontrolujesz bezpośrednio. Każde zabezpieczenie w pakiecie istnieje właśnie ze względu na tę granicę.

• HTML jest weryfikowany przed opuszczeniem procesu PHP (CloudflareSecurityPolicy::validate()).
• Docelowy adres Uniform Resource Locator (URL) jest weryfikowany przed wysłaniem żądania (CloudflareSecurityPolicy::validateWorkerUrl()), a następnie weryfikowany ponownie w momencie żądania, aby zamknąć okno time-of-check/time-of-use (assertPinsStillValid()).
• Transport może przypiąć rozpoznany zbiór adresów Internet Protocol (IP) oraz klucz publiczny certyfikatu serwera (Transport\PinnedCurlTransport).

Jeśli oceniasz ten mostek pod kątem użycia produkcyjnego, przeczytaj /integrations/cloudflare/security-and-operations/ przed /integrations/cloudflare/quickstart/. Model bezpieczeństwa nie jest dodatkiem; wyjaśnia, dlaczego pakiet ma właśnie taki kształt.

Co robi

Funkcja	Realizowane przez
Renderowanie HTML do PDF za pośrednictwem workera Cloudflare	CloudflareHtmlRenderer::render()
Sonda osiągalności (Hypertext Transfer Protocol (HTTP) HEAD)	CloudflareHtmlRenderer::isAvailable()
Transport niezależny od dostawcy	Wstrzykiwanie ClientInterface zgodnego z PSR-18
Utwardzanie danych wejściowych (rozmiar, bomba base64, meta-refresh)	CloudflareSecurityPolicy::validate()
Ochrona przed Server-side request forgery (SSRF) / przepinaniem Domain Name System (DNS)	CloudflareSecurityPolicy::validateWorkerUrl() + assertPinsStillValid()
Przypinanie klucza publicznego Transport Layer Security (TLS), DNS przypięty w warstwie cURL	Transport\PinnedCurlTransport
Lokalny tryb awaryjny Chrome, gdy worker jest nieosiągalny	Contract\LocalRendererFactoryInterface
Parsowanie odpowiedzi binarnych i JSON (base64)	CloudflareResponseParser
Telemetria brzegowa (czas renderowania, lokalizacja brzegowa, wysokość treści)	CloudflareRenderResult
Niestandardowe czcionki z zasobnika R2	CloudflareRenderPayload (r2FontBucket, fontFiles)
Warstwa ochrony Application Programming Interface (API) (uwierzytelnianie kluczem, rozmiar ładunku, ograniczanie liczby żądań)	ApiProtection
Archiwizacja PDF do R2 przez API zgodne z S3	R2ArchiveManager

Każdy wiersz odpowiada klasie w przestrzeni nazw NextPDF\Cloudflare. Każdy z nich jest weryfikowany względem zachowania danej klasy i jej testu, a nie względem dokumentu specyfikacji.

Czego nie robi

• Nie uruchamia przeglądarki. Robi to worker.
• Nie wdraża ani nie konfiguruje Twojego workera. To Twój artefakt.
• Nie podpisuje plików PDF. Podpisywanie obsługuje nextpdf/core lub edycje komercyjne. Jeśli potrzebny jest podpis, najpierw wyrenderuj dokument, a następnie podpisz zwrócone bajty za pomocą silnika. NextPDF Pro zapewnia podpisywanie PAdES B-B. Profile walidacji długoterminowej są funkcją edycji Enterprise.
• Nie zapewnia żadnej pojemności platformy Cloudflare ani nie określa jej limitów. Jedyne limity rozmiaru i czasu podawane w tej dokumentacji to te, które ten pakiet egzekwuje przez własną konfigurację (zobacz /integrations/cloudflare/configuration/).

Dwie polityki bezpieczeństwa

Mostek obejmuje dwie odrębne, uzupełniające się polityki. Ich mylenie to najczęstszy błąd podczas przeglądu. Poniżej obie.

• Polityka bezpieczeństwa HTML (HtmlSecurityPolicyInterface, domyślnie NextPDF\Html\DefaultHtmlSecurityPolicy, dostarczana przez nextpdf/core): filtrowanie treści w warstwie parsowania, stosowane zanim treść dotrze do workera. Pobierz ją za pomocą getHtmlSecurityPolicy().
• Polityka bezpieczeństwa Cloudflare (CloudflareSecurityPolicy, statyczna): zagadnienia warstwy transportu: rozmiar danych wejściowych, wykrywanie bomby dekompresyjnej base64, blokowanie meta-refresh, wymuszanie HTTPS oraz obrona przed SSRF / przepinaniem DNS dla adresu URL workera.

Docblock samego renderera opisuje ten podział. Ta strona go powtarza, ponieważ recenzenci produkcyjni potrzebują obu nazw na jednym ekranie.

Model renderowania brzegowego

Pojedyncze wywołanie render() przebiega według następującej obserwowalnej sekwencji. Sekwencja wynika bezpośrednio z CloudflareHtmlRenderer::render().

1. Sprawdzenie kompletności konfiguracji (workerUrl i apiToken niepuste). Jeśli sprawdzenie się nie powiedzie, mostek albo przechodzi awaryjnie na lokalny renderer, albo zgłasza CloudflareNotAvailableException.
2. Weryfikacja HTML względem skonfigurowanego maksymalnego rozmiaru, górnego limitu URI base64 oraz zakazu meta-refresh.
3. Weryfikacja adresu URL workera, która rozwiązuje nazwę hosta i zwraca zweryfikowany zbiór adresów IP.
4. Konstruowanie ładunku (CloudflareRenderPayload).
5. Ponowne sprawdzenie w momencie użycia potwierdza, że odpowiedź DNS hosta nie zmieniła się od kroku 3.
6. Żądanie HTTP POST jest wysyłane przez przypięty transport cURL, gdy istnieje zbiór adresów IP lub zbiór przypiętych Subject Public Key Info (SPKI) oraz dostarczono fabrykę ResponseFactory zgodną z PSR-17; w przeciwnym razie jest wysyłane przez wstrzykniętego klienta PSR-18.
7. Odpowiedź jest parsowana do CloudflareRenderResult.

Każdy wyjątek inny niż CloudflareRenderException uruchamia ścieżkę awaryjną. CloudflareRenderException (błąd HTTP lub nieprawidłowo sformułowana odpowiedź workera) jest zgłaszany ponownie bez zmian. To awaria po stronie workera, a nie awaria osiągalności, więc mostek nie przechodzi w tryb awaryjny.

Zobacz także

• /integrations/cloudflare/install/ — instalacja pakietu i klienta PSR-18.
• /integrations/cloudflare/configuration/ — każde pole konfiguracji wraz z wartością domyślną zweryfikowaną w kodzie źródłowym.
• /integrations/cloudflare/quickstart/ — pierwsze uruchamialne renderowanie.
• /integrations/cloudflare/production-usage/ — tryb awaryjny, telemetria, archiwizacja R2, ochrona API.
• /integrations/cloudflare/security-and-operations/ — szczegóły operacyjne granicy zaufania.
• /integrations/cloudflare/troubleshooting/ — tryby awarii powiązane z wyjątkami.
• /integrations/cloudflare/boot-and-discovery/ — jak mostek integruje się z frameworkiem hosta.
• /integrations/cloudflare/integration/ — sterowanie NextPDF za pośrednictwem usług Cloudflare.