Errori di runtime e supporto

Ambito

Queste voci documentano le eccezioni sollevate dal livello di supporto del runtime: la policy di degradazione, il trasporto HTTP basato su cURL, il circuit breaker di resilienza, l’emitter Security Information and Event Management (SIEM), il manifest di rendering, l’ispezione del PDF e il sottosistema di chaos-engineering.

Ogni eccezione NextPDF estende NextPdfException, che implementa ContextAwareExceptionInterface ed espone getContext(): array per il logging diagnostico strutturato. Una sottoclasse popola quell’array solo quando sovrascrive getContext(); la base restituisce un array vuoto. Tre eccezioni di questa pagina (DegradedException, CircuitBreakerOpenException e InspectException) estendono direttamente la RuntimeException di PHP ed espongono i propri dati tramite proprietà pubbliche readonly anziché tramite getContext(). Ogni voce seguente indica le proprietà o le chiavi di contesto esatte che la classe trasporta, tratte dal sorgente.

Policy di degradazione

`DegradedException`

Sollevata quando. La pipeline di rendering incontra una capacità degradata che viola la policy di degradazione attiva. Sotto DegradationPolicy::Strict, qualsiasi degradazione ad alto impatto (ComplianceRisk, SemanticLoss o Blocking) la solleva; sotto DegradationPolicy::Balanced, solo un impatto Blocking la solleva.
Classe. Estende direttamente RuntimeException (non NextPdfException), perciò non trasporta getContext().
Dati trasportati. Due proprietà pubbliche readonly: $capability (il value object Capability che ha innescato il rifiuto, inclusi id, status, reason, fallbackTarget e impact) e $policy (la DegradationPolicy attiva al momento del rifiuto). Il messaggio ha la forma Feature "<id>" is <status>: <reason> (policy: <policy>).
Recupero. Ispezionare $capability per individuare la funzionalità mancante e la sua causa. In alternativa, installare il componente richiesto dalla capacità, accettare una configurazione a impatto inferiore, oppure allentare la policy da Strict a Balanced quando la degradazione è accettabile per il caso d’uso. Chiamare $capability->isAvailable() / isDegraded() per pilotare la messaggistica rivolta all’utente.

Trasporto HTTP

Queste tre eccezioni hanno origine nel client PSR-18 basato su cURL e nel suo decorator security-aware. Le prime due estendono NextPdfException ma non sovrascrivono getContext(), perciò la loro getContext() restituisce un array vuoto; i dati diagnostici si raggiungono tramite l’accessor PSR-18 getRequest() e il throwable precedente concatenato.

`CurlNetworkException`

Sollevata quando. La richiesta HTTP non può essere completata a causa di un guasto a livello di rete: guasto di risoluzione Domain Name System (DNS), timeout di connessione o errore di handshake Transport Layer Security (TLS). È anche la classe che il decorator security-aware solleva per un rifiuto di sicurezza (rifiuto Server-Side Request Forgery, rifiuto di DNS-rebinding o un redirect negato).
Classe. Implementa PSR-18 Psr\Http\Client\NetworkExceptionInterface.
Dati trasportati. getRequest() restituisce la RequestInterface fallita. L’errore di trasporto originante, quando presente, è il throwable precedente concatenato. getContext() restituisce un array vuoto (il valore predefinito di base).
Recupero. Un guasto di rete può essere transitorio — riprovare con backoff se la richiesta è idempotente. Un rifiuto di sicurezza non è transitorio e deve adottare il fail-closed: non riprovare; correggere invece l’URL di destinazione o la policy SSRF. Leggere il messaggio e il throwable precedente per distinguere i due casi.

`CurlRequestException`

Sollevata quando. La richiesta stessa non può essere inviata perché è malformata, ad esempio un URL non valido o una richiesta che ha fallito la convalida SSRF prima di qualsiasi chiamata di rete.
Classe. Implementa PSR-18 Psr\Http\Client\RequestExceptionInterface.
Dati trasportati. getRequest() restituisce la RequestInterface problematica; la causa sottostante, quando presente, è il throwable precedente concatenato. getContext() restituisce un array vuoto.
Recupero. Si tratta di un difetto dell’input del chiamante o della policy, non di un guasto transitorio. Non riprovare senza modifiche. Correggere l’URL, gli header o il corpo della richiesta, oppure regolare la allowlist SSRF se la destinazione è legittimamente consentita, quindi riemettere la richiesta.

`TransientHttpException`

