Ikhtisar jembatan rendering edge NextPDF Cloudflare

Sekilas pandang

nextpdf/cloudflare adalah jembatan rendering edge. Aplikasi PHP Anda memegang Hypertext Markup Language (HTML), sedangkan Cloudflare Worker memegang peramban headless. Jembatan ini mengirim HTML ke Worker melalui Hypertext Transfer Protocol Secure (HTTPS) dan menerima bita Portable Document Format (PDF) hasil render. Tidak ada peramban headless yang berjalan di dalam proses PHP Anda, dan jembatan ini tidak memerlukan biner Chromium lokal di jalur yang dikelolanya.

Paket ini merupakan bagian dari ekosistem NextPDF dan bergantung pada nextpdf/core^3.0. Ini adalah kode protokol jaringan: paket ini menyusun permintaan JavaScript Object Notation (JSON), memvalidasi masukan dan tujuan, mengirim permintaan melalui klien PHP Standards Recommendation 18 (PSR-18), lalu mengurai respons menjadi objek hasil yang bertipe. Implementasi Worker berada di luar paket ini. Jembatan ini berkomunikasi dengan Worker yang Anda terapkan.

Batas kepercayaan

Ciri pembeda jembatan ini adalah HTML melintasi batas jaringan dan mencapai mesin peramban yang tidak Anda kendalikan secara langsung. Setiap kontrol keamanan dalam paket ini ada karena batas tersebut.

• HTML divalidasi sebelum meninggalkan proses PHP (CloudflareSecurityPolicy::validate()).
• Uniform Resource Locator (URL) tujuan divalidasi sebelum permintaan dikirim (CloudflareSecurityPolicy::validateWorkerUrl()), lalu divalidasi ulang saat permintaan dibuat untuk menutup jendela time-of-check/time-of-use (assertPinsStillValid()).
• Transport dapat menyematkan kumpulan Internet Protocol (IP) hasil resolusi dan kunci publik sertifikat server (Transport\PinnedCurlTransport).

Jika Anda mengevaluasi jembatan ini untuk produksi, baca /integrations/cloudflare/security-and-operations/ sebelum /integrations/cloudflare/quickstart/. Model keamanan bukan pelengkap; model ini menjelaskan mengapa paket ini dibentuk seperti ini.

Apa yang dilakukannya

Kapabilitas	Didukung oleh
Merender HTML menjadi PDF melalui Cloudflare Worker	CloudflareHtmlRenderer::render()
Pemeriksaan keterjangkauan (Hypertext Transfer Protocol (HTTP) HEAD)	CloudflareHtmlRenderer::isAvailable()
Transport netral vendor	Injeksi ClientInterface PSR-18
Pengetatan masukan (ukuran, base64 bomb, meta-refresh)	CloudflareSecurityPolicy::validate()
Pertahanan terhadap server-side request forgery (SSRF) / rebinding Domain Name System (DNS)	CloudflareSecurityPolicy::validateWorkerUrl() + assertPinsStillValid()
Penyematan kunci publik Transport Layer Security (TLS) dan DNS pada lapisan cURL	Transport\PinnedCurlTransport
Cadangan Chrome lokal saat Worker tidak terjangkau	Contract\LocalRendererFactoryInterface
Penguraian respons biner dan JSON (base64)	CloudflareResponseParser
Telemetri edge (waktu render, lokasi edge, tinggi konten)	CloudflareRenderResult
Fon kustom dari bucket R2	CloudflareRenderPayload (r2FontBucket, fontFiles)
Lapisan proteksi Application Programming Interface (API) (autentikasi kunci, ukuran payload, pembatasan laju)	ApiProtection
Pengarsipan PDF ke R2 melalui API yang kompatibel dengan S3	R2ArchiveManager

Setiap baris dipetakan ke sebuah kelas dalam namespace NextPDF\Cloudflare. Setiap baris diverifikasi terhadap perilaku kelas tersebut beserta pengujiannya, bukan terhadap dokumen spesifikasi.

Apa yang tidak dilakukannya

