NextPDF Connect — gRPC-Transport

Auf einen Blick

Der gRPC-Transport führt bin/nextpdf-grpc in einem gRPC-Worker-Pool von RoadRunner aus. Er stellt den Dienst nextpdf.connect.v1.NextPDFConnect bereit, unterstützt Rendering per Server-Streaming, authentifiziert per Bearer-Token in den Aufrufmetadaten und ist im kombinierten Deployment-Profil für mutual TLS konfiguriert.

Installation

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

Konzeptioneller Überblick

Der gRPC-Dienst nutzt dieselben Anwendungsdienste wie der REST-Transport — Rendering, Jobs, Sessions, Capabilities, Operationen — hinter dem gRPC-Worker von Spiral RoadRunner. Der Wire-Vertrag ist das Protocol-Buffers-Paket nextpdf.connect.v1 und wird durch die .proto-Dateien definiert, die im Paket ausgeliefert werden.

Die Authentifizierung verwendet den Schlüsselspeicher und die Validierung des REST-Transports wieder. Der gRPC-Authenticator liest den Metadatenschlüssel authorization — gRPC-Aufrufmetadaten werden als HTTP/2-Header übertragen —, parst das Token Bearer npk_live_… und validiert die kid sowie den SHA-256-Digest mit einem Vergleich in konstanter Zeit. Der Authenticator lässt den Aufruf mit dem gRPC-Status UNAUTHENTICATED fehlschlagen, wenn der Schlüssel fehlt, fehlerhaft ist, unbekannt, deaktiviert oder abgelaufen ist. Falsch implementierte Authentifizierung entspricht dem Risiko OWASP API2:2023 Broken Authentication; der Digest-Vergleich in konstanter Zeit dient als Gegenmaßnahme.

API-Oberfläche

Dienst-RPCs

Der Dienst nextpdf.connect.v1.NextPDFConnect stellt unäre und Server-Streaming-RPCs bereit:

RPC	Form	Zweck
`Render`	unär	Synchrones Rendering
`RenderStream`	Server-Streaming	Rendering, in Chunks gestreamt
`SubmitJob` / `GetJobStatus` / `GetJobResult` / `CancelJob`	unär	Asynchrone Jobs
`GetJobResultStream`	Server-Streaming	Asynchrones Ergebnis, gestreamt
`CreateSession` / `GetSession` / `DestroySession` / `SessionOperation` / `SessionRender`	unär	Zustandsbehaftete Sessions
`SessionRenderStream`	Server-Streaming	Session-Rendering, gestreamt
`ExecuteCapability` / `GetCapabilities`	unär	Capability-Dispatch und Introspektion
`HealthCheck` / `ReadinessCheck`	unär	Liveness und Readiness

ExecuteCapability dispatcht dieselben stufengesteuerten Operationen wie die Operationsrouten des REST-Transports; Pro- und Enterprise-Operationen sind nur erreichbar, wenn diese Pakete installiert sind. Wenn Signieren dispatcht wird, bietet NextPDF Connect mit Pro ausschließlich das Signieren nach PAdES Baseline-B (B-B).

Streaming

Die Server-Streaming-RPCs senden das Ergebnis als geordneten Stream von Chunks, was sich für große PDFs und die inkrementelle Auslieferung eignet. Die unären RPCs geben das vollständige Ergebnis in einer einzigen Nachricht zurück.

Codebeispiel — Schnellstart

Starten Sie das reine gRPC-Profil:

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

Erzeugen Sie mit Ihrer gRPC-Toolchain einen Client aus den ausgelieferten Protos:

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

Setzen Sie bei jedem Aufruf die Call-Credential-Metadaten authorization auf Bearer npk_live_{kid}_{secret}.

Codebeispiel — Produktion

Das kombinierte Profil betreibt gRPC mit 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

In diesem Profil präsentiert der Server sein Zertifikat, verlangt ein Client-Zertifikat und verifiziert es (require_and_verify_client_cert). Eine idempotente unäre Job-Einreichung kann nach einer abgebrochenen Verbindung sicher wiederholt werden — das Wiederholen einer idempotenten Anfrage hat denselben beabsichtigten Effekt wie eine einzige Anfrage (RFC 9110 §9.2.2).

