NextPDF Connect di lingkungan produksi

Sekilas

Deployment produksi NextPDF Connect memberi Anda sejumlah kendali operasional: probe health dan readiness, jalur render sinkron dan asinkron, idempotensi, batas laju per klien dan per alamat Internet Protocol (IP), serta sesi stateful opsional. Gunakan halaman ini sebagai panduan untuk menjalankannya dengan perilaku yang dapat diprediksi.

Instalasi

composer require nextpdf/server

Gambaran konseptual

Transport Representational State Transfer (REST) merupakan pipeline middleware PHP Standards Recommendation (PSR)-15. Setiap permintaan melewati middleware secara berurutan: penetapan request-id, batas ukuran body, Cross-Origin Resource Sharing (CORS), autentikasi, otorisasi kapabilitas, pembatasan laju, idempotensi, dan timeout. Setelah itu, permintaan sampai ke handler. Transport gRPC memakai ulang layanan aplikasi yang sama di balik worker gRPC RoadRunner.

Perenderan memiliki dua jalur. Endpoint sinkron POST /api/v1/render menjalankan operasi dan mengembalikan berkas Portable Document Format (PDF) dalam respons. Job asinkron menggunakan POST /api/v1/jobs. Job segera mengembalikan job id, dan Anda dapat mengambil hasilnya nanti dari GET /api/v1/jobs/{id}/result. Job disimpan dalam store SQLite bersama, sehingga worker mana pun dapat menjawab kueri status atau hasil.

Permukaan API

Health dan readiness

endpoint	Auth	Arti
GET /healthz	tidak ada	Proses sedang berjalan
GET /readyz	tidak ada	Server siap menerima permintaan

Hubungkan /healthz ke probe liveness dan /readyz ke probe readiness. Kedua endpoint bersifat anonim, sehingga orchestrator tidak memerlukan kredensial.

Job asinkron

endpoint	Metode	Tujuan
/api/v1/jobs	POST	Kirim job render
/api/v1/jobs/{id}	GET	Status job
/api/v1/jobs/{id}/result	GET	Hasil job (PDF)
/api/v1/jobs/{id}	DELETE	Batalkan job

Sesi (opsional)

Ketika NEXTPDF_SESSIONS_ENABLED bernilai true dan alat tersedia, endpoint sesi menyediakan alur pembuatan stateful. Anda membuat sesi, menambahkan halaman, teks, gambar, tabel, dan HyperText Markup Language (HTML), mengatur huruf, lalu merender. Sesi memiliki batas per klien dan idle timeout. Secara bawaan, fitur ini nonaktif.

Contoh kode — Mulai cepat

Kirim job asinkron lalu lakukan polling untuk hasilnya:

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

Contoh kode — Produksi

Buat pengiriman yang aman dicoba ulang dengan mengirimkan kunci idempotensi:

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

Permintaan yang dikirim ulang dengan kunci idempotensi yang sama mengembalikan hasil aslinya, bukan membuat job kedua. Perilaku ini membuat pengiriman aman untuk diulang setelah terjadi kegagalan komunikasi. Ini sesuai dengan properti yang disediakan metode idempoten: mengirim permintaan yang sama lagi menghasilkan efek yang sama dengan mengirimnya satu kali (RFC 9110 §9.2.2). Karena itu, permintaan dapat dicoba ulang secara otomatis jika koneksi terputus sebelum klien membaca respons (RFC 9110 §9.2.2).

Kasus tepi dan jebakan

• Pembatasan laju memerlukan Redis agar akurat di seluruh worker. Pembatas per klien dan per IP menggunakan store yang dikonfigurasi. Dengan store in-memory dan lebih dari satu worker, setiap worker menghitung permintaan secara independen, sehingga batas efektifnya dikalikan dengan jumlah worker. Gunakan store Redis untuk setiap pool multi-worker.

• Permintaan yang terkena pembatasan mengembalikan 429. Ketika batas terlampaui, server merespons dengan 429 Too Many Requests dan header Retry-After, mengikuti semantik status pembatasan laju (RFC 6585 §4). Ikuti Retry-After; jangan langsung mencoba ulang.

• Hasil job tidak disimpan tanpa batas. Store job menghapus entri lama melalui garbage collection setelah NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Ambil hasil sebelum kedaluwarsa.

• Sesi menggunakan memori. Sebuah sesi menyimpan dokumen yang sedang dikerjakan. Batas sesi per klien dan idle timeout membatasi biaya ini. Jangan menaikkan batas tersebut tanpa menghitung kebutuhan memori untuk skenario terburuk.

Performa

Jalur sinkron menahan satu worker selama keseluruhan proses render. Untuk render besar atau lambat, gunakan jalur job asinkron. Jalur ini segera membebaskan worker, dan klien melakukan polling untuk hasilnya. Sesuaikan ukuran pool worker dengan latensi render dan konkurensi yang diamati. Pantau endpoint metrik RoadRunner.

Catatan keamanan

Setiap endpoint kecuali probe health memerlukan kunci application programming interface (API) yang valid. Tier klien menentukan operasi dan ukuran payload yang diizinkan. Klien menyediakan kunci idempotensi. Perlakukan setiap kunci sebagai nilai opaque yang unik untuk satu operasi logis. Lihat /connect/security-and-operations/.

Kepatuhan

Klaim	Sumber	reference_id
Idempoten: permintaan berulang = satu efek	RFC 9110 §9.2.2
Permintaan idempoten dapat dicoba ulang setelah kegagalan	RFC 9110 §9.2.2
429 + Retry-After untuk pembatasan laju	RFC 6585 §4

Konteks komersial

Kunci Pro dan Enterprise mendapatkan batas maksimum payload dan timeout per tier yang lebih tinggi ketika alat tersebut terpasang. Deployment bawaan menggunakan batas maksimum tier core.

Lihat juga

• /connect/deployment/ — pool worker, Redis, profil RoadRunner
• /transports/rest/ — pipeline middleware lengkap dan kontrak OpenAPI
• /connect/troubleshooting/ — mendiagnosis 401/403/413/429/5xx dan kegagalan store
• /connect/security-and-operations/ — autentikasi dan postur pembatasan laju