Transporte gRPC de NextPDF Connect

De un vistazo

El transporte gRPC ejecuta bin/nextpdf-grpc en un grupo de workers gRPC de RoadRunner. Sirve el servicio nextpdf.connect.v1.NextPDFConnect, admite render con streaming desde el servidor, autentica con un token bearer en los metadatos de la llamada y queda configurado para TLS mutuo en el perfil de despliegue combinado.

Instalación

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

Resumen conceptual

El servicio gRPC comparte los mismos servicios de aplicación que el transporte REST —render, jobs, sesiones, capacidades, operaciones— detrás del worker gRPC de Spiral RoadRunner. El contrato de comunicación es el paquete de Protocol Buffers nextpdf.connect.v1, definido por los archivos .proto incluidos en el paquete.

La autenticación reutiliza el almacén de claves y la validación de REST. El autenticador gRPC lee la clave de metadatos authorization —los metadatos de la llamada gRPC se transportan como encabezados HTTP/2—, analiza el token Bearer npk_live_… y valida el kid y el resumen SHA-256 con una comparación en tiempo constante. El autenticador hace que la llamada falle con el estado gRPC UNAUTHENTICATED cuando la clave falta, está malformada, es desconocida, está deshabilitada o ha caducado. Una autenticación implementada de forma incorrecta constituye el riesgo de autenticación rota de OWASP API2:2023; la comparación del resumen en tiempo constante es la mitigación.

Superficie de la API

RPC del servicio

El servicio nextpdf.connect.v1.NextPDFConnect expone RPC unarios y con streaming desde el servidor:

RPC	Forma	Propósito
`Render`	unario	Render síncrono
`RenderStream`	streaming desde el servidor	Render, transmitido en fragmentos
`SubmitJob` / `GetJobStatus` / `GetJobResult` / `CancelJob`	unario	Jobs asíncronos
`GetJobResultStream`	streaming desde el servidor	Resultado asíncrono, transmitido
`CreateSession` / `GetSession` / `DestroySession` / `SessionOperation` / `SessionRender`	unario	Sesiones con estado
`SessionRenderStream`	streaming desde el servidor	Render de sesión, transmitido
`ExecuteCapability` / `GetCapabilities`	unario	Despacho e introspección de capacidades
`HealthCheck` / `ReadinessCheck`	unario	Disponibilidad y preparación

ExecuteCapability despacha las mismas operaciones con control por nivel que las rutas de operación de REST; las operaciones de Pro y Enterprise solo son accesibles cuando esos paquetes están instalados. Cuando se despacha la firma, NextPDF Connect con Pro proporciona únicamente la firma PAdES baseline-B (B-B).

Streaming

Los RPC con streaming desde el servidor envían el resultado como un flujo ordenado de fragmentos, lo que resulta útil para PDF grandes y para la entrega incremental. Los RPC unarios devuelven el resultado completo en un solo mensaje.

Ejemplo de código — Inicio rápido

Inicia el perfil exclusivo de gRPC:

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

Genera un cliente a partir de los protos incluidos con la cadena de herramientas de gRPC:

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

Establece la credencial de llamada en los metadatos authorization como Bearer npk_live_{kid}_{secret} en cada llamada.

Ejemplo de código — Producción

El perfil combinado ejecuta gRPC con TLS mutuo:

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

En este perfil, el servidor presenta su certificado y exige y verifica un certificado de cliente (require_and_verify_client_cert). Reintentar el envío de un job unario idempotente tras una conexión interrumpida es seguro: repetir una solicitud idempotente tiene el mismo efecto previsto que una sola solicitud (RFC 9110 §9.2.2).

Casos límite y advertencias

UNAUTHENTICATED, no un estado HTTP. Un token incorrecto o ausente hace fallar el RPC con el código de estado gRPC UNAUTHENTICATED, no con un 401. El esquema bearer y el formato npk_live_ son idénticos a los de REST.
RESOURCE_EXHAUSTED ante demasiados intentos previos a la autenticación. Los intentos repetidos de autenticación previa desde una misma identidad de cliente se limitan y fallan con el estado gRPC RESOURCE_EXHAUSTED —el equivalente de HTTP 429 en gRPC y la misma postura contra automatización que aplica la superficie REST. Este control está activo de forma predeterminada, por lo que un cliente debería esperar antes de reintentar en lugar de hacerlo de inmediato. Consulta la postura de límite de tasa de HTTP en /connect/production-usage/.
El TLS mutuo es una configuración de despliegue, no un valor predeterminado. El listener gRPC requiere secretos de clave de servidor, certificado de servidor y CA de cliente correctamente aprovisionados. Sin ellos, el perfil combinado no servirá; esto es deliberado. Genéralos y rótalos fuera de banda.
El control por nivel sigue aplicándose. ExecuteCapability para una operación de Pro o Enterprise requiere el paquete instalado y una clave con derechos.
Las operaciones de alto riesgo siguen pasando por una compuerta. Las operaciones que activan una herramienta ApprovalRequired pasan por la misma compuerta con intervención humana. Consulta /connect/hitl-risk-tiers/.

Rendimiento

Cada worker gRPC atiende una llamada a la vez. El grupo se dimensiona de forma independiente del grupo HTTP (dos workers de forma predeterminada) y suele ser más pequeño porque los clientes gRPC son menos numerosos y tienen una vida más larga. Usa los RPC con streaming desde el servidor para salidas grandes, con el fin de evitar almacenar todo el PDF en un solo mensaje.

Notas de seguridad

Ejecuta el transporte gRPC con TLS mutuo en cualquier red no confiable: nunca con un listener en texto plano. Trata la CA de cliente, la clave de servidor y el certificado de servidor como secretos montados en tiempo de ejecución, nunca incorporados en la imagen. La autenticación bearer se aplica además del certificado, no en su lugar. Esta postura requiere una configuración de despliegue correcta. Consulta /connect/security-and-operations/ y /connect/deployment/.

Conformidad

Afirmación	Fuente	`reference_id`
La autenticación rota compromete la seguridad de la API	OWASP API Security Top 10, API2:2023
Solicitudes idempotentes reintentables tras un fallo	RFC 9110 §9.2.2

El propio protocolo gRPC es una especificación externa que no está en el corpus de estándares controlado; las definiciones de Protocol Buffers nextpdf.connect.v1 incluidas son el contrato de comunicación de referencia.

Contexto comercial

ExecuteCapability puede ejecutar operaciones de Pro y Enterprise solo cuando nextpdf/premium está instalado junto con el servidor. El transporte, la autenticación y la configuración de TLS no cambian según los niveles instalados.

Consulta también

/connect/security-and-operations/ — autenticación, TLS mutuo, modelo de amenazas
/connect/deployment/ — el perfil combinado de RoadRunner y los secretos de TLS
/transports/mcp/ · /transports/rest/ — los otros transportes
/connect/tool-catalog/ — cómo ExecuteCapability se asigna al catálogo
/connect/production-usage/ — jobs y reintento idempotente