NextPDF Connect — trasporto gRPC

In sintesi

Il trasporto gRPC esegue bin/nextpdf-grpc all’interno di un pool di worker gRPC RoadRunner. Espone il servizio nextpdf.connect.v1.NextPDFConnect, supporta il rendering in server-streaming, autentica tramite token bearer nei metadati della chiamata ed è configurato per il mutual TLS nel profilo di distribuzione combinato.

Installazione

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

Panoramica concettuale

Il servizio gRPC condivide gli stessi servizi applicativi del trasporto REST — render, job, sessioni, capability, operazioni — tramite il worker gRPC Spiral RoadRunner. Il contratto wire è il pacchetto Protocol Buffers nextpdf.connect.v1, definito dai file .proto distribuiti nel pacchetto.

L’autenticazione riutilizza il key store e la convalida REST. L’autenticatore gRPC legge la chiave di metadati authorization — i metadati delle chiamate gRPC sono trasportati come header HTTP/2 — analizza il token Bearer npk_live_… e convalida il kid e il digest SHA-256 con un confronto a tempo costante. L’autenticatore fa fallire la chiamata con lo stato gRPC UNAUTHENTICATED quando la chiave è assente, malformata, sconosciuta, disabilitata o scaduta. Un’autenticazione implementata in modo errato costituisce il rischio OWASP API2:2023 Broken Authentication; il confronto del digest a tempo costante contribuisce a mitigarlo.

Superficie dell’API

RPC del servizio

Il servizio nextpdf.connect.v1.NextPDFConnect espone RPC unary e server-streaming:

RPC	Forma	Scopo
Render	unary	Render sincrono
RenderStream	server-streaming	Render, trasmesso in chunk
SubmitJob / GetJobStatus / GetJobResult / CancelJob	unary	Job asincroni
GetJobResultStream	server-streaming	Risultato asincrono, trasmesso in streaming
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	unary	Sessioni con stato
SessionRenderStream	server-streaming	Render di sessione, trasmesso in streaming
ExecuteCapability / GetCapabilities	unary	Dispatch e introspezione delle capability
HealthCheck / ReadinessCheck	unary	Liveness e readiness

ExecuteCapability esegue il dispatch delle stesse operazioni soggette a gating per livello delle route di operazione REST; le operazioni Pro ed Enterprise sono raggiungibili solo quando i relativi pacchetti sono installati. Quando il dispatch riguarda la firma, NextPDF Connect con Pro fornisce esclusivamente la firma PAdES baseline-B (B-B).

Streaming

Le RPC server-streaming inviano il risultato come flusso ordinato di chunk, adatto a PDF di grandi dimensioni e alla consegna incrementale. Le RPC unary restituiscono invece il risultato completo in un unico messaggio.

Esempio di codice — Avvio rapido

Avviare il profilo solo gRPC:

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

Generare un client a partire dai proto distribuiti con la propria toolchain gRPC:

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

Impostare i metadati di call-credential authorization su Bearer npk_live_{kid}_{secret} per ogni chiamata.

Esempio di codice — Produzione

Il profilo combinato esegue gRPC con 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 questo profilo il server presenta il proprio certificato e richiede e verifica un certificato client (require_and_verify_client_cert). Riprovare l’invio idempotente di un job unary dopo una connessione interrotta è sicuro — ripetere una richiesta idempotente produce lo stesso effetto previsto di una singola richiesta (RFC 9110 §9.2.2).

Casi limite e insidie

• UNAUTHENTICATED, non uno stato HTTP. Un token errato o assente fa fallire la RPC con il codice di stato gRPC UNAUTHENTICATED, non con un 401. Lo schema bearer e il formato npk_live_ sono identici a REST.

• RESOURCE_EXHAUSTED in caso di tentativi pre-autenticazione eccessivi. I tentativi di pre-autenticazione ripetuti da una sola identità client vengono limitati e falliscono con lo stato gRPC RESOURCE_EXHAUSTED — l’analogo gRPC dell’HTTP 429 e la stessa postura anti-automazione applicata dalla superficie REST. Questo controllo è attivo per impostazione predefinita, quindi un client dovrebbe rallentare il ritmo delle richieste anziché riprovare immediatamente. Per la postura di rate-limit HTTP, vedere /connect/production-usage/.

• Il mutual TLS è una configurazione di distribuzione, non un’impostazione predefinita. Il listener gRPC richiede secret di chiave server, certificato server e CA client correttamente provisionati. Senza di essi il profilo combinato non eroga il servizio; questo è intenzionale. Generarli e ruotarli fuori banda.

• Il gating per livello si applica comunque. ExecuteCapability per un’operazione Pro o Enterprise richiede il pacchetto installato e una chiave abilitata.

• Le operazioni ad alto rischio applicano comunque il gate. Le operazioni che attivano uno strumento ApprovalRequired sono sottoposte allo stesso gate human-in-the-loop. Vedere /connect/hitl-risk-tiers/.

Prestazioni

Ogni worker gRPC gestisce una chiamata alla volta. Il pool è dimensionato indipendentemente dal pool HTTP (due worker per impostazione predefinita) ed è in genere più piccolo perché i client gRPC sono meno numerosi e più longevi. Utilizzare le RPC server-streaming per gli output di grandi dimensioni per evitare di memorizzare in buffer l’intero PDF in un unico messaggio.

Note sulla sicurezza

Eseguire il trasporto gRPC con mutual TLS su qualsiasi rete non attendibile — mai esporre un listener in chiaro. Trattare la CA client, la chiave server e il certificato server come secret montati in fase di esecuzione, mai integrati nell’immagine. L’autenticazione bearer viene applicata in aggiunta al certificato, non in sua sostituzione. Questa postura richiede una configurazione di distribuzione corretta. Vedere /connect/security-and-operations/ e /connect/deployment/.

Conformità

Dichiarazione	Fonte	reference_id
Un’autenticazione compromessa pregiudica la sicurezza dell’API	OWASP API Security Top 10, API2:2023
Le richieste idempotenti sono ritentabili dopo un errore	RFC 9110 §9.2.2

Il protocollo gRPC stesso è una specifica esterna non presente nel corpus di standard sottoposti a gating; il contratto wire di riferimento è rappresentato dalle definizioni Protocol Buffers nextpdf.connect.v1 distribuite.

Contesto commerciale

ExecuteCapability raggiunge le operazioni Pro ed Enterprise solo quando nextpdf/premium è installato insieme al server. Il trasporto, l’autenticazione e la configurazione TLS non vengono modificati dai livelli installati.

Vedere anche

• /connect/security-and-operations/ — autenticazione, mutual TLS, modello delle minacce
• /connect/deployment/ — il profilo RoadRunner combinato e i secret TLS
• /transports/mcp/ · /transports/rest/ — gli altri trasporti
• /connect/tool-catalog/ — come ExecuteCapability si mappa al catalogo
• /connect/production-usage/ — job e retry idempotente