Erreurs d'exécution et de support

Portée

Ces entrées documentent les exceptions levées par la couche de support d’exécution : la politique de dégradation, le transport HTTP adossé à cURL, le disjoncteur de résilience, l’émetteur Security Information and Event Management (SIEM), le manifeste de rendu, l’inspection PDF et le sous-système d’ingénierie du chaos.

Chaque exception NextPDF étend NextPdfException, qui implémente ContextAwareExceptionInterface et expose getContext(): array pour la journalisation de diagnostic structurée. Une sous-classe ne peuple ce tableau que lorsqu’elle redéfinit getContext() ; la base renvoie un tableau vide. Trois exceptions sur cette page (DegradedException, CircuitBreakerOpenException et InspectException) étendent directement la RuntimeException de PHP et exposent leurs données via des propriétés readonly publiques au lieu de getContext(). Chaque entrée ci-dessous nomme les propriétés ou clés de contexte exactes que porte la classe, tirées de la source.

Politique de dégradation

`DegradedException`

Levée lorsque. Le pipeline de rendu rencontre une capacité dégradée qui viole la politique de dégradation active. Sous DegradationPolicy::Strict, toute dégradation à fort impact (ComplianceRisk, SemanticLoss ou Blocking) la lève ; sous DegradationPolicy::Balanced, seul un impact Blocking la lève.
Classe. Étend directement RuntimeException (pas NextPdfException), donc elle ne porte pas de getContext().
Données portées. Deux propriétés readonly publiques : $capability (l’objet-valeur Capability qui a déclenché le rejet, incluant son id, status, reason, fallbackTarget et impact) et $policy (la DegradationPolicy active au moment du rejet). Le message a la forme Feature "<id>" is <status>: <reason> (policy: <policy>).
Rétablissement. Inspecte $capability pour identifier la fonctionnalité manquante et sa cause. Soit installe le composant que la capacité requiert, accepte une configuration à plus faible impact, ou relâche la politique de Strict à Balanced lorsque la dégradation est acceptable pour le cas d’usage. Appelle $capability->isAvailable() / isDegraded() pour piloter le message destiné à l’utilisateur.

Transport HTTP

Ces trois exceptions proviennent du client PSR-18 adossé à cURL et de son décorateur sensible à la sécurité. Les deux premières étendent NextPdfException mais ne redéfinissent pas getContext(), donc leur getContext() renvoie un tableau vide ; les données de diagnostic sont atteintes via l’accesseur PSR-18 getRequest() et le throwable précédent chaîné.

`CurlNetworkException`

Levée lorsque. La requête HTTP ne peut pas être complétée à cause d’une faute de niveau réseau : échec de résolution du Domain Name System (DNS), délai d’attente de connexion, ou erreur de poignée de main Transport Layer Security (TLS). C’est aussi la classe que le décorateur sensible à la sécurité lève pour un rejet de sécurité (refus de Server-Side Request Forgery, refus de DNS-rebinding, ou redirection refusée).
Classe. Implémente PSR-18 Psr\Http\Client\NetworkExceptionInterface.
Données portées. getRequest() renvoie le RequestInterface en échec. L’erreur de transport d’origine, lorsqu’elle est présente, est le throwable précédent chaîné. getContext() renvoie un tableau vide (la valeur par défaut de la base).
Rétablissement. Une faute réseau peut être transitoire — réessaie avec un backoff si la requête est idempotente. Un rejet de sécurité n’est pas transitoire et doit échouer en mode fermé : ne réessaie pas ; corrige plutôt l’URL cible ou la politique SSRF. Lis le message et le throwable précédent pour distinguer les deux.

`CurlRequestException`

Levée lorsque. La requête elle-même ne peut pas être envoyée parce qu’elle est malformée, par exemple une URL invalide ou une requête qui a échoué à la validation SSRF avant tout appel réseau.
Classe. Implémente PSR-18 Psr\Http\Client\RequestExceptionInterface.
Données portées. getRequest() renvoie le RequestInterface fautif ; la cause sous-jacente, lorsqu’elle est présente, est le throwable précédent chaîné. getContext() renvoie un tableau vide.
Rétablissement. C’est un défaut d’entrée de l’appelant ou de politique, pas une faute transitoire. Ne réessaie pas sans changement. Corrige l’URL, les en-têtes ou le corps de la requête, ou ajuste la liste d’autorisation SSRF si la cible est légitimement permise, puis réémets la requête.

`TransientHttpException`