Sonderfälle und Stolperfallen

UNAUTHENTICATED, kein HTTP-Status. Ein falsches oder fehlendes Token lässt den RPC mit dem gRPC-Statuscode UNAUTHENTICATED fehlschlagen, nicht mit einem 401. Das Bearer-Schema und das Format npk_live_ sind identisch mit REST.
RESOURCE_EXHAUSTED bei übermäßigen Pre-Auth-Versuchen. Wiederholte Pre-Authentication-Versuche von einer einzelnen Client-Identität werden gedrosselt und schlagen mit dem gRPC-Status RESOURCE_EXHAUSTED fehl — dem gRPC-Pendant zu HTTP 429 und derselben Anti-Automatisierungs-Haltung, die die REST-Oberfläche anwendet. Diese Kontrolle ist standardmäßig aktiv, sodass ein Client eine Wartezeit einhalten sollte, statt sofort einen weiteren Versuch zu senden. Siehe zur HTTP-Rate-Limit-Haltung /connect/production-usage/.
mutual TLS ist eine Deployment-Konfiguration, kein Standard. Der gRPC-Listener benötigt korrekt bereitgestellte Secrets für den Serverschlüssel, das Serverzertifikat und die Client-CA. Ohne sie stellt das kombinierte Profil keinen Dienst bereit; das ist beabsichtigt. Erzeugen und rotieren Sie sie über einen separaten Prozess.
Die Stufen-Gatterung gilt weiterhin. ExecuteCapability für eine Pro- oder Enterprise-Operation setzt das installierte Paket und einen berechtigten Schlüssel voraus.
Operationen mit hohem Risiko werden weiterhin gegated. Operationen, die ein Werkzeug mit ApprovalRequired anstoßen, durchlaufen dasselbe Human-in-the-Loop-Gate. Siehe /connect/hitl-risk-tiers/.

Performance

Jeder gRPC-Worker bearbeitet jeweils einen Aufruf. Der Pool wird unabhängig vom HTTP-Pool dimensioniert (Standard: zwei Worker) und ist meist kleiner, weil gRPC-Clients seltener und langlebiger sind. Nutzen Sie die Server-Streaming-RPCs für große Ausgaben, um zu vermeiden, dass das gesamte PDF in einer einzigen Nachricht gepuffert wird.

Sicherheitshinweise

Betreiben Sie den gRPC-Transport in jedem nicht vertrauenswürdigen Netzwerk mit mutual TLS — niemals als Klartext-Listener. Behandeln Sie die Client-CA, den Serverschlüssel und das Serverzertifikat als Secrets, die zur Laufzeit gemountet und niemals in das Image eingebrannt werden. Die Bearer-Authentifizierung wird zusätzlich zum Zertifikat erzwungen, nicht an seiner Stelle. Diese Sicherheitslage erfordert eine korrekte Deployment-Konfiguration. Siehe /connect/security-and-operations/ und /connect/deployment/.

Konformität

Behauptung	Quelle	`reference_id`
Fehlerhafte Authentifizierung kompromittiert die API-Sicherheit	OWASP API Security Top 10, API2:2023
Idempotente Anfragen sind nach einem Fehler wiederholbar	RFC 9110 §9.2.2

Das gRPC-Protokoll selbst ist eine externe Spezifikation, die nicht im zugriffsbeschränkten Standards-Korpus enthalten ist; der maßgebliche Wire-Vertrag sind die ausgelieferten Protocol-Buffers-Definitionen von nextpdf.connect.v1.

Kommerzieller Kontext

ExecuteCapability erreicht Pro- und Enterprise-Operationen nur, wenn nextpdf/premium zusammen mit dem Server installiert ist. Transport, Authentifizierung und TLS-Konfiguration bleiben von den installierten Stufen unberührt.

Siehe auch

/connect/security-and-operations/ — Authentifizierung, mutual TLS, Bedrohungsmodell
/connect/deployment/ — das kombinierte RoadRunner-Profil und die TLS-Secrets
/transports/mcp/ · /transports/rest/ — die übrigen Transporte
/connect/tool-catalog/ — wie ExecuteCapability auf den Katalog abgebildet wird
/connect/production-usage/ — Jobs und idempotenter Wiederholungsversuch