Sollevata quando. Internamente, all’interno di SecurityAwareHttpClient, per contrassegnare un guasto del trasporto interno genuinamente transitorio (DNS, connessione o timeout sollevato dal client PSR-18 interno) come idoneo al budget limitato di retry. È l’unica classe idonea al retry che il ciclo di retry del decorator riconosce; un’eccezione non racchiusa (un rifiuto di sicurezza sollevato dal decorator) viene trattata come fatale.
Classe. Implementa PSR-18 Psr\Http\Client\NetworkExceptionInterface. Contrassegnata @internal — viene creata e srotolata interamente all’interno di SecurityAwareHttpClient e non sfugge mai al decorator.
Dati trasportati. getRequest() restituisce la richiesta fallita. La ClientExceptionInterface originale del trasporto interno è conservata come throwable precedente concatenato (getPrevious()) e riemessa verbatim al chiamante una volta esaurito il budget di retry, così che il contratto pubblico PSR-18 resti invariato. getContext() restituisce un array vuoto.
Recupero. Il codice applicativo non intercetta direttamente questo tipo. Intercettare l’eccezione interna riemessa che il decorator restituisce dopo l’esaurimento del budget di retry, e trattare i guasti transitori ripetuti come un problema di disponibilità a monte.

Resilienza

`CircuitBreakerOpenException`

Sollevata quando. Un CircuitBreaker nello stato CircuitBreakerState::Open rifiuta una chiamata fail-fast, prima di qualsiasi invocazione a valle. Esiste per consentire ai chiamanti di distinguere “il servizio remoto è irraggiungibile in questo momento” (un guasto di trasporto transitorio, che vale la pena degradare) da “il pool di connessioni sarebbe stato esaurito da questa chiamata” (fail-fast, nessuna rete tentata) — la mitigazione batch del denial-of-service richiesta dai client Public Key Infrastructure (PKI).
Classe. Estende direttamente RuntimeException, perciò non trasporta getContext().
Dati trasportati. Due proprietà pubbliche readonly: $breakerName (l’identificatore del breaker aperto) e $secondsUntilHalfOpen (il cooldown approssimativo residuo prima che il breaker passi a half-open). Il messaggio ha la forma Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
Recupero. Non martellare il breaker — attendere almeno $secondsUntilHalfOpen prima di riprovare, oppure degradare l’operazione. Non è stata tentata alcuna chiamata di rete, perciò questo non è una prova che il servizio remoto stesso abbia fallito; è back-pressure che protegge il pool di connessioni.

Osservabilità

`SiemEmitterException`

Sollevata quando. Un emitter di eventi SIEM non può persistere o concatenare un record. Fa emergere guasti a livello di file system (open, lock, seek, write, fflush, read) e guasti di integrità della hash-chain (chain: indice fuori ordine, record di coda malformato o deriva del round-trip JSON) condivisi tra l’event log a hash-chain e gli adapter dell’emitter su file JSON-lines.
Classe. Estende NextPdfException e sovrascrive getContext().
Chiavi di contesto. operation (una tra open, lock, seek, write, fflush, read, chain), path (il percorso del log di destinazione) e detail (un dettaglio leggibile come conteggi di byte o indice atteso rispetto a effettivo). Queste sono raggiungibili anche tramite getOperation(), getPath() e getDetail(). Il messaggio ha la forma SIEM emitter <operation> failed for <path>: <detail>.
Recupero. Questo è azionabile da infrastruttura o SecOps, non dalla logica applicativa. Verificare il mount del volume di log, i permessi della directory, i descrittori di file disponibili e la salute del file system. Un guasto dell’operazione chain indica un segnale di manomissione o corruzione nell’audit log e dovrebbe essere indagato, non ritentato silenziosamente.

Manifest di rendering

`RenderManifestException`

