Enterprise edizione

Output Pipeline — Riferimento approfondito

In breve

NextPDF\Enterprise\OutputPipeline esegue molti manifest di pipeline Pro come un unico batch. BatchPipelineOrchestrator avvolge il PipelineExecutor di Pro con il coordinamento del batch: un guard a risorse limitate sulla dimensione del batch, un timeout globale facoltativo del batch, l’iniezione di variabili per ciascun manifest e la contabilità aggregata. Un controllo di conformità facoltativo a fine batch riconvalida ogni output completato attraverso il gateway di conformità Enterprise e fallisce in modo chiuso. Ogni esecuzione restituisce un BatchPipelineResult che riporta i risultati per ciascun manifest, i conteggi dei completati e dei falliti, i tempi e il report di conformità facoltativo.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Una distribuzione priva di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Tier	Superficie output-pipeline
Core	Nessuna superficie output-pipeline.
Pro	Pipeline a singolo manifest (capability `pro.output.pipeline`).
Enterprise	Orchestrazione batch, limite sulla dimensione del batch, timeout del batch, handoff di conformità.

La superficie batch Enterprise non porta alcun codice di capability separato per funzionalità; è il confine del pacchetto a farne il gate. La capability Pro a singolo manifest pro.output.pipeline è un prerequisito, non il gate. Una licenza Pro da sola sblocca solo la pipeline a singolo manifest sottostante, non questa superficie batch.

composer require nextpdf/enterprise:^3

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	Config predefinita; nessun gateway; profilo `ComplianceProfile::PdfA4`	—	Nulla	Iniettare un gateway quando il controllo di conformità è abilitato; senza uno, ogni manifest controllato è riportato come fallito.
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	Esegue i manifest nell’ordine di invio; le variabili si risolvono per ID del manifest	`BatchPipelineResult`	`OverflowException` quando il batch supera i 10.000 manifest; eccezioni del gateway quando il controllo di conformità è abilitato (vedi Casi limite)	I `Throwable` del resolver non sfuggono mai; l’esecutore Pro li declassa a risultati di passo falliti.
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Concorrenza 4; nessun timeout; nessun controllo di conformità	—	Nulla	Value object readonly. `timeoutMs = 0` disabilita il timeout del batch.
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	Aggregazione sui valori `PipelineResult` per ciascun manifest	—	Nulla	Readonly. `complianceReport` resta `null` a meno che il controllo non sia stato eseguito.
`BatchPipelineResult::allSucceeded()`	—	Verifica `failedCount === 0`	`bool`	Nulla	Restituisce true su un batch troncato per timeout con zero fallimenti; vedi Casi limite.
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	Nulla	Restituisce `1.0` per un batch vuoto.
`BatchPipelineResult::hasComplianceReport()`	—	Verifica `complianceReport !== null`	`bool`	Nulla	—

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,
) {}

Contratto di comportamento

executeBatch() verifica per prima cosa la dimensione del batch rispetto a un limite di 10.000 manifest. Un batch oltre il limite solleva OverflowException prima che qualsiasi manifest venga eseguito; nulla degrada silenziosamente.

I manifest vengono quindi eseguiti nell’ordine di invio attraverso il PipelineExecutor di Pro. Ciascun manifest riceve la voce di variabili identificata dal suo ID in $variablesMap; un manifest privo di voce riceve una mappa di variabili vuota. Un manifest conta come completato quando lo stato del suo PipelineResult è Completed; qualsiasi altro stato terminale conta come fallito. Le eccezioni del resolver non sfuggono: l’esecutore Pro converte ogni Throwable del resolver in un risultato di passo fallito, così executeBatch() aggrega sempre i risultati anziché interrompere il batch a metà per un errore di passo.

Quando timeoutMs è maggiore di zero, il tempo trascorso viene controllato prima dell’avvio di ciascun manifest. Una volta esaurito il budget, i manifest rimanenti vengono saltati: non producono alcun PipelineResult e non contano né come completati né come falliti. totalManifests riporta sempre il conteggio inviato.

Quando complianceCheckOnComplete è abilitato, l’orchestratore convalida il PDF finale di ogni manifest completato rispetto al ComplianceProfile configurato attraverso il ComplianceGateway iniettato. Il controllo fallisce in modo chiuso:

Nessun gateway iniettato: ogni manifest controllato è riportato come fallito, poiché la conformità non è mai stata convalidata.
Nessun output PDF risolvibile dagli output dei passi del manifest: fallito.
Il gateway non restituisce alcun risultato (indisponibilità del sidecar in modalità facoltativa): fallito. L’assenza di un risultato positivo non è un passaggio.
Il gateway segnala una qualsiasi non conformità: fallito.

