NextPDF Connect — transport gRPC

W skrócie

Transport gRPC uruchamia bin/nextpdf-grpc w puli procesów roboczych gRPC RoadRunner. Udostępnia usługę nextpdf.connect.v1.NextPDFConnect, wspiera renderowanie strumieniowane po stronie serwera, uwierzytelnia każde wywołanie tokenem bearer w metadanych i jest skonfigurowany do wzajemnego zabezpieczenia warstwy transportowej (TLS) w połączonym profilu wdrożenia.

Instalacja

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

Przegląd koncepcyjny

Usługa gRPC korzysta z tych samych usług aplikacyjnych co transport Representational State Transfer (REST): renderowania, zadań, sesji, możliwości oraz operacji. Wywołania obsługuje proces roboczy gRPC Spiral RoadRunner. Kontrakt transmisji stanowi pakiet Protocol Buffers nextpdf.connect.v1, zdefiniowany w plikach .proto dostarczanych z pakietem.

Uwierzytelnianie używa tego samego magazynu kluczy i tej samej walidacji co REST. Mechanizm uwierzytelniania gRPC odczytuje klucz metadanych authorization, przenoszony przez gRPC jako nagłówki Hypertext Transfer Protocol version 2 (HTTP/2). Parsuje token Bearer npk_live_…, a następnie weryfikuje identyfikator klucza (kid) oraz skrót SHA-256 za pomocą porównania o stałym czasie. Mechanizm uwierzytelniania odrzuca wywołanie ze statusem gRPC UNAUTHENTICATED, gdy klucza brakuje, ma nieprawidłowy format, jest nieznany, wyłączony lub wygasły. Nieprawidłowo zaimplementowane uwierzytelnianie stanowi zagrożenie OWASP API2:2023 Broken Authentication; porównanie skrótu o stałym czasie ogranicza to ryzyko.

Powierzchnia API

Wywołania RPC usługi

Usługa nextpdf.connect.v1.NextPDFConnect udostępnia zdalne wywołania procedur (RPC): jednoargumentowe (unary) oraz strumieniowane po stronie serwera:

RPC	Postać	Przeznaczenie
Render	jednoargumentowe	Renderowanie synchroniczne
RenderStream	strumieniowane po stronie serwera	Renderowanie strumieniowane we fragmentach
SubmitJob / GetJobStatus / GetJobResult / CancelJob	jednoargumentowe	Zadania asynchroniczne
GetJobResultStream	strumieniowane po stronie serwera	Wynik asynchroniczny, strumieniowany
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	jednoargumentowe	Sesje stanowe
SessionRenderStream	strumieniowane po stronie serwera	Renderowanie sesji, strumieniowane
ExecuteCapability / GetCapabilities	jednoargumentowe	Wysyłanie i introspekcja możliwości
HealthCheck / ReadinessCheck	jednoargumentowe	Stan działania i gotowość

ExecuteCapability przekazuje do wykonania te same operacje ograniczone poziomem subskrypcji co trasy operacji REST. Operacje Pro i Enterprise są dostępne tylko wtedy, gdy odpowiednie pakiety są zainstalowane. W obszarze podpisywania NextPDF Connect z pakietem Pro zapewnia wyłącznie podpisywanie Portable Document Format (PDF) Advanced Electronic Signatures (PAdES) baseline-B (B-B).

Strumieniowanie

Wywołania RPC strumieniowane po stronie serwera wysyłają wynik jako uporządkowany strumień fragmentów, co dobrze sprawdza się w przypadku dużych plików PDF oraz dostarczania przyrostowego. Wywołania RPC jednoargumentowe zwracają pełny wynik w jednym komunikacie.

Przykład kodu — szybki start

Uruchom profil obsługujący wyłącznie gRPC:

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

Wygeneruj klienta z dostarczonych plików .proto, używając własnego zestawu narzędzi gRPC:

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

Dla każdego wywołania ustaw metadane poświadczeń authorization na Bearer npk_live_{kid}_{secret}.

Przykład kodu — środowisko produkcyjne

Połączony profil uruchamia gRPC ze wzajemnym 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

W tym profilu serwer przedstawia własny certyfikat oraz wymaga certyfikatu klienta i go weryfikuje (require_and_verify_client_cert). Bezpiecznie jest ponowić idempotentne, jednoargumentowe przesłanie zadania po zerwaniu połączenia: powtórzenie idempotentnego żądania ma taki sam zamierzony efekt jak pojedyncze żądanie (RFC 9110 §9.2.2).

