NextPDF Connect — transporte gRPC

Visão geral

O transporte gRPC executa bin/nextpdf-grpc em um pool de workers gRPC do RoadRunner. Ele atende ao serviço nextpdf.connect.v1.NextPDFConnect, oferece suporte à renderização com streaming do servidor, autentica cada chamada com um bearer token nos metadados e é configurado para Transport Layer Security (TLS) mútua no perfil de implantação combinado.

Instalação

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

Visão conceitual

O serviço gRPC usa os mesmos serviços da aplicação que o transporte Representational State Transfer (REST): render, jobs, sessions, capabilities e operations. Um worker gRPC do Spiral RoadRunner processa as chamadas. O contrato de comunicação é o pacote Protocol Buffers nextpdf.connect.v1, definido pelos arquivos .proto distribuídos com o pacote.

A autenticação usa o mesmo armazenamento de chaves e a mesma validação que o REST. O autenticador gRPC lê a chave de metadados authorization, que o gRPC transporta como cabeçalhos do Hypertext Transfer Protocol version 2 (HTTP/2). Ele analisa o token Bearer npk_live_… e, em seguida, valida o identificador da chave (kid) e o resumo SHA-256 com uma comparação em tempo constante. O autenticador rejeita a chamada com o status gRPC UNAUTHENTICATED quando a chave está ausente, malformada, desconhecida, desativada ou expirada. Uma autenticação implementada incorretamente corresponde ao risco OWASP API2:2023 Broken Authentication; a comparação de resumos em tempo constante mitiga esse risco.

Superfície da API

RPCs do serviço

O serviço nextpdf.connect.v1.NextPDFConnect expõe chamadas de procedimento remoto (RPCs) unárias e de streaming do servidor:

RPC	Formato	Finalidade
`Render`	unária	Renderização síncrona
`RenderStream`	streaming do servidor	Renderização, transmitida em blocos
`SubmitJob` / `GetJobStatus` / `GetJobResult` / `CancelJob`	unária	Jobs assíncronos
`GetJobResultStream`	streaming do servidor	Resultado assíncrono, transmitido
`CreateSession` / `GetSession` / `DestroySession` / `SessionOperation` / `SessionRender`	unária	Sessões com estado
`SessionRenderStream`	streaming do servidor	Renderização de sessão, transmitida
`ExecuteCapability` / `GetCapabilities`	unária	Despacho e introspecção de capabilities
`HealthCheck` / `ReadinessCheck`	unária	Liveness e readiness

ExecuteCapability despacha as mesmas operações restritas por tier que as rotas de operação do REST. As operações Pro e Enterprise só ficam acessíveis quando esses pacotes estão instalados. Para assinatura, o NextPDF Connect com Pro fornece apenas assinatura Portable Document Format (PDF) Advanced Electronic Signatures (PAdES) baseline-B (B-B).

Streaming

As RPCs de streaming do servidor enviam o resultado como um fluxo ordenado de blocos, o que é adequado para arquivos PDF grandes e para entrega incremental. As RPCs unárias retornam o resultado completo em uma única mensagem.

Exemplo de código — Início rápido

Inicie o perfil somente gRPC:

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

Gere um cliente a partir dos arquivos .proto distribuídos usando a sua toolchain gRPC:

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

Em cada chamada, defina o metadado de credencial da chamada authorization como Bearer npk_live_{kid}_{secret}.

Exemplo de código — Produção

O perfil combinado executa o gRPC com TLS mútua:

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

Nesse perfil, o servidor apresenta o próprio certificado, exige um certificado de cliente e o verifica (require_and_verify_client_cert). Reenviar uma submissão de job unária idempotente após uma conexão interrompida é seguro: repetir uma requisição idempotente tem o mesmo efeito pretendido de uma única requisição (RFC 9110 §9.2.2).

Casos de borda e armadilhas

UNAUTHENTICATED, não um status HTTP. Um token inválido ou ausente rejeita a RPC com o código de status gRPC UNAUTHENTICATED, não um 401. O esquema bearer e o formato npk_live_ são idênticos aos do REST.
RESOURCE_EXHAUSTED em tentativas excessivas de pré-autenticação. Tentativas repetidas de pré-autenticação a partir da mesma identidade de cliente são limitadas e rejeitadas com o status gRPC RESOURCE_EXHAUSTED. Esse status é o equivalente gRPC do HTTP 429 e aplica a mesma postura antiautomação que o REST. Esse controle está ativo por padrão; portanto, os clientes devem aguardar antes de tentar novamente, em vez de repetir a chamada de imediato. Consulte a postura de limitação de taxa HTTP em /connect/production-usage/.
A TLS mútua é uma configuração de implantação, não é o padrão. O listener gRPC exige que os segredos de chave de servidor, certificado de servidor e autoridade certificadora (CA) de cliente estejam provisionados corretamente. Sem eles, o perfil combinado não aceitará chamadas; isso é intencional. Gere e rotacione esses segredos fora de banda.
A restrição por tier continua valendo. ExecuteCapability para uma operação Pro ou Enterprise exige que o pacote esteja instalado e uma chave autorizada.
Operações de alto risco continuam sob controle de acesso. As operações que acionam uma ferramenta ApprovalRequired usam o mesmo controle com intervenção humana (human-in-the-loop). Consulte /connect/hitl-risk-tiers/.

Desempenho

Cada worker gRPC trata uma chamada por vez. O pool é dimensionado de forma independente do pool HTTP (dois workers por padrão) e costuma ser menor porque há menos clientes gRPC e as conexões deles duram mais. Use RPCs de streaming do servidor para saídas grandes, a fim de evitar colocar o PDF inteiro em buffer em uma única mensagem.

Notas de segurança

Execute o transporte gRPC com TLS mútua em qualquer rede não confiável; nunca use um listener em texto puro. Trate a CA de cliente, a chave de servidor e o certificado de servidor como segredos montados em tempo de execução, nunca embutidos na imagem. A autenticação bearer é aplicada além do certificado, não como substituição a ele. Essa postura exige uma configuração de implantação correta. Consulte /connect/security-and-operations/ e /connect/deployment/.

Conformidade

Afirmação	Fonte	`reference_id`
Autenticação quebrada compromete a segurança da API	OWASP API Security Top 10, API2:2023
Requisições idempotentes podem ser repetidas após falha	RFC 9110 §9.2.2

O protocolo gRPC em si é uma especificação externa, fora do corpus restrito de normas. As definições de Protocol Buffers nextpdf.connect.v1 distribuídas são o contrato de comunicação oficial.

Contexto comercial

ExecuteCapability aciona operações Pro e Enterprise somente quando o nextpdf/premium está instalado junto com o servidor. Os tiers instalados não alteram o transporte, a autenticação ou a configuração de TLS.

Veja também

/connect/security-and-operations/ — autenticação, TLS mútua, modelo de ameaças
/connect/deployment/ — o perfil combinado do RoadRunner e os segredos de TLS
/transports/mcp/ · /transports/rest/ — os outros transportes
/connect/tool-catalog/ — como o ExecuteCapability mapeia para o catálogo
/connect/production-usage/ — jobs e repetição idempotente