NextPDF Gotenberg dalam lingkungan produksi

Sekilas

Bridge menjalankan satu round trip Hypertext Transfer Protocol (HTTP) secara sinkron dan memvalidasi hasilnya. Bridge tidak menangani percobaan ulang, antrean, cache, maupun pembatasan laju. Tempatkan perilaku tersebut di aplikasi yang membungkus bridge. Halaman ini menjelaskan pembagian tanggung jawab dan jaminan yang diberikan bridge, sehingga Anda dapat membangun selebihnya dengan benar.

Perlakukan setiap konversi sebagai panggilan jarak jauh ke layanan yang Anda operasikan, tetapi tidak Anda kendalikan secara in-process. Rancang alurnya untuk menghadapi latensi dan kegagalan layanan tersebut.

Mengambil konfigurasi dan secret

GotenbergConfig menyimpan Uniform Resource Locator (URL) untuk application programming interface (API) dan, ketika autentikasi diaktifkan, sebuah bearer token. Field token ditandai dengan #[\SensitiveParameter], sehingga nilainya disensor di stack trace. Anda tetap bertanggung jawab untuk memuatnya secara aman.

• Muat token dari secret manager Anda atau dari nilai environment yang disuntikkan saat proses dimulai. Jangan meng-commit token tersebut, dan jangan menaruhnya dalam berkas konfigurasi yang ikut dikirim di dalam image.
• Buat konfigurasi sekali per cakupan permintaan atau sekali per worker, bukan per konversi. Konfigurasi bersifat immutable dan ringan untuk disimpan.
• GotenbergConfig::fromArray() secara sengaja menerima input yang bentuknya salah dan diam-diam menggantinya dengan nilai standar. Di lingkungan produksi, validasi array sumber sebelum Anda memanggil fromArray(). Dengan begitu, URL yang hilang muncul sebagai kesalahan konfigurasi saat boot, bukan belakangan sebagai exception Invalid Gotenberg configuration: apiUrl is empty pada setiap konversi.

Timeout

timeout (detik, standar 30) adalah batas waktu transfer keras yang diterapkan oleh transport yang di-pin ke cURL. Konversi Office melalui LibreOffice tidak instan; dokumen yang besar atau kompleks membutuhkan waktu lebih lama. Tetapkan timeout berdasarkan latensi konversi terukur untuk dokumen nyata Anda, dengan margin tambahan. Pastikan nilainya tetap di bawah timeout gateway hulu mana pun atau max_execution_time runtime PHP. Dengan begitu, bridge akan mencapai timeout lebih dahulu dan menghasilkan exception bertipe, bukan proses yang dihentikan paksa.

Jika Anda menggunakan jalur klien PHP Standard Recommendation 18 (PSR-18) yang disuntikkan (tanpa responseFactory yang disuntikkan, atau URL Internet Protocol (IP) telanjang tanpa pin), bridge tidak menerapkan nilai timeout ke klien tersebut. Konfigurasikan timeout pada klien PSR-18 juga agar kedua transport tetap memiliki batas waktu.

Percobaan ulang

Bridge mengirim tepat satu permintaan per panggilan dan tidak pernah mencoba ulang. Tambahkan logika percobaan ulang di sisi pemanggil, dan pastikan percobaan tersebut aman:

• Coba ulang hanya kegagalan tingkat transport (sebuah GotenbergConvertException yang penyebabnya adalah exception klien PSR-18) dan kesalahan server yang idempoten (HTTP 502, 503, 504). Jangan mencoba ulang setiap GotenbergConvertException tanpa seleksi. Respons kelas 400 biasanya berarti inputnya salah, sehingga percobaan ulang yang sama akan gagal dengan cara yang sama.
• Gunakan exponential backoff terbatas dengan jitter. Ketika layanan konversi yang sedang kelebihan beban mengembalikan 503, mengirim permintaan terus-menerus hanya memperparah gangguan.
• Batasi jumlah total percobaan dan total wall time. Konversi sudah lambat, sehingga percobaan ulang yang tidak terbatas melipatgandakan tail latency.
• Validasi ulang berjalan secara otomatis: setiap panggilan yang dicoba ulang menjalankan kembali validasi URL dan pemeriksaan ulang alamat, sehingga percobaan ulang tidak dapat tanpa sengaja melewati perlindungan server-side request forgery (SSRF).

Konkurensi dan kapasitas

Setiap konversi menahan satu koneksi dan satu worker LibreOffice di sisi Gotenberg sampai permintaan selesai. Bridge itu sendiri bersifat stateless dan aman digunakan oleh banyak worker secara bersamaan. Namun, layanan Gotenberg tetap memiliki kapasitas konversi yang terbatas.

