Panduan pengembang Cloudflare

Sekilas pandang

Paket Cloudflare memindahkan perenderan Portable Document Format (PDF) ke batas Worker. Perlakukan perenderan Worker, fallback lokal, proteksi application programming interface (API), dan arsip R2 sebagai kapabilitas terpisah, masing-masing dengan penanganan kegagalannya sendiri.

Gunakan panduan ini saat Anda membangun layanan perenderan edge, endpoint perenderan terproteksi, alur kerja arsip, atau jalur fallback lokal dengan nextpdf/cloudflare.

Batas arsitektur

Lapisan	Dimiliki oleh	Tanggung jawab	Jangan letakkan di sini
endpoint aplikasi	Aplikasi	Otorisasi pemanggil, normalisasi permintaan render, dan penerapan kebijakan bisnis.	Token Worker yang ditanam di dalam kode.
Proteksi API	nextpdf/cloudflare dan aplikasi	Pemeriksaan kunci API, pemeriksaan ukuran payload, dan keputusan rate-limit dalam proses.	Penagihan, hak akses tenant, atau penegakan kuota persisten.
Perender Cloudflare	nextpdf/cloudflare	Validasi Hypertext Markup Language (HTML) dan Uniform Resource Locator (URL) Worker, pengiriman payload render, lalu penguraian responsnya.	Perenderan template atau kueri domain.
Worker	deployment aplikasi	Menjalankan Browser Rendering dan mengembalikan byte PDF atau hasil terstruktur.	Kebijakan penyimpanan sisi PHP.
Fallback lokal	deployment aplikasi	Merender saat Worker tidak tersedia.	Fallback diam-diam yang menyembunyikan gangguan operasional.
Arsip R2	nextpdf/cloudflare	Mengunggah berkas PDF, membangun kunci objek, dan membuat URL bertanda tangan.	Metadata bisnis sensitif tanpa peninjauan.

Siklus hidup runtime

Tahap	Perilaku	Tindakan pengembang
Pembuatan konfigurasi	Memuat URL Worker, token API, timeout, batas ukuran, fallback, dan pin.	Simpan rahasia dalam konfigurasi deployment.
Proteksi permintaan	ApiProtection opsional memvalidasi kunci, ukuran, dan rate limit.	Jalankan sebelum pekerjaan render yang mahal.
Pemanggilan renderer	CloudflareHtmlRenderer memvalidasi HTML dan URL Worker, lalu mengirim JavaScript Object Notation (JSON).	Tangani ketidaktersediaan Worker dan kegagalan render secara terpisah.
Penguraian respons	CloudflareResponseParser::parse() menerima keluaran PDF biner atau keluaran JSON terstruktur.	Tolak keluaran yang tidak valid atau bukan PDF.
Fallback lokal	Perender lokal opsional menangani kegagalan Worker.	Suntikkan factory renderer lokal hanya ketika host mendukungnya.
Arsip R2	R2ArchiveManager menyimpan byte PDF dan membuat URL bertanda tangan.	Pastikan metadata tetap tidak sensitif kecuali Anda sengaja menyimpannya.

Struktur aplikasi yang direkomendasikan

