Pipeline de Saída

Em resumo

O NextPDF Enterprise coordena a execução em lote de larga escala de manifestos de output-pipeline do NextPDF Pro com um limite de concorrência configurável e um handoff de conformidade opcional sobre as saídas concluídas. Ele é a camada de lote acima do output pipeline do Pro.

Disponibilidade e licenciamento

Esta capacidade é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem esse direito não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

A superfície de lote do Enterprise se apoia sobre o output pipeline do Pro (pro.output.pipeline), que é um pré-requisito e não a restrição. Não há um código de capacidade por recurso separado; o orquestrador de lote e o handoff de conformidade estão disponíveis onde quer que o pacote licenciado nextpdf/enterprise esteja instalado.

Instalação

composer require nextpdf/enterprise:^3

Visão conceitual

O BatchPipelineOrchestrator executa muitas instâncias de PipelineManifest como um único lote. Cada manifesto passa pelo PipelineExecutor do Pro; o orquestrador acrescenta a coordenação do lote, um guarda de recursos limitados (o número de manifestos por lote é limitado), o tratamento de timeout por lote e um handoff de conformidade opcional.

O BatchPipelineConfig controla três coisas: o número máximo de callbacks de worker concorrentes, um timeout global de lote opcional em milissegundos e se uma verificação de conformidade é executada sobre cada saída após a conclusão do pipeline. Quando a verificação de conformidade está habilitada, o ComplianceHandoff se integra como uma etapa do pipeline que revalida cada PDF derivado por meio do gateway de conformidade do Enterprise, de modo que um documento modificado pelo pipeline seja reverificado em vez de ser confiado a partir do seu estado anterior à modificação.

Em implantações de produção, o dispatch paralelo de workers e a contrapressão (backpressure) são tratados por um sidecar de execução separado; o orquestrador PHP descrito aqui fornece a coordenação do lote e a lógica do handoff de conformidade, e é invocado pelo worker de jobs, em vez de diretamente pelos manipuladores de requisição.

Por que funciona assim

A geração em lote de alto volume se divide em duas preocupações: coordenar quais manifestos executam sob quais garantias e conduzir a vazão paralela bruta. O NextPDF mantém a coordenação e a semântica de conformidade neste orquestrador PHP determinístico e delega o dispatch paralelo de workers e a contrapressão a um sidecar de execução separado. Essa fronteira permite que a camada de vazão escale a concorrência de forma independente, enquanto o orquestrador permanece simples, limitado e auditável. Um limite rígido de manifestos por lote mantém o pico de memória previsível, de modo que uma única submissão grande não possa degradar o pool de workers. O handoff de conformidade revalida cada saída derivada em vez de confiar no seu estado anterior à modificação, e falha de forma fechada. Um manifesto concluído passa somente quando o gateway confirma a conformidade, nunca por padrão.

Contexto de projeto: Geração de documentos de alto volume.

Superfície de API

Classe	Responsabilidade
BatchPipelineOrchestrator	Executa muitos manifestos como um lote com concorrência limitada.
BatchPipelineConfig	Concorrência máxima, timeout de lote, alternância de conformidade na conclusão.
BatchPipelineResult	Agregado: resultados por manifesto, contagens de concluídos e falhos, tempos.
ComplianceHandoff	Etapa opcional de revalidação de conformidade ao fim do pipeline.

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

use NextPDF\Enterprise\OutputPipeline\BatchPipelineOrchestrator;

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

Exemplo de código — Produção

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 extremos e pegadinhas

• O lote impõe um limite superior ao número de manifestos; excedê-lo gera um erro do guarda de recursos em vez de degradar silenciosamente.
• Um timeout global de zero significa nenhum timeout de lote; defina um valor finito em produção, de modo que um manifesto travado não bloqueie o lote indefinidamente.
• O handoff de conformidade requer um PDF reconhecível na saída da etapa a montante; se nenhum for encontrado, a etapa relata uma falha para aquele manifesto em vez de passar silenciosamente.
• Este módulo depende do output pipeline do Pro; ele acrescenta coordenação de lote, não um novo modelo de etapas.

Desempenho

O throughput escala com a concorrência configurada e o custo por manifesto. A concorrência deve ser definida de forma conservadora em relação ao pool de workers, de modo que os callbacks não o saturem. O limite de manifestos por lote restringe o pico de memória.