Il PDF finale viene risolto scansionando gli output dei passi di un manifest completato, dall’ultimo passo per primo, alla ricerca di un valore stringa diretto che inizia con l’header %PDF. Gli output dei passi non annidano mai stringhe di byte PDF dentro sotto-array; vengono ispezionati solo i valori di output diretti. I manifest che non si sono completati vengono saltati, non controllati.

Il report di conformità è un array con chiavi profile, checked, passed, failed e failures; ciascuna voce di fallimento porta manifestId e reason. Il report si allega a BatchPipelineResult::$complianceReport ed è raggiungibile tramite hasComplianceReport().

L’handoff di conformità è un ausilio di riconvalida, non un controllo di autorizzazione. Riporta solo findings.

Casi limite e modalità di errore

Più di 10.000 manifest: OverflowException prima che qualsiasi esecuzione inizi.
timeoutMs = 0 significa nessun timeout del batch. Impostare un valore finito in produzione.
Troncamento per timeout: i manifest saltati non compaiono in alcun conteggio, quindi completedCount + failedCount può essere inferiore a totalManifests. allSucceeded() verifica solo failedCount === 0 e può restituire true per un batch troncato. Confrontare count($result->results) con totalManifests per rilevare il troncamento.
successRate() restituisce 1.0 per un batch vuoto (zero manifest inviati).
Gli ID dei manifest non vengono deduplicati a livello di batch. Due manifest che condividono un ID vengono entrambi eseguiti e risolvono la stessa voce di variabili.
Gli errori strutturali del manifest (elenco di passi vuoto, ID di passo duplicati, dipendenza sconosciuta, ciclo di dipendenze, mancata corrispondenza del tipo di output, passo di ripresa mancante) sollevano InvalidArgumentException alla costruzione del manifest, prima che executeBatch() venga mai chiamato.
Con il controllo di conformità abilitato, ComplianceGateway::validate() può sollevare ComplianceSidecarUnavailableException (sidecar non disponibile in modalità obbligatoria) o InvalidArgumentException (nessun validatore registrato per il tool del profilo). Entrambe le eccezioni sfuggono da executeBatch() dopo l’esecuzione ma prima che il risultato sia costruito, quindi i risultati per ciascun manifest vanno persi per il chiamante. In modalità facoltativa il gateway restituisce null invece, e il manifest viene registrato come fallimento di conformità.
Un passo di handoff di conformità in-pipeline fallisce quando nessun output di passo a monte contiene byte PDF riconoscibili; non passa mai silenziosamente.
Questo modulo non esegue alcuna operazione crittografica; la modalità FIPS non è applicabile.

Conformità

Non viene rivendicata alcuna conformità a standard per questo modulo; è un layer di orchestrazione. Il controllo di conformità facoltativo rinvia al gateway di conformità Enterprise e ai suoi validatori esterni, che portano con sé i propri riferimenti. Il profilo predefinito è ComplianceProfile::PdfA4; altri profili del gateway coprono ulteriori target PDF/A, PDF/UA e PAdES.

Un report di conformità dichiara i findings del validatore rispetto al profilo selezionato. Non certifica un documento, non garantisce la sufficienza normativa e non costituisce consulenza legale. Valutare se un output soddisfi i propri obblighi è responsabilità dell’utente.

Note di sviluppo

Nelle distribuzioni di produzione, il dispatch dei worker paralleli e la backpressure sono gestiti da un sidecar di esecuzione separato. L’orchestratore PHP fornisce la logica di coordinamento del batch e di handoff di conformità ed è invocato dal job worker, non direttamente dagli handler di richiesta.
Il percorso di fallback PHP esegue i manifest in modo sequenziale. maxConcurrency limita i callback worker concorrenti nella distribuzione guidata dal sidecar; dimensionarlo rispetto al pool di worker PHP è responsabilità dell’operatore.
Il resolver del passo di handoff di conformità in-pipeline è un tipo interno registrato per i passi di tipo inspect. Abilitare la convalida a fine batch tramite BatchPipelineConfig anziché costruire direttamente passi di pipeline per essa.
Costruire le istanze di PipelineManifest presto. La loro convalida strutturale viene eseguita nel costruttore, quindi i grafi non validi falliscono rapidamente e non consumano mai budget del batch.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi di file di runbook e i prefissi di ticket sono fuori ambito.