Pipeline de salida

De un vistazo

NextPDF Enterprise coordina la ejecución por lotes a gran escala de manifiestos del output pipeline de NextPDF Pro con un límite de concurrencia configurable y un traspaso de cumplimiento opcional sobre las salidas completadas. Es la capa de lotes sobre el output pipeline de Pro.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin esa titularidad no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

La superficie de lotes de Enterprise se construye sobre el output pipeline de Pro (pro.output.pipeline), que es un prerrequisito y no la restricción. No hay ningún código de capacidad por característica independiente; el orquestador de lotes y el traspaso de cumplimiento están disponibles allí donde esté instalado el paquete licenciado nextpdf/enterprise.

Instalación

composer require nextpdf/enterprise:^3

Descripción conceptual

BatchPipelineOrchestrator ejecuta muchas instancias de PipelineManifest como un solo lote. Cada manifiesto se ejecuta a través del PipelineExecutor de Pro; el orquestador añade la coordinación de lotes, un guard de recursos acotados (el número de manifiestos por lote está limitado), la gestión de tiempo de espera por lote y un traspaso de cumplimiento opcional.

BatchPipelineConfig controla tres cosas: el número máximo de callbacks de worker concurrentes, un tiempo de espera global de lote opcional en milisegundos y si se ejecuta una comprobación de cumplimiento sobre cada salida después de que el pipeline finalice. Cuando la comprobación de cumplimiento está habilitada, ComplianceHandoff se integra como un paso del pipeline que vuelve a validar cada PDF derivado a través de la pasarela de cumplimiento de Enterprise, de modo que un documento modificado por el pipeline se vuelve a comprobar en lugar de confiar en su estado previo a la modificación.

En los despliegues de producción, el reparto paralelo de workers y la contrapresión los gestiona un sidecar de ejecución independiente; el orquestador de PHP descrito aquí proporciona la coordinación de lotes y la lógica de traspaso de cumplimiento, y lo invoca el worker de tareas en lugar de los manejadores de peticiones directamente.

Por qué funciona así

La generación por lotes de gran volumen se divide en dos preocupaciones: coordinar qué manifiestos se ejecutan bajo qué garantías e impulsar el rendimiento paralelo bruto. NextPDF mantiene la coordinación y la semántica de cumplimiento en este orquestador de PHP determinista, y delega el reparto paralelo de workers y la contrapresión en un sidecar de ejecución independiente. Esa frontera permite que la capa de rendimiento escale la concurrencia de forma independiente mientras el orquestador se mantiene simple, acotado y auditable. Un límite estricto de manifiestos por lote mantiene predecible la memoria máxima, de modo que un envío grande no pueda degradar el grupo de workers. El traspaso de cumplimiento vuelve a validar cada salida derivada en lugar de confiar en su estado previo a la modificación, y falla de forma cerrada. Un manifiesto completado pasa solo cuando la pasarela confirma la conformidad, nunca por defecto.

Contexto de diseño: Generación de documentos de gran volumen.

Superficie de la API

Clase	Responsabilidad
BatchPipelineOrchestrator	Ejecutar muchos manifiestos como un lote con concurrencia acotada.
BatchPipelineConfig	Concurrencia máxima, tiempo de espera de lote, interruptor de cumplimiento al completar.
BatchPipelineResult	Agregado: resultados por manifiesto, recuentos de completados y fallidos, tiempos.
ComplianceHandoff	Paso opcional de nueva validación de cumplimiento al final del pipeline.

Ejemplo de código — Inicio rápido

use NextPDF\Enterprise\OutputPipeline\BatchPipelineOrchestrator;

$result = (new BatchPipelineOrchestrator($executor))->executeBatch($manifests);

Ejemplo de código — Producción

use NextPDF\Enterprise\OutputPipeline\BatchPipelineOrchestrator;
use NextPDF\Enterprise\OutputPipeline\BatchPipelineConfig;

$config = new BatchPipelineConfig(
    maxConcurrency: 4,
    timeoutMs: 600_000,
    complianceCheckOnComplete: true,
);

$result = (new BatchPipelineOrchestrator($executor, $config))
    ->executeBatch($manifests, $variablesMap);

$logger->info('pipeline.batch', [
    'completed' => $result->completedCount,
    'failed'    => $result->failedCount,
]);

Casos límite y aspectos a tener en cuenta

• El lote aplica un límite superior al número de manifiestos; superarlo genera un error del guard de recursos en lugar de degradarse de forma silenciosa.
• Un tiempo de espera global de cero significa que no hay tiempo de espera de lote; establezca un valor finito en producción para que un manifiesto atascado no pueda bloquear el lote indefinidamente.
• El traspaso de cumplimiento requiere un PDF reconocible en la salida del paso aguas arriba; si no se encuentra ninguno, el paso notifica un fallo para ese manifiesto en lugar de pasar de forma silenciosa.
• Este módulo depende del output pipeline de Pro; añade la coordinación de lotes, no un nuevo modelo de pasos.