• Jembatan ini tidak menjalankan peramban. Worker yang menjalankannya.
• Jembatan ini tidak menerapkan atau mengonfigurasi Worker Anda. Artefak tersebut milik Anda.
• Jembatan ini tidak menandatangani PDF. Penandatanganan merupakan tugas nextpdf/core atau edisi komersial. Ketika Anda memerlukan penandatanganan, render terlebih dahulu, lalu tanda tangani bita yang dikembalikan menggunakan mesin tersebut. NextPDF Pro menyediakan penandatanganan PAdES B-B. Profil validasi jangka panjang merupakan kapabilitas Enterprise.
• Jembatan ini tidak menyatakan kapasitas atau batas platform Cloudflare apa pun. Satu-satunya batas ukuran dan waktu yang dinyatakan dalam dokumentasi ini adalah batas yang ditegakkan paket ini melalui konfigurasinya sendiri (lihat /integrations/cloudflare/configuration/).

Dua kebijakan keamanan

Jembatan ini membawa dua kebijakan yang berbeda dan saling melengkapi. Mencampuradukkannya adalah kesalahan tinjauan yang paling umum. Berikut masing-masingnya.

• Kebijakan keamanan HTML (HtmlSecurityPolicyInterface, standar NextPDF\Html\DefaultHtmlSecurityPolicy, disediakan oleh nextpdf/core): penyaringan konten pada lapisan penguraian, diterapkan sebelum konten mencapai Worker. Ambil kebijakan tersebut dengan getHtmlSecurityPolicy().
• Kebijakan keamanan Cloudflare (CloudflareSecurityPolicy, statis): aspek lapisan transport: ukuran masukan, deteksi base64 decompression-bomb, pemblokiran meta-refresh, penegakan HTTPS, serta pertahanan SSRF / DNS-rebinding untuk URL Worker.

Docblock renderer sendiri menyatakan pemisahan ini. Halaman ini menyatakannya kembali karena peninjau produksi perlu melihat kedua nama tersebut dalam satu layar.

Model rendering edge

Satu panggilan render() mengikuti urutan berikut yang dapat diamati. Urutan ini dibaca langsung dari CloudflareHtmlRenderer::render().

1. Pemeriksaan kelengkapan konfigurasi (workerUrl dan apiToken tidak kosong). Jika pemeriksaan gagal, jembatan ini beralih ke renderer lokal atau melempar CloudflareNotAvailableException.
2. Validasi HTML terhadap ukuran maksimum yang dikonfigurasi, batas atas URI base64, dan larangan meta-refresh.
3. Validasi URL Worker, yang meresolusi host dan mengembalikan kumpulan IP yang telah diperiksa.
4. Konstruksi payload (CloudflareRenderPayload).
5. Pemeriksaan ulang saat penggunaan memastikan bahwa jawaban DNS host belum berubah sejak langkah 3.
6. HTTP POST dikirim melalui transport cURL tersemat ketika terdapat kumpulan IP atau kumpulan pin Subject Public Key Info (SPKI) dan sebuah ResponseFactory PSR-17 disediakan; jika tidak, permintaan dikirim melalui klien PSR-18 yang diinjeksikan.
7. Respons diurai menjadi sebuah CloudflareRenderResult.

Throwable apa pun selain CloudflareRenderException memicu jalur cadangan. CloudflareRenderException (kesalahan HTTP atau respons Worker yang cacat) dilempar ulang tanpa perubahan. Ini adalah kegagalan di sisi Worker, bukan kegagalan keterjangkauan; karena itu jembatan ini tidak beralih ke cadangan.

Lihat juga

• /integrations/cloudflare/install/ — memasang paket dan klien PSR-18.
• /integrations/cloudflare/configuration/ — setiap bidang konfigurasi, beserta nilai standarnya yang terverifikasi dari sumber.
• /integrations/cloudflare/quickstart/ — render pertama yang dapat Anda jalankan.
• /integrations/cloudflare/production-usage/ — cadangan, telemetri, pengarsipan R2, proteksi API.
• /integrations/cloudflare/security-and-operations/ — detail operasional batas kepercayaan.
• /integrations/cloudflare/troubleshooting/ — mode kegagalan yang dipetakan ke eksepsi.
• /integrations/cloudflare/boot-and-discovery/ — bagaimana jembatan ini terhubung ke framework host.
• /integrations/cloudflare/integration/ — menjalankan NextPDF melalui layanan Cloudflare.