NextPDF Connect — gRPC transport

At a glance

The gRPC transport runs bin/nextpdf-grpc in a RoadRunner gRPC worker pool. It serves the nextpdf.connect.v1.NextPDFConnect service, supports server-streaming render, authenticates each call with a bearer token in metadata, and is configured for mutual Transport Layer Security (TLS) in the combined deployment profile.

Install

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

Conceptual overview

The gRPC service uses the same application services as the Representational State Transfer (REST) transport: render, jobs, sessions, capabilities, and operations. A Spiral RoadRunner gRPC worker handles the calls. The wire contract is the Protocol Buffers package nextpdf.connect.v1, defined by the .proto files shipped with the package.

Authentication uses the same key store and validation as REST. The gRPC authenticator reads the authorization metadata key, which gRPC carries as Hypertext Transfer Protocol version 2 (HTTP/2) headers. It parses the Bearer npk_live_… token, then validates the key identifier (kid) and the SHA-256 digest with a constant-time comparison. The authenticator fails the call with the gRPC UNAUTHENTICATED status when the key is missing, malformed, unknown, disabled, or expired. Incorrect authentication implementation is the OWASP API2:2023 Broken Authentication risk; the constant-time digest comparison mitigates it.

API surface

Service RPCs

The nextpdf.connect.v1.NextPDFConnect service exposes unary and server-streaming remote procedure calls (RPCs):

RPC	Shape	Purpose
`Render`	unary	Synchronous render
`RenderStream`	server-streaming	Render, streamed in chunks
`SubmitJob` / `GetJobStatus` / `GetJobResult` / `CancelJob`	unary	Async jobs
`GetJobResultStream`	server-streaming	Async result, streamed
`CreateSession` / `GetSession` / `DestroySession` / `SessionOperation` / `SessionRender`	unary	Stateful sessions
`SessionRenderStream`	server-streaming	Session render, streamed
`ExecuteCapability` / `GetCapabilities`	unary	Capability dispatch and introspection
`HealthCheck` / `ReadinessCheck`	unary	Liveness and readiness

ExecuteCapability dispatches the same tier-gated operations as the REST operation routes. Pro and Enterprise operations are reachable only when those packages are installed. For signing, NextPDF Connect with Pro provides Portable Document Format (PDF) Advanced Electronic Signatures (PAdES) baseline-B (B-B) signing only.

Streaming

The server-streaming RPCs send the result as an ordered chunk stream, which suits large PDF files and incremental delivery. Unary RPCs return the full result in one message.

Code sample — Quick start

Start the gRPC-only profile:

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

Generate a client from the shipped .proto files with your gRPC toolchain:

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

On every call, set the authorization call-credential metadata to Bearer npk_live_{kid}_{secret}.

Code sample — Production

The combined profile runs gRPC with 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 this profile, the server presents its certificate and requires and verifies a client certificate (require_and_verify_client_cert). A retry of an idempotent unary job submission after a dropped connection is safe: repeating an idempotent request has the same intended effect as one request (RFC 9110 §9.2.2).

Edge cases and gotchas

UNAUTHENTICATED, not an HTTP status. A bad or missing token fails the RPC with the gRPC UNAUTHENTICATED status code, not a 401. The bearer scheme and npk_live_ format are identical to REST.
RESOURCE_EXHAUSTED on excessive pre-auth attempts. Repeated pre-authentication attempts from one client identity are throttled and fail with the gRPC RESOURCE_EXHAUSTED status. This status is the gRPC equivalent of HTTP 429, and it applies the same anti-automation posture as REST. This control is active by default, so clients should back off instead of retrying immediately. See the HTTP rate-limit posture in /connect/production-usage/.
mutual TLS is a deployment configuration, not a default. The gRPC listener requires correctly provisioned server key, server certificate, and client certificate authority (CA) secrets. Without them, the combined profile will not serve; this is intentional. Generate and rotate them out of band.
Tier gating still applies. ExecuteCapability for a Pro or Enterprise operation requires the package to be installed and an entitled key.
High-risk operations still gate. Operations that drive an ApprovalRequired tool use the same human-in-the-loop gate. See /connect/hitl-risk-tiers/.

Performance

Each gRPC worker handles one call at a time. The pool is sized independently of the HTTP pool (default two workers) and is usually smaller because there are fewer gRPC clients, and their connections last longer. Use server-streaming RPCs for large outputs to avoid buffering the whole PDF in one message.

Security notes

Run the gRPC transport with mutual TLS on any untrusted network; never use a plaintext listener. Treat the client CA, server key, and server certificate as secrets mounted at runtime, never baked into the image. Bearer authentication is enforced in addition to the certificate, not instead of it. This posture requires correct deployment configuration. See /connect/security-and-operations/ and /connect/deployment/.

Conformance

Claim	Source	`reference_id`
Broken authentication compromises API security	OWASP API Security Top 10, API2:2023
Idempotent requests retryable after failure	RFC 9110 §9.2.2

The gRPC protocol itself is an external specification outside the gated standards corpus. The shipped nextpdf.connect.v1 Protocol Buffers definitions are the wire contract of record.

Commercial context

ExecuteCapability reaches Pro and Enterprise operations only when nextpdf/premium is installed alongside the server. Installed tiers do not change the transport, authentication, or TLS configuration.