NextPDF Connect — gRPC-transport

In een oogopslag

Het gRPC-transport draait bin/nextpdf-grpc in een RoadRunner-gRPC-workerpool. Het biedt de nextpdf.connect.v1.NextPDFConnect-service aan, ondersteunt server-streaming weergave, authenticeert elke aanroep met een bearer-token in de metadata en is in het gecombineerde implementatieprofiel geconfigureerd voor wederzijdse Transport Layer Security (TLS).

Installeren

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

Conceptueel overzicht

De gRPC-service gebruikt dezelfde applicatieservices als het Representational State Transfer (REST)-transport: render, jobs, sessies, capabilities en operations. Een Spiral RoadRunner-gRPC-worker verwerkt de aanroepen. Het wire-contract is het Protocol Buffers-pakket nextpdf.connect.v1, gedefinieerd door de .proto-bestanden die met het pakket worden meegeleverd.

Voor authenticatie worden dezelfde sleutelopslag en validatie gebruikt als bij REST. De gRPC-authenticator leest de metadatasleutel authorization, die gRPC meevoert als Hypertext Transfer Protocol versie 2 (HTTP/2)-headers. Hij parseert het Bearer npk_live_…-token en valideert vervolgens de sleutelidentifier (kid) en de SHA-256-digest met een vergelijking in constante tijd. De authenticator laat de aanroep mislukken met de gRPC-status UNAUTHENTICATED wanneer de sleutel ontbreekt, verkeerd is geformatteerd, onbekend is, is uitgeschakeld of is verlopen. Een onjuiste implementatie van authenticatie is het OWASP API2:2023-risico Broken Authentication; de digest-vergelijking in constante tijd beperkt dit risico.

API-oppervlak

Service-RPC’s

De nextpdf.connect.v1.NextPDFConnect-service stelt unaire en server-streaming remote procedure calls (RPC’s) beschikbaar:

RPC	Vorm	Doel
Render	unair	Synchrone weergave
RenderStream	server-streaming	Weergave, gestreamd in chunks
SubmitJob / GetJobStatus / GetJobResult / CancelJob	unair	Asynchrone jobs
GetJobResultStream	server-streaming	Asynchroon resultaat, gestreamd
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	unair	Stateful sessies
SessionRenderStream	server-streaming	Sessieweergave, gestreamd
ExecuteCapability / GetCapabilities	unair	Capability-dispatch en introspectie
HealthCheck / ReadinessCheck	unair	Liveness en readiness

ExecuteCapability dispatcht operations met dezelfde tier-gating als de REST-operation-routes. Pro- en Enterprise-operations zijn alleen bereikbaar wanneer die pakketten zijn geïnstalleerd. Voor ondertekening ondersteunt NextPDF Connect met Pro uitsluitend Portable Document Format (PDF) Advanced Electronic Signatures (PAdES) baseline-B (B-B).

Streaming

De server-streaming RPC’s verzenden het resultaat als een geordende chunkstream, geschikt voor grote PDF-bestanden en incrementele levering. Unaire RPC’s retourneren het volledige resultaat in één bericht.

Codevoorbeeld — Snelstart

Start het gRPC-only-profiel:

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

Genereer een client uit de meegeleverde .proto-bestanden met je gRPC-toolchain:

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

Stel bij elke aanroep de call-credential-metadata authorization in op Bearer npk_live_{kid}_{secret}.

Codevoorbeeld — Productie

Het gecombineerde profiel draait gRPC met wederzijdse 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

In dit profiel presenteert de server zijn certificaat en vereist en verifieert hij een clientcertificaat (require_and_verify_client_cert). Een idempotente unaire jobindiening kan na een verbroken verbinding veilig opnieuw worden geprobeerd: het herhalen van een idempotente aanvraag heeft hetzelfde beoogde effect als één aanvraag (RFC 9110 §9.2.2).

Randgevallen en valkuilen

• UNAUTHENTICATED, geen HTTP-status. Een ongeldig of ontbrekend token laat de RPC mislukken met de gRPC-statuscode UNAUTHENTICATED, niet met een 401. Het bearer-schema en het npk_live_-formaat zijn identiek aan REST.

• RESOURCE_EXHAUSTED bij te veel pre-auth-pogingen. Herhaalde pre-authenticatiepogingen vanuit één clientidentiteit worden beperkt en mislukken met de gRPC-status RESOURCE_EXHAUSTED. Deze status is het gRPC-equivalent van HTTP 429 en past hetzelfde anti-automatiseringsbeleid toe als REST. Deze maatregel is standaard actief, dus clients moeten backoff toepassen in plaats van direct opnieuw te proberen. Zie het HTTP-rate-limit-beleid in /connect/production-usage/.

• Wederzijdse TLS is een implementatieconfiguratie, geen standaardinstelling. De gRPC-listener vereist correct aangeleverde secrets voor de serversleutel, het servercertificaat en de client-certificeringsinstantie (CA). Zonder deze bedient het gecombineerde profiel geen verkeer; dit is opzettelijk. Genereer en roteer deze out-of-band.

• Tier-gating geldt nog steeds. ExecuteCapability voor een Pro- of Enterprise-operation vereist dat het pakket is geïnstalleerd en dat er een sleutel met rechten is.

• Operations met een hoog risico worden nog steeds afgeschermd. Operations die een ApprovalRequired-tool aansturen, gebruiken dezelfde human-in-the-loop-gate. Zie /connect/hitl-risk-niveaus/.

Prestaties

Elke gRPC-worker verwerkt één aanroep tegelijk. De pool wordt onafhankelijk van de HTTP-pool gedimensioneerd (standaard twee workers) en is meestal kleiner omdat er minder gRPC-clients zijn en hun verbindingen langer open blijven. Gebruik server-streaming RPC’s voor grote uitvoer om te voorkomen dat de hele PDF in één bericht wordt gebufferd.

Beveiligingsopmerkingen

Draai het gRPC-transport met wederzijdse TLS op elk niet-vertrouwd netwerk; gebruik nooit een plaintext-listener. Behandel de client-CA, de serversleutel en het servercertificaat als secrets die tijdens runtime worden gemount, nooit ingebakken in de image. Bearer-authenticatie wordt afgedwongen in aanvulling op het certificaat, niet in plaats daarvan. Deze aanpak vereist een correcte implementatieconfiguratie. Zie /connect/security-and-operations/ en /connect/deployment/.

Conformiteit

Bewering	Bron	reference_id
Gebroken authenticatie brengt de API-beveiliging in gevaar	OWASP API Security Top 10, API2:2023
Idempotente aanvragen kunnen na een storing opnieuw worden geprobeerd	RFC 9110 §9.2.2

Het gRPC-protocol zelf is een externe specificatie buiten het afgeschermde standaardencorpus. De meegeleverde nextpdf.connect.v1 Protocol Buffers-definities vormen het gezaghebbende wire-contract.

Commerciële context

ExecuteCapability bereikt Pro- en Enterprise-operations alleen wanneer nextpdf/premium naast de server is geïnstalleerd. Geïnstalleerde tiers wijzigen het transport, de authenticatie of de TLS-configuratie niet.

Zie ook

• /connect/security-and-operations/ — authenticatie, wederzijdse TLS, dreigingsmodel
• /connect/deployment/ — het gecombineerde RoadRunner-profiel en de TLS-secrets
• /transports/mcp/ · /transports/rest/ — de andere transporten
• /connect/tool-catalog/ — hoe ExecuteCapability wordt toegewezen aan de catalogus
• /connect/production-usage/ — jobs en idempotente nieuwe poging