NextPDF Connect em produção

Visão geral

Uma implantação de produção do NextPDF Connect oferece vários controles operacionais: sondas de integridade e prontidão, caminhos de renderização síncronos e assíncronos, idempotência, limites de taxa por cliente e por endereço Internet Protocol (IP) e sessões com estado opcionais. Use esta página para operá-los com comportamento previsível.

Instalação

composer require nextpdf/server

Visão conceitual

O transporte Representational State Transfer (REST) é um pipeline de middleware PHP Standards Recommendation (PSR)-15. Cada requisição passa pelos middlewares em ordem: atribuição de request-id, limites de tamanho do corpo, Cross-Origin Resource Sharing (CORS), autenticação, autorização de capacidade, limitação de taxa, idempotência e timeout. Em seguida, a requisição chega a um handler. O transporte gRPC reutiliza os mesmos serviços de aplicação por trás do worker gRPC do RoadRunner.

A renderização tem dois caminhos. O caminho síncrono POST /api/v1/render executa as operações e retorna o arquivo Portable Document Format (PDF) na resposta. Um job assíncrono usa POST /api/v1/jobs. Ele retorna imediatamente com um ID de job, e você busca o resultado depois em GET /api/v1/jobs/{id}/result. Os jobs persistem em um store SQLite compartilhado, de modo que qualquer worker pode responder a uma consulta de status ou resultado.

Superfície da API

Integridade e prontidão

Endpoint	Autenticação	Significado
`GET /healthz`	nenhuma	O processo está em execução
`GET /readyz`	nenhuma	O servidor está pronto para aceitar requisições

Conecte /healthz a uma sonda de liveness e /readyz a uma sonda de readiness. Ambos os endpoints são anônimos, portanto os orquestradores não precisam de credenciais.

Jobs assíncronos

Endpoint	Método	Finalidade
`/api/v1/jobs`	`POST`	Enviar um job de renderização
`/api/v1/jobs/{id}`	`GET`	Status do job
`/api/v1/jobs/{id}/result`	`GET`	Resultado do job (o PDF)
`/api/v1/jobs/{id}`	`DELETE`	Cancelar um job

Sessões (opcional)

Quando NEXTPDF_SESSIONS_ENABLED é true e há ferramentas disponíveis, os endpoints de sessão fornecem um fluxo de construção com estado. Você cria uma sessão, adiciona páginas, texto, imagens, tabelas e HyperText Markup Language (HTML), define a fonte e então renderiza. As sessões têm um limite por cliente e um timeout por inatividade. Elas ficam desativadas por padrão.

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

Envie um job assíncrono e faça polling do resultado:

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

Exemplo de código — Produção

Torne um envio seguro para repetir enviando uma chave de idempotência:

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

Uma requisição reenviada com a mesma chave de idempotência retorna o resultado original em vez de criar um segundo job. Isso permite repetir o envio com segurança após uma falha de comunicação. Esse comportamento corresponde à propriedade oferecida por um método idempotente: enviar a mesma requisição novamente tem o mesmo efeito pretendido que enviá-la uma única vez (RFC 9110 §9.2.2). Portanto, a requisição pode ser repetida automaticamente se a conexão cair antes que o cliente leia a resposta (RFC 9110 §9.2.2).

Casos extremos e pontos de atenção

A limitação de taxa precisa do Redis para funcionar corretamente entre workers. Os limitadores por cliente e por IP usam o store configurado. Com o store em memória e mais de um worker, cada worker contabiliza as requisições de forma independente, e o limite efetivo é multiplicado pelo número de workers. Use o store Redis para qualquer pool com múltiplos workers.
Uma requisição limitada retorna 429. Quando um limite é excedido, o servidor responde com 429 Too Many Requests e um cabeçalho Retry-After, seguindo a semântica de status de limitação de taxa (RFC 6585 §4). Respeite Retry-After; não tente novamente imediatamente.
Os resultados dos jobs não duram para sempre. O store de jobs remove entradas antigas após NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Busque os resultados antes que eles expirem.
As sessões consomem memória. Uma sessão mantém um documento em andamento. O limite de sessões por cliente e o timeout por inatividade restringem esse custo. Não aumente esses valores sem dimensionar a memória para o pior caso.

Desempenho

O caminho síncrono mantém um worker ocupado durante toda a renderização. Para renderizações grandes ou lentas, use o caminho de job assíncrono. Ele libera o worker imediatamente, e o cliente faz polling do resultado. Dimensione o pool de workers com base na latência de renderização observada e na concorrência. Monitore o endpoint de métricas do RoadRunner.

Notas de segurança

Todos os endpoints, exceto as sondas de integridade e prontidão, exigem uma chave de API válida. O tier do cliente controla quais operações e tamanhos de payload são permitidos. Os clientes fornecem as chaves de idempotência. Trate cada chave como opaca e única para uma operação lógica. Consulte /connect/security-and-operations/.

Conformidade

Declaração	Fonte	`reference_id`
Idempotente: requisições repetidas = um efeito	RFC 9110 §9.2.2
Requisições idempotentes podem ser repetidas após falha	RFC 9110 §9.2.2
`429` + `Retry-After` para limitação de taxa	RFC 6585 §4

Contexto comercial

As chaves Pro e Enterprise têm tetos de payload e timeout por tier mais altos quando essas ferramentas estão instaladas. Uma implantação padrão usa os tetos do tier core.

Veja também

/connect/deployment/ — pools de workers, Redis, perfis do RoadRunner
/transports/rest/ — o pipeline de middleware completo e o contrato OpenAPI
/connect/troubleshooting/ — diagnóstico de 401/403/413/429/5xx e falhas de store
/connect/security-and-operations/ — autenticação e postura de limitação de taxa