Rendimiento

El rendimiento de procesamiento escala con la concurrencia configurada y el coste por manifiesto. La concurrencia debe establecerse de forma conservadora en relación con el grupo de workers para que los callbacks no lo saturen. El límite de manifiestos por lote acota la memoria máxima.

Notas de seguridad

El orquestador de lotes procesa los manifiestos y las variables que suministre el llamante; trate las entradas del pipeline como cualquier otra carga de trabajo de PDF no confiable. El traspaso de cumplimiento es una ayuda de nueva validación, no un control de autorización.

Residencia de datos y mitigaciones de PII

Las salidas de lote pueden contener datos personales. El procesamiento es en proceso y local; este orquestador no realiza llamadas de red salientes. Aplique sus propios controles de conservación a las salidas de lote.

Telemetría segura y depuración de registros

Los resultados de lote informan de recuentos y tiempos, no del contenido del documento. Depure los identificadores de manifiesto de los registros si codifican datos de inquilino o de caso.

Conformidad

No se afirma ninguna conformidad con estándares para este módulo; es una capa de orquestación. El traspaso de cumplimiento opcional se remite a la pasarela de cumplimiento de Enterprise, que lleva sus propias referencias.

Comportamiento en modo FIPS

Este módulo no realiza ninguna operación criptográfica.

Modelo de amenazas

Las entradas principales son los manifiestos y las variables suministrados por el llamante. Mitigaciones: un límite estricto de manifiestos por lote, concurrencia acotada, nueva validación opcional de las salidas derivadas y ninguna E/S de red en el propio orquestador.

Contrato de comportamiento

• executeBatch() ejecuta cada manifiesto a través del ejecutor de pipeline de Pro y devuelve los resultados por manifiesto con los recuentos de completados y fallidos y los tiempos.
• Un límite estricto acota el número de manifiestos por lote; superarlo genera un error del guard de recursos en lugar de degradarse de forma silenciosa.
• Un tiempo de espera global de cero significa que no hay tiempo de espera de lote; un valor finito acota un manifiesto atascado.
• Cuando está habilitado, el traspaso de cumplimiento vuelve a validar cada PDF derivado y notifica un fallo de paso cuando no se encuentra ningún PDF reconocible aguas arriba en lugar de pasar de forma silenciosa.

Frontera de publicación

Esta página documenta únicamente el comportamiento observable desde fuera y la superficie de API pública admitida. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Alternativa de Core

NextPDF Core no tiene ningún modelo de output pipeline. Un despliegue solo con Core compone sus propios pasos directamente contra la API de Core; no hay manifiesto, ni coordinación de lotes, ni traspaso de cumplimiento.

Alternativa de Pro

En un despliegue solo con Pro, la superficie admitida es el output pipeline de Pro de un solo manifiesto (pro.output.pipeline): el PipelineExecutor de Pro ejecuta un manifiesto cada vez. Pro no proporciona el orquestador de lotes, el guard de lotes de concurrencia acotada, el tiempo de espera por lote ni el traspaso de cumplimiento de Enterprise; una configuración que solicite la orquestación por lotes o el traspaso de cumplimiento en un despliegue solo con Pro no tiene ningún componente de Enterprise que la satisfaga. Consulte la descripción general de Pro para conocer la superficie del pipeline de Pro.

Nota sobre la frontera de Enterprise

La coordinación de lotes, los límites del guard de recursos y el cableado del traspaso de cumplimiento se describen únicamente a nivel de comportamiento. El protocolo interno de reparto del sidecar, la semántica interna de contrapresión y el cableado interno de la pasarela de cumplimiento quedan fuera del alcance de la superficie pública y no se reproducen aquí.

Frontera de despliegue

En producción, el reparto paralelo de workers y la contrapresión los gestiona un sidecar de ejecución independiente; el orquestador de PHP descrito aquí proporciona la coordinación de lotes y la lógica de traspaso de cumplimiento y lo invoca el worker de tareas, no los manejadores de peticiones directamente. El dimensionamiento del grupo de workers, el aprovisionamiento del sidecar y los límites de concurrencia en relación con el grupo de workers de PHP son responsabilidad del operador. El traspaso de cumplimiento es una ayuda de nueva validación, no un control de autorización.

Frontera de cumplimiento legal

El traspaso de cumplimiento opcional vuelve a ejecutar una pasada de validación sobre los documentos derivados. Informa de los hallazgos; no certifica un documento, no garantiza la suficiencia normativa ni constituye asesoramiento legal. Juzgar si una salida cumple sus obligaciones es responsabilidad suya.

Consulta también

• Pipeline de salida (referencia de Enterprise) — la referencia de la API del orquestador de lotes.
• Descripción general de Pro — el output pipeline subyacente.
• Descripción general de Enterprise
• Matriz de funciones: Core frente a Pro frente a Enterprise