• Batasi jumlah konversi yang sedang berjalan di sisi Anda (dengan antrean, semaphore, atau worker pool) sesuai kapasitas yang dapat ditopang Gotenberg. Penentuan kapasitas bergantung pada deployment Gotenberg Anda, bukan pada paket ini; lihat /integrations/gotenberg/security-and-operations/.
• Batas ukuran input (maxFileSize, standar 50 MiB) adalah satu-satunya batas sumber daya bawaan bridge. Bridge menerapkannya secara in-process sebelum permintaan dikirim, sehingga berkas berukuran berlebih tidak pernah menghabiskan kapasitas layanan. Turunkan nilainya agar sesuai dengan kebutuhan dokumen Anda yang sebenarnya; batas yang lebih kecil adalah kontrol denial-of-service yang lebih murah daripada batas yang lebih besar.
• Tidak ada caching in-process. Jika Anda mengonversi dokumen yang sama berulang kali, simpan Portable Document Format (PDF) yang dihasilkan dalam cache di aplikasi Anda, dengan kunci berupa hash konten dari input.

Observabilitas

Suntikkan logger PHP Standard Recommendation 3 (PSR-3) untuk menghasilkan satu entri debug bagi setiap permintaan konversi. Entri tersebut berisi URL permintaan, nama berkas, format yang terdeteksi, dan panjang konten permintaan. Entri tersebut tidak berisi isi berkas maupun bearer token.

• Ubah sinyal tersebut menjadi metrik: hitung konversi berdasarkan format dan hasil, serta catat wall time di sekitar setiap panggilan convertFile() / convertString() sebagai histogram latensi. Bridge sendiri tidak memancarkan metrik.
• Objek hasil menyediakan field renderTimeMs. Nilainya adalah 0.0 kecuali jika integrasi Anda mengukur dan menetapkannya; bridge tidak mengisinya dari respons Gotenberg. Ukur sendiri waktu panggilan jika Anda membutuhkan nilainya.
• Catat exception beserta tipenya. Tipe exception adalah sinyal utama tentang penyebab kegagalan; lihat /integrations/gotenberg/troubleshooting/ untuk katalognya.
• Lakukan probe isAvailable() dari endpoint readiness atau health Anda, bukan pada setiap konversi. Probe tersebut mengirim HEAD ke /health. Menjalankannya sebelum setiap konversi menggandakan laju permintaan Anda terhadap layanan tanpa manfaat apa pun.

Kontrak penanganan kegagalan

Bridge memunculkan kegagalan sebagai exception bertipe dan tidak pernah mengembalikan hasil yang parsial atau belum tervalidasi. Bridge menjamin hal-hal berikut:

• Status selain 200, sebuah Content-Type tanpa application/pdf, atau body yang tidak diawali dengan %PDF memunculkan GotenbergConvertException. Bridge mengembalikan objek hasil hanya ketika ketiga pemeriksaan lulus.
• Kegagalan klien PSR-18 (termasuk kegagalan jaringan atau timeout) dibungkus sebagai GotenbergConvertException, dengan exception asli sebagai penyebabnya dan kode klien sebagai kode exception.
• Kegagalan validasi (URL non-HTTPS, alamat private/reserved, input berukuran berlebih, nama berkas tidak aman) memunculkan RuntimeException sebelum ada lalu lintas jaringan apa pun.
• Ekstensi berkas yang tidak dikenali memunculkan ValueError sebelum ada lalu lintas jaringan apa pun.

Tangkap tipe yang spesifik. Program contoh di examples/convert-office-to-pdf.php menunjukkan urutan catch yang lengkap. /integrations/gotenberg/troubleshooting/ menjelaskan setiap pemicunya.

Batasan pascapemrosesan

Bridge menghasilkan sebuah PDF lalu berhenti. Pipeline produksi yang umum adalah:

1. Konversikan dokumen Office dengan bridge ini.
2. Muat byte hasilnya ke dalam dokumen NextPDF.
3. Terapkan pascapemrosesan: penyusunan halaman, pemberian tanda air, konversi Portable Document Format/Archive (PDF/A), dan tanda tangan digital.

Langkah 3 merupakan tanggung jawab NextPDF, bukan bridge. nextpdf/premium menyediakan penandatanganan, profil PDF/A, dan pemberian tanda air. Pertahankan konversi dan pascapemrosesan sebagai tahap yang terpisah agar Anda dapat mendiagnosis kegagalan konversi secara independen dari kegagalan penandatanganan.

Dukungan PDF Advanced Electronic Signatures (PAdES) pada edisi Pro hanya mencakup baseline B-B. Dukungan ini tidak menyediakan B-T, B-LT, maupun B-LTA, dan profil-profil tersebut tidak otomatis tercakup hanya dengan mengonversi dokumen melalui bridge ini. Kapabilitas validasi jangka panjang merupakan tanggung jawab edisi yang terpisah dan berada di luar cakupan paket ini.

Lihat juga

• /integrations/gotenberg/configuration/ - aturan pemilihan transport dan model pin.
• /integrations/gotenberg/security-and-operations/ - deployment dan pengerasan dependensi Gotenberg.
• /integrations/gotenberg/troubleshooting/ - katalog exception.
• /integrations/gotenberg/integration/ - menghubungkan PDF hasil konversi ke pipeline NextPDF.