Pipeline di output

In sintesi

NextPDF Enterprise coordina l’esecuzione in batch su larga scala dei manifest della pipeline di output di NextPDF Pro con un limite di concorrenza configurabile e un handoff di compliance facoltativo sugli output completati. È il layer di batch sopra la pipeline di output di Pro.

Disponibilità e licenze

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

La superficie di batch Enterprise si basa sulla pipeline di output di Pro (pro.output.pipeline), che è un prerequisito anziché il gate. Non esiste un codice di capability per-feature separato; l’orchestratore di batch e l’handoff di compliance sono disponibili ovunque sia installato il pacchetto con licenza nextpdf/enterprise.

Installazione

composer require nextpdf/enterprise:^3

Panoramica concettuale

BatchPipelineOrchestrator esegue molte istanze PipelineManifest come un unico batch. Ogni manifest viene eseguito tramite il PipelineExecutor di Pro; l’orchestratore aggiunge il coordinamento del batch, una guardia di risorse limitata (il numero di manifest per batch è limitato), la gestione del timeout per ciascun batch e un handoff di compliance facoltativo.

BatchPipelineConfig controlla tre cose: il numero massimo di callback worker concorrenti, un timeout di batch globale facoltativo in millisecondi e se un controllo di compliance viene eseguito su ogni output dopo il completamento della pipeline. Quando il controllo di compliance è abilitato, ComplianceHandoff si integra come passaggio della pipeline che riconvalida ogni PDF derivato tramite il gateway di compliance Enterprise, così che un documento modificato dalla pipeline venga ricontrollato anziché ritenuto attendibile in base al suo stato precedente alla modifica.

Nelle distribuzioni di produzione, il dispatch parallelo dei worker e la backpressure sono gestiti da un sidecar di esecuzione separato; l’orchestratore PHP qui descritto fornisce il coordinamento del batch e la logica di handoff di compliance, ed è invocato dal job worker anziché direttamente dai gestori delle richieste.

Perché funziona così

La generazione in batch ad alto volume si divide in due aspetti: coordinare quali manifest vengono eseguiti sotto quali garanzie e guidare il throughput parallelo grezzo. NextPDF mantiene la semantica di coordinamento e di compliance in questo orchestratore PHP deterministico e delega il dispatch parallelo dei worker e la backpressure a un sidecar di esecuzione separato. Quel confine consente al layer di throughput di scalare la concorrenza in modo indipendente, mentre l’orchestratore resta semplice, limitato e verificabile. Un limite rigido di manifest per batch mantiene prevedibile il picco di memoria, così che una singola grande sottomissione non possa degradare il pool di worker. L’handoff di compliance riconvalida ogni output derivato anziché ritenere attendibile il suo stato precedente alla modifica, e fallisce in modo chiuso. Un manifest completato passa solo quando il gateway conferma la conformità, mai per impostazione predefinita.

Contesto di progettazione: Generazione di documenti ad alto volume.

Superficie API

Classe	Responsabilità
BatchPipelineOrchestrator	Eseguire molti manifest come un batch con concorrenza limitata.
BatchPipelineConfig	Concorrenza massima, timeout del batch, toggle di compliance al completamento.
BatchPipelineResult	Aggregato: risultati per ciascun manifest, conteggi di completati e falliti, tempi.
ComplianceHandoff	Passaggio facoltativo di riconvalida di compliance a fine pipeline.

Esempio di codice — Avvio rapido

use NextPDF\Enterprise\OutputPipeline\BatchPipelineOrchestrator;

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

Esempio di codice — Produzione

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,
]);

Casi limite e insidie

• Il batch impone un limite superiore al numero di manifest; superarlo solleva un errore della guardia di risorse anziché degradare silenziosamente.
• Un timeout globale pari a zero significa nessun timeout del batch; impostare un valore finito in produzione in modo che un manifest bloccato non possa bloccare il batch a tempo indeterminato.
• L’handoff di compliance richiede un PDF riconoscibile nell’output del passaggio a monte; se non ne viene trovato alcuno, il passaggio segnala un fallimento per quel manifest anziché passare silenziosamente.
• Questo modulo dipende dalla pipeline di output di Pro; aggiunge il coordinamento del batch, non un nuovo modello di passaggi.

Prestazioni

Il throughput cresce con la concorrenza configurata e con il costo per ciascun manifest. La concorrenza dovrebbe essere impostata in modo conservativo rispetto al pool di worker, in modo che i callback non lo saturino. Il limite di manifest per ciascun batch delimita il picco di memoria.

