Ciclo de vida seguro de sesiones para workers con NextPDF Connect

De un vistazo

Usar el ciclo de vida de sesión correcto en un worker de PHP de larga duración (RoadRunner, Swoole, Laravel Octane). Cada solicitud crea su propia sesión de documento y la destruye tras output_pdf. Ningún estado de fuente, página o identificador se filtra más allá del límite de solicitud del worker. Las herramientas son create_pdf, set_font, add_text y output_pdf, todas ellas de Core.

Instalación

composer require nextpdf/server

Enlazar un transporte. El patrón funciona igual con cualquier transporte.

Descripción conceptual

Un document_id es un identificador opaco con alcance limitado a una sola solicitud. La regla es crear por solicitud, destruir por solicitud, nunca almacenar en caché ni compartir. Con el valor predeterminado destroy: true, output_pdf representa el documento y libera la sesión en un único paso atómico. La siguiente solicitud en el mismo worker recibe una sesión nueva e independiente. La fuente y el contenido de la sesión anterior ya han desaparecido. El resultado de cada herramienta es una respuesta de transporte normal (PSR-18 §p2). El propio código del servidor queda aislado por el límite de autoload (PSR-4 §3). El almacén de sesiones es el único estado entre solicitudes y se indexa por id.

Superficie de API

Herramienta	Función	Nivel de riesgo
`create_pdf`	Crear una sesión por solicitud	Seguro
`set_font`	Establecer la fuente activa (por sesión)	Precaución
`add_text`	Escribir contenido	Precaución
`output_pdf`	Representar y destruir la sesión	Requiere aprobación / Revisión (base64)

El catálogo de herramientas es el catálogo de referencia. Las herramientas disponibles dependen del nivel instalado.

Ejemplo de código: inicio rápido

Solicitud 1: create_pdf → set_font → add_text → output_pdf (destroy: true). La solicitud 2 en el mismo worker inicia una sesión create_pdf completamente nueva. El id anterior ya no es válido. Es necesario volver a establecer la fuente, porque no se transfiere.

Ejemplo de código: producción

Envolver el ciclo de vida para que la limpieza se ejecute siempre:

Adquirir la sesión al inicio de la solicitud.
Construir el contenido.
En un bloque equivalente a finally, llamar a output_pdf, que destruye la sesión. Si se usó destroy: false para un flujo de inspección tras la salida, destruir la sesión explícitamente en su lugar.

No se debe almacenar nunca un document_id en una variable global del worker, en una estática ni en un contenedor compartido. No se debe pasar nunca entre corrutinas, fibras o manejadores de solicitudes.

Casos límite y trampas

Id reutilizado tras destruir. Devuelve un error de documento desconocido. Crear una nueva sesión por solicitud.
output_pdf olvidado. La memoria crece sin avisar hasta que el TTL de la sesión expira o el proceso se reinicia. Finalizar siempre.
Límite de sesiones bajo carga. El almacén tiene un tope de concurrencia. La destrucción inmediata lo mantiene por debajo de ese tope.
destroy: false sin limpieza. La memoria crece gradualmente. Usarlo solo para un flujo explícito de inspección tras la salida y, después, destruir la sesión.
Id compartido entre solicitudes concurrentes. Provoca una condición de carrera que corrompe la salida. Cada solicitud posee su propia sesión.

Rendimiento

La salida por solicitud es de unos pocos KB. La ventaja es que la memoria del worker queda acotada durante toda su vida útil. El perfil es structural.

Notas de seguridad

El aislamiento de sesiones también es una propiedad de confidencialidad. El contenido de una solicitud nunca llega a otra, porque los identificadores no se comparten y la sesión se destruye al generar la salida.

Conformidad

Declaración	Especificación	Cláusula	reference_id
Cada resultado de herramienta es una respuesta de transporte normal.	PSR-18	§p2
El código está aislado por la asignación de clase→archivo del autoload.	PSR-4	§3

Contexto comercial

No aplica: todas las herramientas son de Core.

Disponibilidad por transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí	Lo habitual es un proceso stdio por worker.
REST	Sí	El límite de la solicitud HTTP coincide con el límite de la sesión.
gRPC	Sí	Una sesión por secuencia de RPC.

Nivel de riesgo HITL

create_pdf es Seguro. set_font y add_text son Precaución. output_pdf es Requiere aprobación, con degradación a Revisión en modo base64. En un worker, la salida base64 es la ruta habitual y no se aplica ninguna compuerta (niveles de riesgo HITL).

JSON de la compuerta de confirmación

Salida base64 del worker:

{ "allowed": true }