Exécuter des diagnostics d'environnement sur NextPDF Connect

En bref

Assure-toi qu’un serveur NextPDF Connect est sain et qu’il dispose des capacités dont ton flux a besoin avant de lancer un traitement réel. C’est la première étape recommandée dans tout pipeline agentique. Les outils, revérifiés à partir du registre d’outils du serveur, sont diagnostic.doctor, diagnostic.capabilities et diagnostic.verify. Le registre les expose sous des noms de protocole avec points, et un outil connexe diagnostic.inspect existe également. Tous relèvent de l’édition Core.

Installation

composer require nextpdf/server

Configure un transport. veraPDF n’est requis que pour l’étape facultative de vérification de conformité. La vérification structurelle ne nécessite aucun outil externe.

Vue d’ensemble conceptuelle

diagnostic.doctor renvoie un rapport de santé de référence : version de PHP, extensions chargées, version du serveur, édition active et éventuels avertissements. Utilise status comme point de contrôle. Continue si la valeur est ok, lis les warnings si elle vaut warning, et arrête-toi si elle vaut error.
diagnostic.capabilities répertorie les capacités enregistrées avec leur édition et leur statut d’exécution (available, unavailable, degraded). Le nombre de capacités dépend de l’exécution et de l’édition ; ne code donc pas un total en dur. Vérifie une à une chaque capacité dont dépend ton flux.
diagnostic.verify contrôle l’intégrité structurelle : l’en-tête PDF, le marqueur EOF et la table de références croisées. La cible est la structure du document atteinte via l’arbre des pages (ISO 32000-2 §7.5). Avec compliance_flavour, il invoque également veraPDF.

Un résultat de diagnostic est une réponse normale dans chaque transport (PSR-18 §p2).

Surface d’API

Outil	Rôle	Niveau de risque
`diagnostic.doctor`	Rapport de santé de l’environnement	Sûr
`diagnostic.capabilities`	Inventaire des capacités avec leur statut	Sûr
`diagnostic.verify`	Vérification structurelle / de conformité	Sûr
`create_pdf`, `add_text`, `output_pdf`	Tester rapidement un document	comme documenté ailleurs

Ces noms sont les noms de protocole du registre. Le catalogue d’outils fait référence. Les outils et capacités disponibles dépendent de l’édition installée ; n’affirme donc jamais un nombre fixe d’outils ou de capacités.

Exemple de code — Démarrage rapide

diagnostic.doctor (sans argument) → lis status.
diagnostic.capabilities (sans argument) → confirme que chaque capacité requise est available.
create_pdf puis add_text → un document de test minimal.
diagnostic.verify avec le document_id → contrôles structurels.
Éventuellement diagnostic.verify avec compliance_flavour: "4" → veraPDF.
output_pdf (base64) → détruis la session de test.

Exemple de code — Production

Conditionne l’exécution du pipeline à diagnostic.doctorstatus. Associe chaque dépendance du flux à un id de capacité précis, puis vérifie l’état available avant d’exécuter les étapes dépendantes. Considère degraded comme un risque de qualité qui justifie un contrôle ponctuel. Exécute toujours le diagnostic.verify structurel. N’exécute la variante de conformité que lorsque la conformité est pertinente, et accepte qu’un veraPDF absent renvoie un résultat « introuvable » clair plutôt qu’un défaut du serveur.

Cas limites & pièges

veraPDF absent. L’appel de conformité renvoie un résultat « introuvable » explicite. Les contrôles structurels fonctionnent toujours. Si tu as besoin de la vérification de conformité, installe veraPDF et place-le dans le PATH du processus serveur.
Délai d’attente de veraPDF dépassé. Les documents volumineux peuvent déclencher le délai d’attente de la vérification. Réduis la taille du document, ou augmente le délai d’attente dans la configuration du serveur.
Capacité degraded. Une dépendance n’est que partiellement disponible ; la qualité du rendu peut donc baisser. Consulte les journaux du serveur pour connaître le mécanisme de repli utilisé.
error du doctor. Une exigence critique n’est pas satisfaite. Ne continue pas.

Performances

La vérification structurelle est rapide. La vérification de conformité lance veraPDF et reste bornée par le délai d’attente de la vérification. Le budget large reflète ce sous-processus.

Notes de sécurité

La sortie de diagnostic révèle des détails sur l’environnement : la version de PHP, les extensions et l’édition. Considère-la comme réservée aux opérateurs, et ne l’expose pas à des appelants non fiables.

Conformité

Énoncé	Spécification	Clause	reference_id
Un résultat de diagnostic est une réponse de transport normale.	PSR-18	§p2
L’intégrité structurelle cible la structure ancrée à l’arbre des pages.	ISO 32000-2	§7.5

La variante de conformité exécute veraPDF et rapporte son verdict. NextPDF n’affirme pas lui-même la conformité. C’est le validateur qui décide.

Contexte commercial

Sans objet : tous les outils de diagnostic relèvent de l’édition Core.

Disponibilité par transport

Transport	Disponible	Notes
MCP (stdio)	Oui	Les résultats de diagnostic sont des résultats d’outils.
REST	Oui	Les points de terminaison de santé correspondent à ces outils.
gRPC	Oui	Unaire ; le résultat porte les mêmes champs de statut.

Niveau de risque HITL

Les trois outils de diagnostic sont de niveau Sûr : en lecture seule, sans effet de bord. Ils ne déclenchent jamais le point de confirmation. L’output_pdf du test rapide est en mode base64 (Review, sans point de confirmation).

Enveloppe JSON du point de confirmation

Les diagnostics ne déclenchent jamais de point de confirmation.

{ "allowed": true }