Przypadki brzegowe i pułapki

• UNAUTHENTICATED, a nie status HTTP. Nieprawidłowy token albo jego brak powoduje odrzucenie RPC z kodem statusu gRPC UNAUTHENTICATED, a nie 401. Schemat bearer i format npk_live_ są identyczne jak w REST.

• RESOURCE_EXHAUSTED przy nadmiernej liczbie prób przed uwierzytelnieniem. Powtarzane próby przed uwierzytelnieniem z jednej tożsamości klienta podlegają ograniczaniu przepustowości i kończą się statusem gRPC RESOURCE_EXHAUSTED. Status ten jest odpowiednikiem gRPC kodu HTTP 429 i stosuje to samo podejście antyautomatyzacyjne co REST. Mechanizm ten jest domyślnie aktywny, dlatego klienci powinni odczekać zamiast natychmiast ponawiać próby. Zobacz zasady ograniczania przepustowości HTTP w /connect/production-usage/.

• Wzajemny TLS jest konfiguracją wdrożenia, a nie ustawieniem domyślnym. Nasłuch gRPC wymaga prawidłowo dostarczonych sekretów: klucza serwera, certyfikatu serwera oraz urzędu certyfikacji klienta (CA). Bez nich połączony profil nie będzie obsługiwał żądań; jest to zamierzone. Generuj je i rotuj poza pasmem.

• Ograniczenia poziomu subskrypcji nadal obowiązują. ExecuteCapability dla operacji Pro lub Enterprise wymaga zainstalowanego pakietu oraz uprawnionego klucza.

• Operacje wysokiego ryzyka nadal podlegają bramkowaniu. Operacje uruchamiające narzędzie ApprovalRequired nadal przechodzą przez tę samą bramkę z udziałem człowieka w pętli. Zobacz /connect/hitl-risk-tiers/.

Wydajność

Każdy proces roboczy gRPC obsługuje jedno wywołanie naraz. Rozmiar puli ustala się niezależnie od puli HTTP (domyślnie dwa procesy robocze) i zwykle jest on mniejszy, ponieważ klientów gRPC jest mniej, a ich połączenia trwają dłużej. Przy dużych wynikach używaj wywołań RPC strumieniowanych po stronie serwera, aby uniknąć buforowania całego pliku PDF w jednym komunikacie.

Uwagi dotyczące bezpieczeństwa

Uruchamiaj transport gRPC ze wzajemnym TLS w każdej niezaufanej sieci; nigdy nie używaj nasłuchu bez szyfrowania. Traktuj CA klienta, klucz serwera oraz certyfikat serwera jako sekrety montowane w czasie wykonywania, nigdy jako elementy wbudowane w obraz. Uwierzytelnianie bearer jest wymuszane jako uzupełnienie certyfikatu, a nie zamiast niego. Takie podejście wymaga prawidłowej konfiguracji wdrożenia. Zobacz /connect/security-and-operations/ oraz /connect/deployment/.

Zgodność

Deklaracja	Źródło	reference_id
Złamane uwierzytelnianie narusza bezpieczeństwo API	OWASP API Security Top 10, API2:2023
Idempotentne żądania można ponawiać po niepowodzeniu	RFC 9110 §9.2.2

Sam protokół gRPC jest specyfikacją zewnętrzną, spoza korpusu standardów objętego bramkami. Dostarczone definicje Protocol Buffers nextpdf.connect.v1 stanowią obowiązujący kontrakt transmisji.

Kontekst komercyjny

ExecuteCapability ma dostęp do operacji Pro i Enterprise tylko wtedy, gdy obok serwera zainstalowano nextpdf/premium. Zainstalowane poziomy subskrypcji nie zmieniają transportu, uwierzytelniania ani konfiguracji TLS.

Zobacz także

• /connect/security-and-operations/ — uwierzytelnianie, wzajemny TLS, model zagrożeń
• /connect/deployment/ — połączony profil RoadRunner i sekrety TLS
• /transports/mcp/ · /transports/rest/ — pozostałe transporty
• /connect/tool-catalog/ — jak ExecuteCapability odwzorowuje się w katalogu
• /connect/production-usage/ — zadania i idempotentne ponawianie