NextPDF Connect — Transport gRPC

Sekilas pandang

Transport gRPC menjalankan bin/nextpdf-grpc di dalam worker pool gRPC RoadRunner. Transport ini melayani layanan nextpdf.connect.v1.NextPDFConnect, mendukung render server-streaming, mengautentikasi setiap panggilan menggunakan bearer token di metadata, dan dikonfigurasi untuk mutual Transport Layer Security (TLS) pada profil deployment gabungan.

Pemasangan

composer require nextpdf/server
./vendor/bin/rr get-binary

Tinjauan konseptual

Layanan gRPC menggunakan layanan aplikasi yang sama dengan transport Representational State Transfer (REST): render, job, sesi, kapabilitas, dan operasi. Worker gRPC Spiral RoadRunner menangani panggilan tersebut. Kontrak wire-nya berupa paket Protocol Buffers nextpdf.connect.v1, yang didefinisikan dalam berkas .proto yang disertakan bersama paket.

Autentikasi menggunakan key store dan validasi yang sama dengan REST. Autentikator gRPC membaca kunci metadata authorization, yang dibawa gRPC sebagai header Hypertext Transfer Protocol version 2 (HTTP/2). Autentikator mengurai token Bearer npk_live_…, lalu memvalidasi key identifier (kid) dan digest SHA-256 dengan perbandingan constant-time. Autentikator menggagalkan panggilan dengan status gRPC UNAUTHENTICATED ketika kunci hilang, salah format, tidak dikenal, dinonaktifkan, atau kedaluwarsa. Implementasi autentikasi yang keliru merupakan risiko OWASP API2:2023 Broken Authentication; perbandingan digest constant-time memitigasi risiko tersebut.

Permukaan API

RPC layanan

Layanan nextpdf.connect.v1.NextPDFConnect mengekspos remote procedure call (RPC) unary dan server-streaming:

RPC	Bentuk	Tujuan
Render	unary	Render sinkron
RenderStream	server-streaming	Render, di-streaming dalam potongan
SubmitJob / GetJobStatus / GetJobResult / CancelJob	unary	Job asinkron
GetJobResultStream	server-streaming	Hasil asinkron, di-streaming
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	unary	Sesi stateful
SessionRenderStream	server-streaming	Render sesi, di-streaming
ExecuteCapability / GetCapabilities	unary	Dispatch dan introspeksi kapabilitas
HealthCheck / ReadinessCheck	unary	Liveness dan readiness

ExecuteCapability melakukan dispatch operasi tier-gated yang sama seperti rute operasi REST. Operasi Pro dan Enterprise hanya dapat diakses ketika paket-paket tersebut terpasang. Untuk penandatanganan, NextPDF Connect dengan Pro hanya menyediakan penandatanganan Portable Document Format (PDF) Advanced Electronic Signatures (PAdES) baseline-B (B-B).

Streaming

RPC server-streaming mengirimkan hasil sebagai aliran potongan yang berurutan, sehingga cocok untuk berkas PDF besar dan pengiriman inkremental. RPC unary mengembalikan hasil lengkap dalam satu pesan.

Contoh kode — Mulai cepat

Jalankan profil khusus gRPC:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.grpc.yaml

Hasilkan klien dari berkas .proto yang disertakan dengan toolchain gRPC Anda:

# proto/nextpdf/connect/v1/*.proto — package nextpdf.connect.v1
protoc --proto_path=proto --<lang>_out=. proto/nextpdf/connect/v1/service.proto

Untuk setiap panggilan, atur metadata call-credential authorization ke Bearer npk_live_{kid}_{secret}.

Contoh kode — Produksi

Profil gabungan menjalankan gRPC dengan mutual TLS:

export NEXTPDF_GRPC_TLS_KEY=/run/secrets/grpc-server.key
export NEXTPDF_GRPC_TLS_CERT=/run/secrets/grpc-server.crt
export NEXTPDF_GRPC_TLS_CA=/run/secrets/grpc-client-ca.crt
./vendor/bin/rr serve -c .rr.full.yaml

