NextPDF Connect — transport gRPC

En bref

Le transport gRPC exécute bin/nextpdf-grpc au sein d’un pool de workers gRPC RoadRunner. Il expose le service nextpdf.connect.v1.NextPDFConnect, prend en charge le rendu en diffusion serveur, authentifie les appels au moyen d’un jeton bearer dans les métadonnées d’appel et se configure avec TLS mutuel dans le profil de déploiement combiné.

Installation

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

Vue d’ensemble conceptuelle

Le service gRPC partage les mêmes services applicatifs que le transport REST — rendu, jobs, sessions, capacités, opérations — via le worker gRPC Spiral RoadRunner. Le contrat de transmission repose sur le paquet Protocol Buffers nextpdf.connect.v1, défini par les fichiers .proto livrés avec le paquet.

L’authentification reprend le magasin de clés et la validation du transport REST. L’authentificateur gRPC lit la métadonnée authorization — les métadonnées d’appel gRPC sont transportées sous forme d’en-têtes HTTP/2 —, analyse le jeton Bearer npk_live_… et valide le kid et le condensé SHA-256 par une comparaison à temps constant. L’authentificateur fait échouer l’appel avec le statut gRPC UNAUTHENTICATED lorsque la clé est absente, malformée, inconnue, désactivée ou expirée. Une authentification incorrectement implémentée relève du risque OWASP API2:2023 Broken Authentication ; la comparaison à temps constant du condensé en est la mesure d’atténuation.

Surface de l’API

RPC du service

Le service nextpdf.connect.v1.NextPDFConnect expose des RPC unaires et à diffusion serveur :

RPC	Forme	Objet
Render	unaire	Rendu synchrone
RenderStream	diffusion serveur	Rendu, diffusé en fragments
SubmitJob / GetJobStatus / GetJobResult / CancelJob	unaire	Jobs asynchrones
GetJobResultStream	diffusion serveur	Résultat asynchrone, diffusé
CreateSession / GetSession / DestroySession / SessionOperation / SessionRender	unaire	Sessions avec état
SessionRenderStream	diffusion serveur	Rendu de session, diffusé
ExecuteCapability / GetCapabilities	unaire	Distribution et introspection des capacités
HealthCheck / ReadinessCheck	unaire	Vivacité et disponibilité

ExecuteCapability distribue les mêmes opérations contrôlées par le niveau que les routes d’opérations REST ; les opérations Pro et Enterprise ne sont accessibles que lorsque ces paquets sont installés. Lorsque la signature est fournie, NextPDF Connect avec Pro fournit uniquement la signature PAdES baseline-B (B-B).

Diffusion

Les RPC à diffusion serveur envoient le résultat sous forme d’un flux ordonné de fragments, ce qui convient aux gros PDF et à la livraison incrémentale. Les RPC unaires renvoient le résultat complet dans un seul message.

Exemple de code — Démarrage rapide

Démarre le profil gRPC seul :

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

Génère un client à partir des protos livrés, avec ta chaîne d’outils gRPC :

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

Pour chaque appel, définis la métadonnée authorization des identifiants d’appel à la valeur Bearer npk_live_{kid}_{secret}.

Exemple de code — Production

Le profil combiné exécute gRPC avec TLS mutuel :

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

Dans ce profil, le serveur présente son certificat, puis exige et vérifie un certificat client (require_and_verify_client_cert). Il est sans danger de réessayer une soumission de job unaire idempotente après une connexion interrompue — répéter une requête idempotente produit le même effet voulu qu’une seule requête (RFC 9110 §9.2.2).

Cas limites et pièges

• UNAUTHENTICATED, pas un statut HTTP. Un jeton incorrect ou absent fait échouer le RPC avec le code de statut gRPC UNAUTHENTICATED, pas un 401. Le schéma bearer et le format npk_live_ sont identiques à REST.

• RESOURCE_EXHAUSTED en cas de tentatives de pré-authentification excessives. Les tentatives de pré-authentification répétées provenant d’une même identité client sont limitées et échouent avec le statut gRPC RESOURCE_EXHAUSTED — l’analogue gRPC du 429 HTTP et la même protection anti-automatisation que celle appliquée par la surface REST. Ce contrôle est actif par défaut, de sorte qu’un client devrait attendre avant de réessayer immédiatement. Voir la posture de limitation de débit HTTP dans /connect/production-usage/.

• Le TLS mutuel est une configuration de déploiement, pas une valeur par défaut. L’écouteur gRPC exige des secrets correctement provisionnés : clé serveur, certificat serveur et CA client. Sans eux, le profil combiné ne démarre pas ; c’est intentionnel. Génère-les et renouvelle-les hors bande.

• Le contrôle par niveau s’applique toujours. ExecuteCapability pour une opération Pro ou Enterprise exige le paquet installé et une clé autorisée.

• Les opérations à haut risque restent contrôlées. Les opérations qui pilotent un outil ApprovalRequired passent par le même garde-fou de validation humaine. Voir /connect/hitl-risk-tiers/.

Performances

Chaque worker gRPC traite un appel à la fois. Le pool est dimensionné indépendamment du pool HTTP (deux workers par défaut) et il est généralement plus petit, car les clients gRPC sont moins nombreux et gardent des connexions plus longues. Utilise les RPC à diffusion serveur pour les gros résultats afin d’éviter de mettre tout le PDF en mémoire tampon dans un seul message.

Notes de sécurité

Exécute le transport gRPC avec TLS mutuel sur tout réseau non fiable — jamais avec un écouteur en clair. Traite la CA client, la clé serveur et le certificat serveur comme des secrets montés à l’exécution, jamais intégrés à l’image. L’authentification bearer est appliquée en plus du certificat, pas à sa place. Cette posture exige une configuration de déploiement correcte. Voir /connect/security-and-operations/ et /connect/deployment/.

Conformité

Affirmation	Source	reference_id
Une authentification défaillante compromet la sécurité de l’API	OWASP API Security Top 10, API2:2023
Requêtes idempotentes réessayables après échec	RFC 9110 §9.2.2

Le protocole gRPC lui-même est une spécification externe qui ne figure pas dans le corpus de normes contrôlées ; le contrat de transmission faisant foi reste les définitions Protocol Buffers nextpdf.connect.v1 livrées.

Contexte commercial

ExecuteCapability ne peut atteindre les opérations Pro et Enterprise que lorsque nextpdf/premium est installé aux côtés du serveur. Le transport, l’authentification et la configuration TLS ne changent pas selon les niveaux installés.

Voir aussi

• /connect/security-and-operations/ — authentification, TLS mutuel, modèle de menace
• /connect/deployment/ — le profil RoadRunner combiné et les secrets TLS
• /transports/mcp/ · /transports/rest/ — les autres transports
• /connect/tool-catalog/ — comment ExecuteCapability correspond au catalogue
• /connect/production-usage/ — jobs et réessai idempotent