Enterprise edição

Output Pipeline — Referência Profunda

Visão geral

NextPDF\Enterprise\OutputPipeline executa muitos manifestos de pipeline do Pro como um único lote. BatchPipelineOrchestrator envolve o PipelineExecutor do Pro com coordenação de lotes: uma guarda de recursos delimitados sobre o tamanho do lote, um tempo limite global de lote opcional, injeção de variáveis por manifesto e contabilização agregada. Uma verificação de conformidade opcional ao fim do lote revalida cada saída concluída por meio do gateway de conformidade do Enterprise e falha de forma fechada (fail closed). Cada execução retorna um BatchPipelineResult que carrega os resultados por manifesto, as contagens de concluídos e falhados, a temporização e o relatório de conformidade opcional.

Disponibilidade e licenciamento

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

Nível	Superfície do output-pipeline
Core	Sem superfície de output-pipeline.
Pro	Pipeline de manifesto único (capacidade `pro.output.pipeline`).
Enterprise	Orquestração de lotes, limite de tamanho de lote, tempo limite de lote, handoff de conformidade.

A superfície de lotes do Enterprise não carrega um código de capacidade separado por recurso; o limite do pacote a restringe. A capacidade Pro de manifesto único pro.output.pipeline é um pré-requisito, não a restrição. Uma licença Pro sozinha desbloqueia apenas o pipeline de manifesto único subjacente, não esta superfície de lotes.

composer require nextpdf/enterprise:^3

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Config padrão; sem gateway; perfil `ComplianceProfile::PdfA4`	—	Nada	Injete um gateway quando a verificação de conformidade estiver habilitada; sem um, todo manifesto verificado é reportado como falhado.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Executa os manifestos na ordem de submissão; as variáveis resolvem pelo ID do manifesto	`BatchPipelineResult`	`OverflowException` quando o lote excede 10.000 manifestos; exceções do gateway quando a verificação de conformidade está habilitada (ver Casos extremos)	`Throwable`s de resolver nunca escapam; o executor do Pro os rebaixa a resultados de etapa falhados.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Concorrência 4; sem tempo limite; sem verificação de conformidade	—	Nada	Objeto de valor readonly. `timeoutMs = 0` desabilita o tempo limite de lote.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Agrega os valores `PipelineResult` por manifesto	—	Nada	Readonly. `complianceReport` permanece `null` a menos que a verificação seja executada.
`BatchPipelineResult::allSucceeded()`	—	Testa `failedCount === 0`	`bool`	Nada	Retorna true em um lote truncado por tempo limite com zero falhas; ver Casos extremos.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Nada	Retorna `1.0` para um lote vazio.
`BatchPipelineResult::hasComplianceReport()`	—	Testa `complianceReport !== null`	`bool`	Nada	—

public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}

public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult

public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

Contrato de comportamento

executeBatch() primeiro verifica o tamanho do lote contra um limite de 10.000 manifestos. Um lote acima do limite levanta OverflowException antes de qualquer manifesto executar; nada degrada silenciosamente.

Os manifestos então executam na ordem de submissão por meio do PipelineExecutor do Pro. Cada manifesto recebe a entrada de variáveis indexada por seu ID em $variablesMap; um manifesto sem entrada recebe um mapa de variáveis vazio. Um manifesto conta como concluído quando o status de seu PipelineResult é Completed; qualquer outro status terminal conta como falhado. As exceções de resolver não escapam: o executor do Pro converte cada Throwable de resolver em um resultado de etapa falhado, então executeBatch() sempre agrega resultados em vez de abortar no meio do lote em um erro de etapa.

Quando timeoutMs é maior que zero, o tempo decorrido é verificado antes de cada manifesto iniciar. Uma vez que o orçamento se esgota, os manifestos restantes são ignorados: eles não produzem nenhum PipelineResult e não contam como concluídos nem falhados. totalManifests sempre reporta a contagem submetida.

Quando complianceCheckOnComplete está habilitado, o orquestrador valida o PDF final de cada manifesto concluído contra o ComplianceProfile configurado por meio do ComplianceGateway injetado. A verificação falha de forma fechada (fail closed):