Dalam profil ini, server menyajikan sertifikatnya serta mensyaratkan dan memverifikasi sertifikat klien (require_and_verify_client_cert). Mengirim ulang job unary yang idempoten setelah koneksi terputus aman dilakukan: mengulangi permintaan idempoten memberikan efek yang sama seperti satu permintaan (RFC 9110 §9.2.2).

Kasus tepi dan jebakan

• UNAUTHENTICATED, bukan status HTTP. Token yang salah atau hilang membuat RPC gagal dengan kode status gRPC UNAUTHENTICATED, bukan 401. Skema bearer dan format npk_live_ identik dengan REST.

• RESOURCE_EXHAUSTED pada upaya pra-autentikasi yang berlebihan. Upaya pra-autentikasi yang berulang dari satu identitas klien akan dibatasi (throttle) dan gagal dengan status gRPC RESOURCE_EXHAUSTED. Status ini setara dengan HTTP 429 pada gRPC, dan menerapkan postur anti-otomasi yang sama dengan REST. Kontrol ini aktif secara baku, sehingga klien sebaiknya menunda (back off), bukan langsung mencoba lagi. Lihat postur rate-limit HTTP di /connect/production-usage/.

• mutual TLS adalah konfigurasi deployment, bukan setelan baku. Listener gRPC mensyaratkan secret kunci server, sertifikat server, dan certificate authority (CA) klien yang disiapkan dengan benar. Tanpa secret tersebut, profil gabungan tidak akan melayani; perilaku ini disengaja. Hasilkan dan rotasikan secret tersebut secara out of band.

• Tier gating tetap berlaku. ExecuteCapability untuk operasi Pro atau Enterprise mensyaratkan paketnya terpasang dan kunci yang berhak (entitled).

• Operasi berisiko tinggi tetap di-gate. Operasi yang memicu alat ApprovalRequired menggunakan gate human-in-the-loop yang sama. Lihat /connect/hitl-risk-tiers/.

Kinerja

Setiap worker gRPC menangani satu panggilan pada satu waktu. Ukuran pool ditentukan secara terpisah dari pool HTTP (baku dua worker) dan biasanya lebih kecil karena klien gRPC lebih sedikit dan koneksinya berlangsung lebih lama. Gunakan RPC server-streaming untuk keluaran besar agar tidak perlu mem-buffer seluruh PDF dalam satu pesan.

Catatan keamanan

Jalankan transport gRPC dengan mutual TLS pada jaringan apa pun yang tidak tepercaya; jangan pernah menggunakan listener plaintext. Perlakukan CA klien, kunci server, dan sertifikat server sebagai secret yang di-mount saat runtime, dan jangan pernah menyisipkannya ke dalam image. Autentikasi bearer diberlakukan sebagai tambahan terhadap sertifikat, bukan sebagai pengganti sertifikat. Postur ini mensyaratkan konfigurasi deployment yang benar. Lihat /connect/security-and-operations/ dan /connect/deployment/.

Kesesuaian

Klaim	Sumber	reference_id
Autentikasi yang rusak membahayakan keamanan API	OWASP API Security Top 10, API2:2023
Permintaan idempoten dapat dicoba ulang setelah kegagalan	RFC 9110 §9.2.2

Protokol gRPC itu sendiri merupakan spesifikasi eksternal di luar korpus standar yang di-gate. Definisi Protocol Buffers nextpdf.connect.v1 yang disertakan adalah kontrak wire resminya.

Konteks komersial

ExecuteCapability menjangkau operasi Pro dan Enterprise hanya ketika nextpdf/premium terpasang bersama server. Tier yang terpasang tidak mengubah konfigurasi transport, autentikasi, ataupun TLS.

Lihat juga

• /connect/security-and-operations/ — autentikasi, mutual TLS, model ancaman
• /connect/deployment/ — profil RoadRunner gabungan dan secret TLS
• /transports/mcp/ · /transports/rest/ — transport lainnya
• /connect/tool-catalog/ — cara ExecuteCapability dipetakan ke katalog
• /connect/production-usage/ — job dan percobaan ulang idempoten