Levée lorsque. En interne, dans SecurityAwareHttpClient, pour marquer une faute de transport interne réellement transitoire (DNS, connexion, ou délai d’attente levé par le client PSR-18 interne) comme éligible au budget de réessai borné. C’est la seule classe éligible au réessai que la boucle de réessai du décorateur reconnaît ; une exception non enveloppée (un rejet de sécurité levé par le décorateur) est traitée comme fatale.
Classe. Implémente PSR-18 Psr\Http\Client\NetworkExceptionInterface. Marquée @internal — elle est créée et déballée entièrement au sein de SecurityAwareHttpClient et ne s’échappe jamais du décorateur.
Données portées. getRequest() renvoie la requête en échec. La ClientExceptionInterface de transport interne d’origine est préservée comme throwable précédent chaîné (getPrevious()) et refaite remonter telle quelle à l’appelant une fois le budget de réessai épuisé, de sorte que le contrat PSR-18 public est inchangé. getContext() renvoie un tableau vide.
Rétablissement. Le code applicatif n’attrape pas ce type directement. Attrape l’exception interne refaite remonter que le décorateur renvoie une fois le budget de réessai dépensé, et traite des échecs transitoires répétés comme un problème de disponibilité en amont.

Résilience

`CircuitBreakerOpenException`

Levée lorsque. Un CircuitBreaker dans l’état CircuitBreakerState::Open rejette un appel en échouant vite, avant toute invocation en aval. Elle existe pour permettre aux appelants de distinguer « le service distant est inaccessible maintenant » (une faute de transport transitoire, qui mérite de se dégrader) de « le pool de connexions aurait été épuisé par cet appel » (échec vite, aucun réseau tenté) — la mitigation de déni de service par lot requise pour les clients d’infrastructure à clé publique (PKI).
Classe. Étend directement RuntimeException, donc elle ne porte pas de getContext().
Données portées. Deux propriétés readonly publiques : $breakerName (l’identifiant du disjoncteur ouvert) et $secondsUntilHalfOpen (le temps de refroidissement approximatif restant avant que le disjoncteur ne passe en semi-ouvert). Le message a la forme Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
Rétablissement. Ne martèle pas le disjoncteur — attends au moins $secondsUntilHalfOpen avant de réessayer, ou dégrade l’opération. Aucun appel réseau n’a été tenté, donc ce n’est pas une preuve que le service distant lui-même a échoué ; c’est une contre-pression qui protège le pool de connexions.

Observabilité

`SiemEmitterException`

Levée lorsque. Un émetteur d’événements SIEM ne peut pas persister ni chaîner un enregistrement. Elle fait remonter les échecs de niveau système de fichiers (open, lock, seek, write, fflush, read) et les fautes d’intégrité de chaîne de hachage (chain : index dans le désordre, enregistrement de queue malformé, ou dérive d’aller-retour JSON) partagées entre le journal d’événements à chaîne de hachage et les adaptateurs d’émetteur de fichier JSON-lines.
Classe. Étend NextPdfException et redéfinit getContext().
Clés de contexte. operation (l’une de open, lock, seek, write, fflush, read, chain), path (le chemin du journal cible) et detail (un détail lisible par un humain tel que des nombres d’octets ou un index attendu-contre-réel). Celles-ci sont aussi atteignables via getOperation(), getPath() et getDetail(). Le message a la forme SIEM emitter <operation> failed for <path>: <detail>.
Rétablissement. Ceci est actionnable par l’infrastructure ou le SecOps, pas par la logique applicative. Vérifie le montage du volume de journaux, les permissions de répertoire, les descripteurs de fichier disponibles et la santé du système de fichiers. Un échec d’opération chain indique un signal d’altération ou de corruption dans le journal d’audit et devrait faire l’objet d’une enquête, pas d’un réessai silencieux.

Manifeste de rendu

`RenderManifestException`

