NextPDF Connect — gRPC taşıması

Bir bakışta

gRPC taşıması, bin/nextpdf-grpc dosyasını bir RoadRunner gRPC işçi havuzunda çalıştırır. nextpdf.connect.v1.NextPDFConnect hizmetini sunar, sunucu akışlı işlemeyi destekler, her çağrıyı meta verilerdeki taşıyıcı belirteçle doğrular ve birleşik dağıtım profilinde karşılıklı TLS için yapılandırılır.

Kurulum

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

Kavramsal genel bakış

gRPC hizmeti, Temsili Durum Aktarımı (REST) taşımasıyla aynı uygulama hizmetlerini kullanır: işleme, işler, oturumlar, yetenekler ve işlemler. Çağrıları bir Spiral RoadRunner gRPC işçisi karşılar. Bağlantı sözleşmesi nextpdf.connect.v1 Protocol Buffers paketidir; bu paket, paketle birlikte gelen .proto dosyalarıyla tanımlanır.

Kimlik doğrulama, REST ile aynı anahtar deposunu ve doğrulama akışını kullanır. gRPC kimlik doğrulayıcısı, gRPC’nin Köprü Metni Aktarım Protokolü sürüm 2 (HTTP/2) başlıkları biçiminde taşıdığı authorization meta veri anahtarını okur. Bearer npk_live_… belirtecini ayrıştırır, ardından anahtar tanımlayıcısını (kid) ve SHA-256 özetini sabit zamanlı bir karşılaştırmayla doğrular. Anahtar eksik, hatalı biçimli, bilinmeyen, devre dışı veya süresi dolmuşsa kimlik doğrulayıcısı çağrıyı gRPC UNAUTHENTICATED durumuyla başarısız kılar. Hatalı uygulanmış kimlik doğrulama, OWASP API2:2023 Bozuk Kimlik Doğrulama riskidir; sabit zamanlı özet karşılaştırması bu riski azaltır.

API yüzeyi

Hizmet RPC’leri

Hizmet nextpdf.connect.v1.NextPDFConnect birli ve sunucu akışlı uzak yordam çağrıları (RPC’ler) sunar:

RPC	Biçim	Amaç
Render	birli	Eşzamanlı işleme
RenderStream	sunucu akışlı	İşleme, parçalar hâlinde akışla aktarılır
SubmitJob / GetJobStatus / GetJobResult / CancelJob	birli	Eşzamansız işler
GetJobResultStream	sunucu akışlı	Eşzamansız sonuç, akışla aktarılır
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	birli	Durum bilgili oturumlar
SessionRenderStream	sunucu akışlı	Oturum işlemesi, akışla aktarılır
ExecuteCapability / GetCapabilities	birli	Yetenek dağıtımı ve iç gözlem
HealthCheck / ReadinessCheck	birli	Canlılık ve hazır olma

ExecuteCapability, REST işlem yollarıyla aynı katman geçişli işlemleri dağıtır. Pro ve Enterprise işlemlerine yalnızca bu paketler kurulu olduğunda erişilebilir. İmzalama için NextPDF Connect, Pro ile yalnızca Taşınabilir Belge Biçimi (PDF) Gelişmiş Elektronik İmzalar (PAdES) temel-B (B-B) imzalamasını sağlar.

Akış

Sunucu akışlı RPC’ler, sonucu sıralı parçalardan oluşan bir akış olarak gönderir; bu, büyük PDF dosyaları ve aşamalı teslimat için uygundur. Birli RPC’ler, tüm sonucu tek bir iletide döndürür.

Kod örneği — Hızlı başlangıç

Yalnızca gRPC profilini başlatın:

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

Birlikte gelen .proto dosyalarından, gRPC araç zincirinizle bir istemci oluşturun:

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

Her çağrıda, authorization çağrı kimlik bilgisi meta verisini Bearer npk_live_{kid}_{secret} olarak ayarlayın.

Kod örneği — Üretim

Birleşik profil, gRPC’yi karşılıklı TLS ile çalıştırır:

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

Bu profilde sunucu kendi sertifikasını sunar, istemci sertifikası gerektirir ve bunu doğrular (require_and_verify_client_cert). Kesilen bir bağlantının ardından bağımsız (idempotent) birli bir iş gönderimini yeniden denemek güvenlidir: bağımsız bir isteğin yinelenmesi, tek bir isteğin amaçlanan etkisiyle aynıdır (RFC 9110 §9.2.2).

