Eseguire la diagnostica dell'ambiente in NextPDF Connect

In sintesi

Verificare che un server NextPDF Connect sia integro e disponga delle capacità necessarie al flusso di lavoro prima di avviare il lavoro effettivo. È il primo passo consigliato in qualsiasi pipeline basata su agenti. Gli strumenti, ricontrollati rispetto al registro degli strumenti del server, sono diagnostic.doctor, diagnostic.capabilities e diagnostic.verify. Il registro li espone con nomi di protocollo separati da punti e include anche un diagnostic.inspect correlato. Tutti sono Core.

Installazione

composer require nextpdf/server

Associare un trasporto. veraPDF è richiesto solo per il passaggio facoltativo di verifica della conformità. La verifica strutturale non richiede strumenti esterni.

Panoramica concettuale

diagnostic.doctor restituisce un report di stato di base: versione di PHP, estensioni caricate, versione del server, livello attivo ed eventuali avvisi. Usare status come gate. Con ok, procedere; con warning, leggere warnings; con error, arrestarsi.
diagnostic.capabilities elenca le capacità registrate con il relativo livello e stato di runtime (available, unavailable, degraded). Il numero di capacità dipende dal runtime e dal livello, quindi non fissare nel codice un totale. Verificare singolarmente ogni capacità da cui dipende il flusso di lavoro.
diagnostic.verify verifica l’integrità strutturale: l’intestazione del PDF, il marcatore EOF e la tabella dei riferimenti incrociati. Il controllo riguarda la struttura del documento raggiunta attraverso l’albero delle pagine (ISO 32000-2 §7.5). Con compliance_flavour, viene invocato anche veraPDF.

Un risultato diagnostico è una normale risposta in ogni trasporto (PSR-18 §p2).

Superficie API

Strumento	Ruolo	Livello di rischio
`diagnostic.doctor`	Report di stato dell’ambiente	Sicuro
`diagnostic.capabilities`	Inventario delle capacità con stato	Sicuro
`diagnostic.verify`	Verifica strutturale / di conformità	Sicuro
`create_pdf`, `add_text`, `output_pdf`	Test rapido di un documento	come documentato altrove

Questi sono i nomi di protocollo del registro. Il catalogo degli strumenti è il riferimento. La disponibilità di strumenti e capacità dipende dal livello installato, quindi non dichiarare mai un conteggio fisso di strumenti o capacità.

Esempio di codice — Avvio rapido

diagnostic.doctor (senza argomenti) → leggere status.
diagnostic.capabilities (senza argomenti) → confermare che ogni capacità necessaria risulti available.
create_pdf quindi add_text → un documento di test minimo.
diagnostic.verify con il document_id → controlli strutturali.
Facoltativamente diagnostic.verify con compliance_flavour: "4" → veraPDF.
output_pdf (base64) → eliminare la sessione di test.

Esempio di codice — Produzione

Subordinare la pipeline al valore di diagnostic.doctorstatus. Mappare ogni dipendenza del flusso di lavoro su uno specifico ID di capacità e verificare available prima di eseguire i passaggi dipendenti. Trattare degraded come un rischio di qualità che giustifica una verifica a campione. Eseguire sempre la verifica strutturale diagnostic.verify. Eseguire la variante di conformità solo quando la conformità è rilevante e tenere presente che, se veraPDF è assente, viene restituito un chiaro risultato di non trovato anziché un difetto del server.

Casi limite e insidie

veraPDF assente. La chiamata di conformità restituisce un risultato esplicito di non trovato. I controlli strutturali funzionano comunque. Se serve la verifica di conformità, installare veraPDF e inserirlo nel PATH del processo del server.
Timeout di veraPDF. I documenti di grandi dimensioni possono superare il timeout di verifica. Ridurre la dimensione del documento o aumentare il timeout nella configurazione del server.
Capacità degraded. Una dipendenza è disponibile solo parzialmente, quindi la qualità dell’output può diminuire. Controllare i log del server per il fallback utilizzato.
Doctor error. Un requisito critico non è soddisfatto. Non procedere.

Prestazioni

La verifica strutturale è veloce. Il percorso di conformità avvia veraPDF ed è limitato dal timeout di verifica. Il budget ampio riflette quel sottoprocesso.

Note di sicurezza

L’output diagnostico rivela dettagli dell’ambiente: la versione di PHP, le estensioni e il livello. Considerarlo riservato all’operatore e non esporlo a chiamanti non attendibili.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
Un risultato diagnostico è una normale risposta del trasporto.	PSR-18	§p2
L’integrità strutturale riguarda la struttura ancorata all’albero delle pagine.	ISO 32000-2	§7.5

La variante di conformità esegue veraPDF e ne riporta il verdetto. NextPDF non dichiara autonomamente la conformità: decide il validatore.

Contesto commerciale

Non applicabile — tutti gli strumenti diagnostici sono Core.

Disponibilità per trasporto

Trasporto	Disponibile	Note
MCP (stdio)	Sì	I risultati diagnostici sono risultati degli strumenti.
REST	Sì	Gli endpoint di stato corrispondono a questi strumenti.
gRPC	Sì	Unario; il risultato contiene gli stessi campi di stato.

Livello di rischio HITL

Tutti e tre gli strumenti diagnostici sono Sicuri: di sola lettura, senza alcun effetto collaterale. Non attivano mai il gate di conferma. L’output_pdf nel test rapido è in modalità base64 (Review, senza gate).

Envelope JSON del gate di conferma

Gli strumenti diagnostici non attivano mai il gate.

{ "allowed": true }