Notas de segurança

O orquestrador de lote processa quaisquer manifestos e variáveis que o chamador forneça; trate as entradas do pipeline como você trataria qualquer outra carga de trabalho de PDF não confiável. O handoff de conformidade é um auxílio de revalidação, não um controle de autorização.

Residência de dados e mitigações de PII

As saídas em lote podem conter dados pessoais. O processamento é em processo e local; nenhuma chamada de rede de saída é feita por este orquestrador. Aplique seus próprios controles de retenção às saídas em lote.

Telemetria segura e limpeza de logs

Os resultados de lote relatam contagens e tempos, não o conteúdo do documento. Limpe os identificadores de manifesto dos logs se eles codificarem dados de tenant ou de caso.

Conformidade

Nenhuma conformidade com padrões é reivindicada para este módulo; ele é uma camada de orquestração. O handoff de conformidade opcional delega ao gateway de conformidade do Enterprise, que carrega suas próprias referências.

Comportamento em modo FIPS

Este módulo não realiza nenhuma operação criptográfica.

Modelo de ameaças

As entradas principais são manifestos e variáveis fornecidos pelo chamador. Mitigações: um limite rígido de manifestos por lote, concorrência limitada, revalidação opcional das saídas derivadas e nenhum I/O de rede no próprio orquestrador.

Contrato de comportamento

• executeBatch() executa cada manifesto por meio do executor de pipeline do Pro e retorna resultados por manifesto com contagens de concluídos e falhos e tempos.
• Um limite rígido restringe o número de manifestos por lote; excedê-lo gera um erro do guarda de recursos em vez de degradar silenciosamente.
• Um timeout global de zero significa nenhum timeout de lote; um valor finito restringe um manifesto travado.
• Quando habilitado, o handoff de conformidade revalida cada PDF derivado e relata uma falha de etapa quando nenhum PDF reconhecível é encontrado a montante, em vez de passar silenciosamente.

Limite de publicação

Esta página documenta apenas comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tickets estão fora do escopo.

Fallback no Core

O NextPDF Core não tem modelo de output pipeline. Uma implantação somente Core compõe suas próprias etapas diretamente contra a API do Core; não há manifesto, nem coordenação de lote, nem handoff de conformidade.

Fallback no Pro

Em uma implantação somente Pro, a superfície suportada é o output pipeline do Pro de manifesto único (pro.output.pipeline): o PipelineExecutor do Pro executa um manifesto por vez. O Pro não fornece o orquestrador de lote, o guarda de lote com concorrência limitada, o timeout por lote ou o handoff de conformidade do Enterprise; uma configuração que solicite a orquestração em lote ou o handoff de conformidade em uma implantação somente Pro não tem nenhum componente Enterprise para satisfazê-la. Consulte a visão geral do Pro para conhecer a superfície de pipeline do Pro.

Nota sobre o limite do Enterprise

A coordenação do lote, os limites do guarda de recursos e a fiação (wiring) do handoff de conformidade são descritos apenas no nível de comportamento. O protocolo interno de dispatch do sidecar, a semântica interna de contrapressão e a fiação interna do gateway de conformidade estão fora do escopo da superfície pública e não são reproduzidos aqui.

Limite de implantação

Em produção, o dispatch paralelo de workers e a contrapressão são tratados por um sidecar de execução separado; o orquestrador PHP descrito aqui fornece a coordenação do lote e a lógica do handoff de conformidade e é invocado pelo worker de jobs, não diretamente pelos manipuladores de requisição. O dimensionamento do pool de workers, o provisionamento do sidecar e os limites de concorrência em relação ao pool de workers PHP são responsabilidade do operador. O handoff de conformidade é um auxílio de revalidação, não um controle de autorização.

Limite legal e de conformidade

O handoff de conformidade opcional reexecuta uma passagem de validação sobre os documentos derivados. Ele relata achados; ele não certifica um documento, não garante a suficiência regulatória nem constitui aconselhamento jurídico. Avaliar se uma saída atende às suas obrigações é responsabilidade sua.

Veja também

• Output pipeline (referência do Enterprise) — a referência de API do orquestrador de lote.
• Visão geral do Pro — o output pipeline subjacente.
• Visão geral do Enterprise
• Matriz de recursos Core vs Pro vs Enterprise