Path	Tujuan
app/Pdf/Cloudflare/*	Pembungkus aplikasi untuk CloudflareHtmlRenderer.
app/Pdf/Workers/*	Objek transfer data (DTO) permintaan Worker dan kebijakan spesifik endpoint.
app/Pdf/Archive/*	Orkestrasi arsip R2 dan keputusan retensi.
app/Pdf/Fallback/*	Implementasi LocalRendererFactoryInterface untuk fallback yang diizinkan.
tests/Pdf/Cloudflare/*	Pengujian untuk Worker mati, token tidak valid, payload, dan arsip.

Pisahkan token API PHP dari token Worker. PHP melakukan autentikasi ke Worker. Worker sebaiknya mengautentikasi permintaan masuk sebelum memulai pekerjaan browser.

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

Pola renderer

Bangun renderer menggunakan dependensi PHP Standards Recommendation (PSR), termasuk PSR-18 dan PSR-17, dari framework Anda. Jaga fallback lokal tetap eksplisit agar operator dapat melihat kapan sistem berhenti menggunakan 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);

Pola arsip R2

Arsipkan hanya setelah perenderan berhasil dan kebijakan menyetujui hasilnya. Perlakukan URL publik dan URL bertanda tangan sebagai keputusan terpisah.

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

Jangan letakkan nama pelanggan, alamat email, total faktur, atau pengidentifikasi teregulasi dalam metadata objek kecuali kebijakan retensi dan akses Anda secara eksplisit mengizinkannya.

Titik ekstensi

Titik ekstensi	Gunakan untuk	Batasan
LocalRendererFactoryInterface	Fallback lokal melalui Artisan atau renderer lain.	Harus mengembalikan objek yang mengimplementasikan LocalRendererInterface.
ApiProtectionConfig	Kebijakan kunci API, ukuran payload, dan rate-limit.	Batas dalam memori berlaku per proses.
ApiKeyValidator	Validasi kunci yang tahan timing attack (timing-safe) dan helper rotasi kunci.	Simpan rahasia di luar kode sumber.
R2ArchiveConfig	Bucket, kredensial, prefiks path, endpoint, dan batas ukuran.	Kredensial tidak boleh dicatat dalam log.
PinnedCurlTransport	Penegakan pin Internet Protocol (IP) dan Subject Public Key Info (SPKI).	Membutuhkan runtime berkemampuan cURL dan response factory.
CloudflareResponseParser	Penguraian respons Worker.	Menolak keluaran PDF yang tidak valid atau respons error.

Alur kerja pengembangan

1. Bangun jalur render lokal terlebih dahulu.
2. Tambahkan perenderan Worker dengan fixture HTML representatif yang kecil.
3. Aktifkan proteksi permintaan sebelum mengekspos endpoint publik.
4. Tambahkan unggahan R2 hanya setelah alur render dan respons stabil.
5. Uji jalur Worker mati, token tidak valid, payload berlebih, rate-limit, dan kegagalan R2.
6. Tambahkan log yang membedakan render Worker, render fallback, unggahan arsip, dan pembuatan URL bertanda tangan.

Penanganan kegagalan

Kegagalan	Di mana seharusnya ditangani	Respons yang direkomendasikan
Kunci API yang hilang atau tidak valid	Lapisan proteksi API.	Tolak permintaan sebelum pekerjaan render dimulai.
Payload berlebih	Validasi proteksi API atau renderer.	Kembalikan kegagalan validasi tanpa pemanggilan Worker.
URL Worker tidak aman	Kebijakan keamanan renderer.	Gagalkan konfigurasi atau permintaan sebelum input/output (I/O) jaringan.
Worker tidak tersedia	Batas renderer.	Gunakan fallback eksplisit hanya saat diizinkan; jika tidak, gagalkan dengan jelas.
Kegagalan unggahan R2	Batas arsip.	Kembalikan respons PDF jika arsip bersifat opsional; gagalkan jika arsip diwajibkan oleh kebijakan.
Kegagalan rotasi pin	deployment dan operasi.	Rotasikan dengan pin cadangan dan rencana rollback.

Nilai default yang aman

Perhatian	Default	Kapan harus menggantinya
Fallback	Aktif secara default dalam konfigurasi.	Nonaktifkan saat perenderan lokal akan melanggar isolasi deployment.
Ukuran HTML maksimum	5,000,000 byte.	Turunkan untuk endpoint publik.
Time to live (TTL) URL bertanda tangan	3600 detik.	Perpendek untuk PDF sensitif.
Kumpulan pin	Kosong.	Tambahkan pin hanya dengan rencana rotasi dan pin cadangan.
Persyaratan kunci API	Aktif secara default dalam konfigurasi proteksi.	Nonaktifkan hanya untuk panggilan internal privat yang sudah terautentikasi.

Daftar periksa pengujian

• Pengujian renderer mencakup HTML valid, HTML yang terlalu besar, URL Worker tidak valid, dan respons error Worker.
• Pengujian proteksi API mencakup kunci yang hilang, kunci tidak valid, payload yang terlalu besar, dan rate limit yang terlampaui.
• Pengujian R2 mencakup unggahan berhasil, unggahan yang terlalu besar, status Hypertext Transfer Protocol (HTTP) gagal, bucket tidak valid, dan pembuatan URL bertanda tangan.
• Pengujian fallback memverifikasi bahwa jalur renderer lokal eksplisit dan dapat diobservasi.
• Pengujian transport mencakup IP yang dipin, pin kunci publik, timeout, dan pengalihan yang dinonaktifkan oleh kebijakan.
• Pengujian observabilitas memastikan event log yang berbeda untuk render, fallback, arsip, dan pembuatan URL bertanda tangan.