Sollevata quando. Un RenderManifest non può essere costruito, deserializzato o letto a causa di un errore strutturale, di tipo o di compatibilità di schema. Il manifest è un contratto pubblico versionato inviato da ogni trasporto (CLI, coda Laravel, Symfony, l’API SaaS), perciò un manifest malformato o incompatibile viene fatto emergere direttamente anziché coercito ai valori predefiniti.
Classe. Estende NextPdfException e sovrascrive getContext(). I costruttori denominati impostano un codice stabile e leggibile a macchina nel namespace SPEC-MANIFEST-*:
- RenderManifestException::shape() → SPEC-MANIFEST-001 — errore di forma o di tipo durante RenderManifest::fromArray().
- RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — versione di schema major incompatibile (non leggibile).
- RenderManifestException::missingField() → SPEC-MANIFEST-003 — campo obbligatorio mancante durante la finalizzazione del builder.
- RenderManifestException::unsupported() → SPEC-MANIFEST-004 — un manifest ben formato fa riferimento a un input o a un template che il renderer corrente non può risolvere (ad esempio un input URI o un motore di template solo host).
Chiavi di contesto. manifest_code (l’identificatore SPEC-MANIFEST-*) e reason (la descrizione leggibile del guasto). Queste sono raggiungibili anche tramite getManifestCode() e getReason(). Il messaggio ha la forma [<code>] <reason>.
Recupero. Diramare su manifest_code. Per SPEC-MANIFEST-001 e SPEC-MANIFEST-003, correggere il payload del manifest (correggere il tipo del campo o fornire il campo mancante). Per SPEC-MANIFEST-002, rigenerare il manifest rispetto a una versione di schema major supportata oppure aggiornare il renderer. Per SPEC-MANIFEST-004, fornire un input o un motore di template che l’edizione corrente può risolvere.

Ispezione

`InspectException`

Sollevata quando. L’ispezione del PDF fallisce.
Classe. Estende direttamente RuntimeException (non NextPdfException), perciò non trasporta getContext().
Dati trasportati. Due proprietà pubbliche readonly: $inspectCode (un codice leggibile a macchina nel namespace INSPECT-*) e $retryable (un booleano che indica se il chiamante dovrebbe riprovare — ad esempio quando un sidecar di ispezione è temporaneamente inattivo). La causa originante, quando presente, è il throwable precedente concatenato.
Recupero. Diramare su $inspectCode per la classe di guasto specifica. Quando $retryable è true, riprovare con backoff perché il guasto è atteso come transitorio (come il riavvio di un sidecar); quando è false, considerare l’input o la configurazione come il difetto e non riprovare senza modifiche.

Chaos engineering

`ChaosReportWriteException`

Sollevata quando. ChaosScenarioRunner::writeReport() non può persistere su disco il report aggregato del chaos-day. È una sostituzione tipizzata per dominio di un errore di runtime generico, così che i chiamanti possano intercettare lo specifico guasto di scrittura su disco del report senza confonderlo con gli errori sollevati all’interno dei simulatori di scenario stessi (il runner li cattura come campi di ChaosOutcome).
Classe. Estende NextPdfException e sovrascrive getContext().
Chiavi di contesto. output_path (il percorso assoluto su cui il runner ha tentato di scrivere). È raggiungibile anche tramite getOutputPath(). Il messaggio ha la forma ChaosScenarioRunner: failed to write report to "<path>".
Recupero. Questo è un guasto lato scrittura del sink del report, non degli scenari. Verificare che la directory di output esista e sia scrivibile e che vi sia spazio su disco disponibile, quindi rieseguire la scrittura del report. Gli esiti del chaos non sono interessati.

`RetrievalUnavailableException`

Sollevata quando. Un endpoint di retrieval (ad esempio un servizio Voyage Retrieval Augmented Generation) non è disponibile e il sistema ripiega sulla modalità solo-cache oppure adotta il fail-closed.
Classe. Estende NextPdfException e sovrascrive getContext().
Chiavi di contesto. mode (la modalità operativa dopo il guasto — CACHED_ONLY quando i risultati sono serviti solo dalla cache semantica, oppure FAIL_CLOSED quando la richiesta è rifiutata interamente senza dati obsoleti) ed endpoint (l’endpoint divenuto irraggiungibile). Queste sono raggiungibili anche tramite getMode() e getEndpoint(). Il messaggio ha la forma Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
Recupero. Leggere mode per capire come il sistema sia degradato. Sotto CACHED_ONLY, i risultati possono essere obsoleti; aggiornarli una volta che l’endpoint si ripristina. Sotto FAIL_CLOSED, la richiesta è stata rifiutata di proposito e deve essere ritentata dopo che l’endpoint è raggiungibile. Ripristinare la connettività dell’endpoint (rete, credenziali, salute del servizio) prima di dipendere da un retrieval aggiornato.

Errori di runtime e supporto

Ambito

Policy di degradazione

DegradedException

Trasporto HTTP

CurlNetworkException

CurlRequestException

TransientHttpException

Resilienza

CircuitBreakerOpenException