Ciclo de vida seguro de sessão para workers no NextPDF Connect

Visão geral

Use um ciclo de vida de sessão no escopo da requisição em um worker PHP de longa duração (RoadRunner, Swoole, Laravel Octane). Cada requisição cria sua própria sessão de documento e a destrói após output_pdf. O estado da fonte, da página e do handle permanece dentro do limite da requisição do worker. As ferramentas são create_pdf, set_font, add_text e output_pdf — todas do Core.

Instalação

composer require nextpdf/server

Vincule um transporte. Este padrão funciona da mesma forma com qualquer transporte.

Visão conceitual

Um document_id é um handle opaco com escopo em uma única requisição. Siga uma única regra: crie por requisição, destrua por requisição, nunca armazene em cache nem compartilhe. Com o padrão destroy: true, output_pdf renderiza o documento e libera a sessão em um único passo atômico. A próxima requisição no mesmo worker recebe uma sessão nova e independente. A fonte e o conteúdo da sessão anterior deixam de existir. Cada resultado de ferramenta é uma resposta de transporte normal (PSR-18 §p2). O código do servidor é isolado pelo limite de autoload (PSR-4 §3). O armazenamento de sessões é o único estado compartilhado entre requisições, e ele é indexado por id.

Superfície da API

Ferramenta	Função	Nível de risco
`create_pdf`	Abre uma sessão por requisição	Seguro
`set_font`	Define a fonte ativa (por sessão)	Cuidado
`add_text`	Escreve conteúdo	Cuidado
`output_pdf`	Renderiza e destrói a sessão	Aprovação Necessária / Revisão (base64)

O catálogo de ferramentas é a referência oficial. As ferramentas que você pode usar dependem do nível instalado.

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

Requisição 1: create_pdf → set_font → add_text → output_pdf (destroy: true). A requisição 2 no mesmo worker inicia uma nova sessão create_pdf. O id antigo passa a ser inválido. Defina a fonte novamente, pois ela não é preservada.

Exemplo de código — Produção

Encapsule o ciclo de vida para que a limpeza sempre seja executada:

Obtenha a sessão quando a requisição começar.
Construa o conteúdo.
Em um bloco equivalente a finally, chame output_pdf, que destrói a sessão. Se você usou destroy: false em um fluxo de inspeção após a saída, destrua a sessão explicitamente.

Nunca armazene um document_id em um contêiner global de worker, estático ou compartilhado. Nunca o passe entre corrotinas, fibers ou handlers de requisição.

Casos extremos e armadilhas

Id reutilizado após a destruição. Retorna um erro de documento desconhecido. Crie uma nova sessão para cada requisição.
output_pdf esquecido. A memória cresce silenciosamente até o TTL da sessão expirar ou até o processo reiniciar. Sempre finalize.
Limite de sessões sob carga. O armazenamento tem um limite de concorrência. A destruição imediata ajuda você a se manter abaixo dele.
destroy: false sem limpeza. A memória cresce gradualmente. Use-o apenas para um fluxo explícito de inspeção após a saída e depois destrua a sessão.
Id compartilhado entre requisições concorrentes. É uma condição de corrida que corrompe a saída. Cada requisição é dona da própria sessão.

Desempenho

A saída por requisição tem alguns KB. O benefício é manter a memória do worker limitada ao longo do tempo de vida do worker. O perfil é structural.

Notas de segurança

O isolamento de sessão também é uma propriedade de confidencialidade. O conteúdo de uma requisição nunca chega a outra, porque os handles não são compartilhados e a sessão é destruída na saída.

Conformidade

Afirmação	Especificação	Cláusula	reference_id
Cada resultado de ferramenta é uma resposta de transporte normal.	PSR-18	§p2
O código é isolado pelo mapeamento de classe→arquivo do autoload.	PSR-4	§3

Contexto comercial

Não aplicável — todas as ferramentas são Core.

Disponibilidade de transporte

Transporte	Disponível	Notas
MCP (stdio)	Sim	O típico é um processo stdio por worker.
REST	Sim	O limite da requisição HTTP corresponde ao limite da sessão.
gRPC	Sim	Uma sessão por sequência RPC.

Nível de risco HITL

create_pdf é Seguro. set_font e add_text são Cuidado. output_pdf é Aprovação Necessária, rebaixado para Revisão no modo base64. Em um worker, a saída base64 é o caminho comum e não adiciona gate algum (níveis de risco HITL).

Envelope JSON do gate de confirmação

Saída base64 do worker:

{ "allowed": true }