Ciclo di vita sicuro delle sessioni per i worker in NextPDF Connect

In sintesi

Usare il ciclo di vita corretto della sessione in un worker PHP a esecuzione prolungata (RoadRunner, Swoole, Laravel Octane). Ogni richiesta crea la propria sessione di documento e la distrugge dopo output_pdf. Nessuno stato di font, pagina o handle trapela oltre il confine della richiesta del worker. Gli strumenti sono create_pdf, set_font, add_text e output_pdf — tutti Core.

Installazione

composer require nextpdf/server

Associare un trasporto. Il modello funziona allo stesso modo con qualsiasi trasporto.

Panoramica concettuale

Un document_id è un handle opaco con ambito limitato a una singola richiesta. La regola è creare per richiesta, distruggere per richiesta, mai memorizzare nella cache né condividere. Con il valore predefinito destroy: true, output_pdf esegue il rendering del documento e libera la sessione in un’unica operazione atomica. La richiesta successiva sullo stesso worker ottiene una sessione nuova e indipendente. Il font e il contenuto della sessione precedente non esistono più. Ogni risultato di uno strumento è una normale risposta di trasporto (PSR-18 §p2). Il codice del server stesso è isolato dal confine di autoload (PSR-4 §3). L’archivio delle sessioni è l’unico stato condiviso tra le richieste ed è indicizzato per id.

Superficie API

Strumento	Ruolo	Livello di rischio
`create_pdf`	Apre una sessione per una singola richiesta	Sicuro
`set_font`	Imposta il font attivo (per sessione)	Attenzione
`add_text`	Scrive il contenuto	Attenzione
`output_pdf`	Esegue il rendering e distrugge la sessione	Approvazione richiesta / Revisione (base64)

Il catalogo degli strumenti è il riferimento canonico. Gli strumenti disponibili dipendono dal livello installato.

Esempio di codice — Avvio rapido

Richiesta 1: create_pdf → set_font → add_text → output_pdf (destroy: true). La richiesta 2 sullo stesso worker avvia, con create_pdf, una sessione completamente nuova. Il vecchio id ora non è più valido. Impostare di nuovo il font, perché non viene mantenuto.

Esempio di codice — Produzione

Incapsulare il ciclo di vita in modo che la pulizia venga sempre eseguita:

Acquisire la sessione all’avvio della richiesta.
Costruire il contenuto.
In un blocco equivalente a finally, chiamare output_pdf, che distrugge la sessione. Se è stato usato destroy: false per un flusso di ispezione dopo l’output, distruggere invece la sessione esplicitamente.

Non memorizzare mai un document_id in una variabile globale del worker, in una variabile statica o in un container condiviso. Non passarlo mai tra coroutine, fiber o gestori di richieste.

Casi limite e insidie

Id riutilizzato dopo la distruzione. Restituisce un errore di documento sconosciuto. Creare una nuova sessione per ogni richiesta.
output_pdf dimenticato. La memoria cresce silenziosamente finché il TTL della sessione non scade o il processo non viene riavviato. Finalizzare sempre.
Limite di sessioni sotto carico. L’archivio ha un limite massimo di concorrenza. Una distruzione tempestiva mantiene l’uso al di sotto di tale limite.
destroy: false senza pulizia. La memoria cresce gradualmente. Usarlo solo per un flusso esplicito di ispezione dopo l’output, poi distruggere la sessione.
Id condiviso tra richieste concorrenti. È una race condition che corrompe l’output. Ogni richiesta possiede la propria sessione.

Prestazioni

L’output per richiesta occupa pochi KB. Il vantaggio è mantenere limitata la memoria del worker per tutta la sua durata. Il profilo è structural.

Note sulla sicurezza

L’isolamento della sessione è anche una proprietà di riservatezza. Il contenuto di una richiesta non raggiunge mai un’altra, perché gli handle non sono condivisi e la sessione viene distrutta al momento dell’output.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
Ogni risultato di uno strumento è una normale risposta di trasporto.	PSR-18	§p2
Il codice è isolato dalla mappatura di autoload classe→file.	PSR-4	§3

Contesto commerciale

Non applicabile — tutti gli strumenti sono Core.

Disponibilità dei trasporti

Trasporto	Disponibile	Note
MCP (stdio)	Sì	Un processo stdio per worker è la configurazione tipica.
REST	Sì	Il confine della richiesta HTTP corrisponde al confine della sessione.
gRPC	Sì	Una sessione per sequenza RPC.

Livello di rischio HITL

create_pdf è Sicuro. set_font e add_text sono Attenzione. output_pdf è Approvazione richiesta, declassato a Revisione in modalità base64. In un worker, l’output base64 è il percorso comune e non attiva alcun gate (livelli di rischio HITL).

Envelope JSON del gate di conferma

Output base64 del worker:

{ "allowed": true }