NextPDF Cloudflare uçta işleme köprüsü — genel bakış

Bir bakışta

nextpdf/cloudflare uçta işleme için kullanılan bir köprüdür. Hypertext Markup Language (HTML) içeriği PHP uygulamanızda kalır; başsız tarayıcı ise bir Cloudflare Worker tarafından çalıştırılır. Köprü, HTML’yi Hypertext Transfer Protocol Secure (HTTPS) üzerinden Worker’a gönderir ve işlenmiş Portable Document Format (PDF) baytlarını geri alır. PHP sürecinizin içinde hiçbir başsız tarayıcı çalışmaz ve köprü, kendi yolunda yerel bir Chromium ikili dosyası bulunmasını gerektirmez.

Paket, NextPDF ekosisteminin parçasıdır ve nextpdf/core^3.0 bağımlılığına sahiptir. Bu, hat protokolü kodudur: bir JavaScript Object Notation (JSON) isteği oluşturur, girdiyi ve hedefi doğrular, isteği bir PHP Standards Recommendation 18 (PSR-18) istemcisi aracılığıyla gönderir ve yanıtı türlenmiş bir sonuç nesnesine ayrıştırır. Worker uygulaması bu paketin kapsamı dışındadır. Bu köprü, dağıttığınız Worker ile iletişim kurar.

Güven sınırı

Bu köprünün belirleyici özelliği, HTML’nin bir ağ sınırını aşarak doğrudan denetlemediğiniz bir tarayıcı motoruna ulaşmasıdır. Paketteki her güvenlik denetimi bu sınır nedeniyle vardır.

HTML, PHP sürecinden ayrılmadan önce doğrulanır (CloudflareSecurityPolicy::validate()).
Hedef Uniform Resource Locator (URL), istek gönderilmeden önce doğrulanır (CloudflareSecurityPolicy::validateWorkerUrl()), ardından time-of-check/time-of-use penceresini kapatmak için istek anında yeniden doğrulanır (assertPinsStillValid()).
Taşıma katmanı, çözümlenen Internet Protocol (IP) kümesini ve sunucu sertifikasının açık anahtarını sabitleyebilir (Transport\PinnedCurlTransport).

Bu köprüyü üretim için değerlendiriyorsanız, /integrations/cloudflare/quickstart/. sayfasından önce /integrations/cloudflare/security-and-operations/ sayfasını okuyun. Güvenlik modeli sonradan eklenmiş bir katman değildir; paketin neden bu biçimde tasarlandığını açıklar.

Ne yapar

Yetenek	Şununla desteklenir
Bir Cloudflare Worker aracılığıyla HTML’yi PDF’ye dönüştürme	`CloudflareHtmlRenderer::render()`
Erişilebilirlik yoklaması (Hypertext Transfer Protocol (HTTP) `HEAD`)	`CloudflareHtmlRenderer::isAvailable()`
Sağlayıcıdan bağımsız taşıma katmanı	PSR-18 `ClientInterface` enjeksiyonu
Girdi sıkılaştırma (boyut, base64 bombası, meta-refresh)	`CloudflareSecurityPolicy::validate()`
Server-side request forgery (SSRF) / Domain Name System (DNS) yeniden bağlama savunması	`CloudflareSecurityPolicy::validateWorkerUrl()` + `assertPinsStillValid()`
Transport Layer Security (TLS) açık anahtar sabitleme, cURL katmanında sabitlenmiş DNS	`Transport\PinnedCurlTransport`
Worker erişilemez olduğunda yerel Chrome yedeği	`Contract\LocalRendererFactoryInterface`
İkili ve JSON (base64) yanıt ayrıştırma	`CloudflareResponseParser`
Uç telemetrisi (işleme süresi, uç konumu, içerik yüksekliği)	`CloudflareRenderResult`
Bir R2 paketinden özel yazı tipleri kullanma	`CloudflareRenderPayload` (`r2FontBucket`, `fontFiles`)
Application Programming Interface (API) koruma katmanı (anahtar kimlik doğrulaması, yük boyutu, hız sınırlaması)	`ApiProtection`
S3 uyumlu API üzerinden R2’ye PDF arşivleme	`R2ArchiveManager`

Her satır, NextPDF\Cloudflare ad alanındaki bir sınıfa eşlenir. Her satır, bir belirtim belgesine göre değil, ilgili sınıfın davranışına ve testine göre doğrulanır.

Ne yapmaz