Uç durumlar ve dikkat edilecek noktalar

• UNAUTHENTICATED, HTTP durumu değil. Hatalı veya eksik bir belirteç, RPC’yi gRPC UNAUTHENTICATED durum koduyla başarısız kılar; bir 401 ile değil. Taşıyıcı şeması ve npk_live_ biçimi, REST ile aynıdır.

• Aşırı ön kimlik doğrulama denemelerinde RESOURCE_EXHAUSTED. Tek bir istemci kimliğinden yinelenen ön kimlik doğrulama denemeleri kısıtlanır ve gRPC RESOURCE_EXHAUSTED durumuyla başarısız olur. Bu durum, HTTP 429 durumunun gRPC karşılığıdır ve REST ile aynı otomasyon karşıtı yaklaşımı uygular. Bu denetim varsayılan olarak etkindir; bu nedenle istemciler hemen yeniden denemek yerine geri çekilmelidir. HTTP hız sınırlama yaklaşımı için bkz. /connect/production-usage/.

• Karşılıklı TLS bir dağıtım yapılandırmasıdır, varsayılan değildir. gRPC dinleyicisi, doğru biçimde sağlanmış sunucu anahtarı, sunucu sertifikası ve istemci sertifika yetkilisi (CA) gizli dizilerini gerektirir. Bunlar olmadan birleşik profil hizmet vermez; bu kasıtlıdır. Bunları bant dışı olarak oluşturun ve değiştirin.

• Katman geçişi yine de geçerlidir. Bir Pro veya Enterprise işlemi için ExecuteCapability, paketin kurulu olmasını ve yetkili bir anahtarı gerektirir.

• Yüksek riskli işlemlerde geçit yine uygulanır. Bir ApprovalRequired aracını çalıştıran işlemler, aynı insan-döngüde geçidinden geçer. Bkz. /connect/hitl-risk-tiers/.

Performans

Her gRPC işçisi aynı anda tek bir çağrıyı karşılar. Havuz, HTTP havuzundan bağımsız olarak boyutlandırılır (varsayılan iki işçi) ve genellikle daha küçüktür; çünkü gRPC istemcileri daha azdır ve bağlantıları daha uzun süre açık kalır. Tüm PDF’yi tek bir iletide arabelleğe almaktan kaçınmak için büyük çıktılarda sunucu akışlı RPC’leri kullanın.

Güvenlik notları

gRPC taşımasını, güvenilmeyen herhangi bir ağda karşılıklı TLS ile çalıştırın; asla düz metin dinleyici kullanmayın. İstemci CA’sını, sunucu anahtarını ve sunucu sertifikasını, asla imaja gömülmeyen, çalışma zamanında bağlanan gizli diziler olarak ele alın. Taşıyıcı kimlik doğrulaması, sertifikanın yerine değil, ona ek olarak zorunlu kılınır. Bu yaklaşım, doğru dağıtım yapılandırması gerektirir. Bkz. /connect/security-and-operations/ ve /connect/deployment/.

Uygunluk

İddia	Kaynak	reference_id
Bozuk kimlik doğrulama, API güvenliğini tehlikeye atar	OWASP API Security Top 10, API2:2023
Bağımsız (idempotent) istekler başarısızlıktan sonra yeniden denenebilir	RFC 9110 §9.2.2

gRPC protokolünün kendisi, geçide tabi standartlar kümesinin dışındaki harici bir belirtimdir. Birlikte gelen nextpdf.connect.v1 Protocol Buffers tanımları, geçerli bağlantı sözleşmesidir.

Ticari bağlam

ExecuteCapability, Pro ve Enterprise işlemlerine yalnızca sunucuyla birlikte nextpdf/premium kurulduğunda ulaşır. Kurulu katmanlar; taşıma, kimlik doğrulama veya TLS yapılandırmasını değiştirmez.

Ayrıca bkz.

• /connect/security-and-operations/ — kimlik doğrulama, karşılıklı TLS, tehdit modeli
• /connect/deployment/ — birleşik RoadRunner profili ve TLS gizli dizileri
• /transports/mcp/ · /transports/rest/ — diğer taşımalar
• /connect/tool-catalog/ — ExecuteCapability kataloğa nasıl eşlenir
• /connect/production-usage/ — işler ve bağımsız yeniden deneme