Note di sicurezza

L’orchestratore di batch elabora qualsiasi manifest e variabile fornito dal chiamante; trattare gli input della pipeline come si tratterebbe qualsiasi altro carico di lavoro PDF non attendibile. L’handoff di compliance è un ausilio di riconvalida, non un controllo di autorizzazione.

Residenza dei dati e mitigazioni dei dati personali (PII)

Gli output del batch possono contenere dati personali. L’elaborazione è in-process e locale; questo orchestratore non effettua alcuna chiamata di rete in uscita. Applicare i propri controlli di conservazione agli output del batch.

Telemetria sicura e sanificazione dei log

I risultati del batch riportano conteggi e tempi, non il contenuto del documento. Sanificare gli identificatori dei manifest dai log se codificano dati di tenant o di caso.

Conformità

Non viene asserita alcuna conformità agli standard per questo modulo; è un layer di orchestrazione. L’handoff di compliance facoltativo si rimette al gateway di compliance Enterprise, che porta i propri riferimenti.

Comportamento in modalità FIPS

Questo modulo non esegue alcuna operazione crittografica.

Modello di minaccia

Gli input principali sono manifest e variabili forniti dal chiamante. Mitigazioni: un limite rigido di manifest per batch, concorrenza limitata, riconvalida facoltativa degli output derivati e nessun I/O di rete nell’orchestratore stesso.

Contratto di comportamento

• executeBatch() esegue ogni manifest tramite il pipeline executor di Pro e restituisce i risultati per ciascun manifest con i conteggi di completati e falliti e i tempi.
• Un limite rigido delimita il numero di manifest per batch; superarlo solleva un errore della guardia di risorse anziché degradare silenziosamente.
• Un timeout globale pari a zero significa nessun timeout del batch; un valore finito delimita un manifest bloccato.
• Quando abilitato, l’handoff di compliance riconvalida ogni PDF derivato e segnala un fallimento del passaggio quando a monte non viene trovato alcun PDF riconoscibile, anziché passare silenziosamente.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Fallback di Core

NextPDF Core non dispone di alcun modello di pipeline di output. Una distribuzione solo Core compone i propri passaggi direttamente sull’API di Core; non esiste alcun manifest, alcun coordinamento di batch né alcun handoff di compliance.

Fallback di Pro

In una distribuzione solo Pro, la superficie supportata è la pipeline di output Pro a manifest singolo (pro.output.pipeline): il PipelineExecutor di Pro esegue un manifest alla volta. Pro non fornisce l’orchestratore di batch, la guardia di batch a concorrenza limitata, il timeout per ciascun batch né l’handoff di compliance Enterprise; una configurazione che richiede l’orchestrazione in batch o l’handoff di compliance in una distribuzione solo Pro non ha alcuna componente Enterprise che la soddisfi. Vedere Panoramica di Pro per la superficie della pipeline di Pro.

Nota sul confine Enterprise

Il coordinamento del batch, i limiti della guardia di risorse e il cablaggio dell’handoff di compliance sono descritti solo a livello di comportamento. Il protocollo interno di dispatch del sidecar, la semantica interna di backpressure e il cablaggio interno del gateway di compliance sono fuori ambito per la superficie pubblica e non sono qui riprodotti.

Confine di distribuzione

In produzione, il dispatch parallelo dei worker e la backpressure sono gestiti da un sidecar di esecuzione separato; l’orchestratore PHP qui descritto fornisce il coordinamento del batch e la logica di handoff di compliance ed è invocato dal job worker, non direttamente dai gestori delle richieste. Il dimensionamento del pool di worker, il provisioning del sidecar e i limiti di concorrenza rispetto al pool di worker PHP sono responsabilità dell’operatore. L’handoff di compliance è un ausilio di riconvalida, non un controllo di autorizzazione.

Confine di conformità legale

L’handoff di compliance facoltativo ri-esegue un passaggio di convalida sui documenti derivati. Riporta rilievi; non certifica un documento, non garantisce la sufficienza normativa e non costituisce un parere legale. Valutare se un output soddisfa i propri obblighi è una responsabilità dell’utente.

Vedere anche

• Pipeline di output (riferimento Enterprise) — il riferimento API dell’orchestratore di batch.
• Panoramica di Pro — la pipeline di output sottostante.
• Panoramica di Enterprise
• Matrice delle funzionalità Core vs Pro vs Enterprise