Nenhum gateway injetado: todo manifesto verificado é reportado como falhado, já que a conformidade nunca foi validada.
Nenhuma saída PDF resolvível a partir das saídas de etapa do manifesto: falhado.
O gateway não retorna resultado (indisponibilidade do sidecar em modo opcional): falhado. A ausência de um resultado positivo não é uma aprovação.
O gateway reporta qualquer não conformidade: falhado.

O PDF final é resolvido varrendo as saídas de etapa de um manifesto concluído, da última etapa para a primeira, em busca de um valor de string direto que comece com o cabeçalho %PDF. As saídas de etapa nunca aninham strings de bytes de PDF dentro de subarrays; apenas valores de saída diretos são inspecionados. Manifestos que não foram concluídos são ignorados, não verificados.

O relatório de conformidade é um array com as chaves profile, checked, passed, failed e failures; cada entrada de falha carrega manifestId e reason. O relatório se anexa a BatchPipelineResult::$complianceReport e é acessível via hasComplianceReport().

O handoff de conformidade é um auxílio de revalidação, não um controle de autorização. Ele apenas informa achados.

Casos extremos e modos de falha

Mais de 10.000 manifestos: OverflowException antes de qualquer execução iniciar.
timeoutMs = 0 significa sem tempo limite de lote. Defina um valor finito em produção.
Truncamento por tempo limite: manifestos ignorados não aparecem em nenhuma contagem, então completedCount + failedCount pode ser menor que totalManifests. allSucceeded() testa apenas failedCount === 0 e pode retornar true para um lote truncado. Compare count($result->results) com totalManifests para detectar o truncamento.
successRate() retorna 1.0 para um lote vazio (zero manifestos submetidos).
Os IDs de manifesto não são desduplicados no nível do lote. Dois manifestos que compartilham um ID ambos executam e resolvem a mesma entrada de variáveis.
Erros estruturais de manifesto (lista de etapas vazia, IDs de etapa duplicados, dependência desconhecida, ciclo de dependência, incompatibilidade de tipo de saída, etapa de retomada ausente) levantam InvalidArgumentException na construção do manifesto, antes de executeBatch() sequer ser chamado.
Com a verificação de conformidade habilitada, ComplianceGateway::validate() pode lançar ComplianceSidecarUnavailableException (sidecar indisponível em modo obrigatório) ou InvalidArgumentException (nenhum validador registrado para a ferramenta do perfil). Qualquer uma das exceções escapa de executeBatch() após a execução, mas antes de o resultado ser construído, então os resultados por manifesto se perdem para o chamador. Em modo opcional o gateway retorna null em vez disso, e o manifesto é registrado como uma falha de conformidade.
Uma etapa de handoff de conformidade dentro do pipeline falha quando nenhuma saída de etapa a montante contém bytes de PDF reconhecíveis; ela nunca passa silenciosamente.
Este módulo não realiza nenhuma operação criptográfica; o modo FIPS não é aplicável.

Conformidade

Nenhuma conformidade com padrões é declarada para este módulo; ele é uma camada de orquestração. A verificação de conformidade opcional recorre ao gateway de conformidade do Enterprise e a seus validadores externos, que carregam suas próprias referências. O perfil padrão é ComplianceProfile::PdfA4; outros perfis do gateway cobrem alvos adicionais de PDF/A, PDF/UA e PAdES.

Um relatório de conformidade declara os achados do validador contra o perfil selecionado. Ele não certifica um documento, não garante suficiência regulatória, nem constitui aconselhamento jurídico. Julgar se uma saída cumpre suas obrigações é responsabilidade sua.

Notas de desenvolvimento

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 fornece a coordenação de lotes e a lógica de handoff de conformidade e é invocado pelo worker de job, não diretamente pelos handlers de requisição.
O caminho de fallback em PHP executa os manifestos sequencialmente. maxConcurrency delimita os callbacks de worker concorrentes na implantação dirigida por sidecar; dimensioná-lo em relação ao pool de workers PHP é responsabilidade do operador.
O resolver da etapa de handoff de conformidade dentro do pipeline é um tipo interno registrado para etapas do tipo inspect. Habilite a validação ao fim do lote por meio de BatchPipelineConfig em vez de construir etapas de pipeline diretamente para isso.
Construa as instâncias de PipelineManifest cedo. Sua validação estrutural é executada no construtor, então grafos inválidos falham rápido e nunca consomem orçamento do lote.

Limite de publicação

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