Levée lorsque. Un RenderManifest ne peut pas être construit, désérialisé ou lu à cause d’une erreur structurelle, de type ou de compatibilité de schéma. Le manifeste est un contrat public versionné soumis par chaque transport (CLI, file d’attente Laravel, Symfony, l’API SaaS), donc un manifeste malformé ou incompatible est fait remonter directement plutôt que coercé vers des valeurs par défaut.
Classe. Étend NextPdfException et redéfinit getContext(). Les constructeurs nommés fixent un code stable lisible par machine dans l’espace de noms SPEC-MANIFEST-* :
- RenderManifestException::shape() → SPEC-MANIFEST-001 — erreur de forme ou de type pendant RenderManifest::fromArray().
- RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — version majeure de schéma incompatible (ne peut pas être lue).
- RenderManifestException::missingField() → SPEC-MANIFEST-003 — champ requis manquant lors de la finalisation par le builder.
- RenderManifestException::unsupported() → SPEC-MANIFEST-004 — un manifeste bien formé référence une entrée ou un modèle que le renderer actuel ne peut pas résoudre (par exemple une entrée URI ou un moteur de modèles propre à l’hôte).
Clés de contexte. manifest_code (l’identifiant SPEC-MANIFEST-*) et reason (la description d’échec lisible par un humain). Celles-ci sont aussi atteignables via getManifestCode() et getReason(). Le message a la forme [<code>] <reason>.
Rétablissement. Branche sur manifest_code. Pour SPEC-MANIFEST-001 et SPEC-MANIFEST-003, corrige la charge utile du manifeste (corrige le type de champ ou fournis le champ manquant). Pour SPEC-MANIFEST-002, régénère le manifeste par rapport à une version majeure de schéma prise en charge ou mets à niveau le renderer. Pour SPEC-MANIFEST-004, fournis une entrée ou un moteur de modèles que l’édition actuelle peut résoudre.

Inspection

`InspectException`

Levée lorsque. L’inspection PDF échoue.
Classe. Étend directement RuntimeException (pas NextPdfException), donc elle ne porte pas de getContext().
Données portées. Deux propriétés readonly publiques : $inspectCode (un code lisible par machine dans l’espace de noms INSPECT-*) et $retryable (un booléen indiquant si l’appelant devrait réessayer — par exemple lorsqu’un sidecar d’inspection est temporairement hors service). La cause d’origine, lorsqu’elle est présente, est le throwable précédent chaîné.
Rétablissement. Branche sur $inspectCode pour la classe d’échec spécifique. Lorsque $retryable vaut true, réessaie avec un backoff car l’échec est attendu comme transitoire (tel qu’un redémarrage de sidecar) ; lorsqu’il vaut false, traite l’entrée ou la configuration comme le défaut et ne réessaie pas sans changement.

Ingénierie du chaos

`ChaosReportWriteException`

Levée lorsque. ChaosScenarioRunner::writeReport() ne peut pas persister sur disque le rapport agrégé de la journée de chaos. C’est un remplacement à type de domaine d’une erreur d’exécution générique, afin que les appelants puissent attraper l’échec spécifique d’écriture du rapport sur disque sans le confondre avec des erreurs levées au sein des simulateurs de scénario eux-mêmes (le runner les capture comme champs ChaosOutcome).
Classe. Étend NextPdfException et redéfinit getContext().
Clés de contexte. output_path (le chemin absolu que le runner a tenté d’écrire). Il est aussi atteignable via getOutputPath(). Le message a la forme ChaosScenarioRunner: failed to write report to "<path>".
Rétablissement. C’est un échec côté écriture du puits de rapport, pas des scénarios. Vérifie que le répertoire de sortie existe et est inscriptible et que l’espace disque est disponible, puis réexécute l’écriture du rapport. Les résultats du chaos eux-mêmes ne sont pas affectés.

`RetrievalUnavailableException`

Levée lorsque. Un point de terminaison de récupération (par exemple un service Voyage Retrieval Augmented Generation) est indisponible et le système soit retombe en mode cache uniquement, soit échoue en mode fermé.
Classe. Étend NextPdfException et redéfinit getContext().
Clés de contexte. mode (le mode de fonctionnement après l’échec — CACHED_ONLY lorsque les résultats sont servis depuis le seul cache sémantique, ou FAIL_CLOSED lorsque la requête est refusée entièrement sans donnée périmée) et endpoint (le point de terminaison devenu inaccessible). Celles-ci sont aussi atteignables via getMode() et getEndpoint(). Le message a la forme Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
Rétablissement. Lis mode pour savoir comment le système s’est dégradé. Sous CACHED_ONLY, les résultats peuvent être périmés ; rafraîchis une fois que le point de terminaison se rétablit. Sous FAIL_CLOSED, la requête a été refusée par conception et doit être réessayée une fois que le point de terminaison est accessible. Restaure la connectivité du point de terminaison (réseau, identifiants, santé du service) avant de dépendre d’une récupération fraîche.

Erreurs d'exécution et de support

Portée

Politique de dégradation

DegradedException

Transport HTTP

CurlNetworkException

CurlRequestException

TransientHttpException

Résilience

CircuitBreakerOpenException