Bir tarayıcı çalıştırmaz. Worker çalıştırır.
Worker’ınızı dağıtmaz veya yapılandırmaz. Bu yapıt size aittir.
PDF’leri imzalamaz. İmzalama, nextpdf/core sürümüne veya ticari sürümlere aittir. İmzalama gerektiğinde önce işleme yapın, ardından döndürülen baytları motorla imzalayın. NextPDF Pro, PAdES B-B imzalama sağlar. Uzun vadeli doğrulama profilleri bir Enterprise yeteneğidir.
Herhangi bir Cloudflare platform kapasitesi veya sınırı öne sürmez. Bu belgelemenin belirttiği tek boyut ve süre sınırları, bu paketin kendi yapılandırması aracılığıyla zorunlu kıldığı sınırlardır (bkz. /integrations/cloudflare/configuration/).

İki güvenlik ilkesi

Köprü, birbirinden ayrı ama birbirini tamamlayan iki ilke taşır. Bunları birbirine karıştırmak en yaygın inceleme hatasıdır. Her biri aşağıda açıklanmıştır.

HTML güvenlik ilkesi (HtmlSecurityPolicyInterface, varsayılan NextPDF\Html\DefaultHtmlSecurityPolicy, nextpdf/core tarafından sağlanır): ayrıştırma katmanında içerik filtreleme yapar; içerik Worker’a ulaşmadan önce uygulanır. Bunu getHtmlSecurityPolicy() ile alın.
Cloudflare güvenlik ilkesi (CloudflareSecurityPolicy, statik): taşıma katmanı konularını kapsar: girdi boyutu, base64 açma bombası algılama, meta-refresh engelleme, HTTPS zorunlu kılma ve Worker URL’si için SSRF / DNS yeniden bağlama savunması.

İşleyicinin kendi docblock’u bu ayrımı belirtir. Bu sayfa, üretim incelemecilerinin her iki adı tek bir ekranda görmesi gerektiği için aynı ayrımı yeniden belirtir.

Uç işleme modeli

Tek bir render() çağrısı, aşağıdaki gözlemlenebilir sırayı izler. Bu sıra doğrudan CloudflareHtmlRenderer::render() kaynağından okunur.

Yapılandırmanın eksiksizliği denetlenir (workerUrl ve apiToken boş değil). Denetim başarısız olursa, köprü ya yerel bir işleyiciye geri döner ya da CloudflareNotAvailableException fırlatır.
HTML, yapılandırılmış azami boyuta, base64 URI tavanına ve meta-refresh yasağına karşı doğrulanır.
Ana makineyi çözümleyen ve incelenmiş IP kümesini döndüren Worker URL doğrulaması.
Yük oluşturma (CloudflareRenderPayload).
Kullanım anında yapılan yeniden denetim, ana makinenin DNS yanıtının 3. adımdan bu yana değişmediğini doğrular.
HTTP POST isteği, bir IP kümesi veya Subject Public Key Info (SPKI) sabit kümesi mevcut olduğunda ve bir PSR-17 ResponseFactory sağlandığında sabitlenmiş cURL taşıma katmanı aracılığıyla; aksi durumda enjekte edilen PSR-18 istemcisi aracılığıyla gönderilir.
Yanıt, bir CloudflareRenderResult nesnesine ayrıştırılır.

Fırlatılabilir herhangi bir hata — CloudflareRenderException dışında olanlar — yedek yolu tetikler. CloudflareRenderException (bir HTTP hatası veya Worker’dan gelen hatalı biçimlendirilmiş bir yanıt) değiştirilmeden yeniden fırlatılır. Bu bir erişilebilirlik hatası değil, Worker tarafındaki bir hatadır; bu nedenle köprü yedeğe geçmez.

Ayrıca bkz.

/integrations/cloudflare/install/ — paketi ve bir PSR-18 istemcisini kurun.
/integrations/cloudflare/configuration/ — kaynaktan doğrulanmış varsayılanıyla birlikte her yapılandırma alanı.
/integrations/cloudflare/quickstart/ — ilk çalıştırılabilir işlemeniz.
/integrations/cloudflare/production-usage/ — yedek, telemetri, R2 arşivleme, API koruması.
/integrations/cloudflare/security-and-operations/ — güven sınırına ilişkin işletim ayrıntıları.
/integrations/cloudflare/troubleshooting/ — istisnalarla eşleşen hata kipleri.
/integrations/cloudflare/boot-and-discovery/ — köprünün bir ana çerçeveye nasıl bağlandığı.
/integrations/cloudflare/integration/ — NextPDF uygulamasının Cloudflare hizmetleri aracılığıyla çalıştırılması.