NextPDF Connect : démarrage et découverte

En bref

Chaque transport dispose de son propre point d’entrée et de sa propre séquence de démarrage. Les transports partagent le registre, la configuration et le gate comme concepts. Ils s’exécutent dans des processus indépendants : démarrer l’un ne démarre donc pas les autres.

Installation

composer require nextpdf/server

Vue d’ensemble conceptuelle

Séquence de démarrage MCP

McpServer::create() câble le serveur MCP selon un ordre fixe. Il charge d’abord la configuration, construit la politique de sécurité à partir de cette configuration, construit le registre d’outils et lance la découverte des niveaux. Ensuite, il construit le magasin de documents en mémoire à partir du TTL et de la capacité configurés, crée le transport stdio et assemble le gestionnaire de protocole JSON-RPC avec le gate de confirmation et le journal d’audit. Une fois ces éléments en place, le serveur entre dans sa boucle lecture-traitement-écriture et s’exécute jusqu’à ce que l’entrée standard atteigne la fin de fichier.

Séquence de démarrage REST

HttpServer::create() lit HttpConfig depuis l’environnement et applique les surcharges CLI. Il résout ensuite le magasin de clés d’API dans cet ordre de préférence : d’abord le magasin de fichiers à rechargement à chaud, puis le fichier statique, puis l’environnement. Il résout ensuite les magasins de limitation de débit et d’idempotence, qui utilisent Redis quand Redis est configuré et accessible, et se rabattent sinon sur un stockage en mémoire. À partir de là, il ouvre le magasin de tâches SQLite partagé, construit les services applicatifs et la table de routage. Comme la table de routage est construite à partir des niveaux détectés, elle reflète les packages installés. RoadRunner pilote ensuite la boucle de requêtes des workers.

Séquence de démarrage gRPC

GrpcServer::create() résout le même magasin de clés, construit les mêmes services applicatifs et enregistre le service nextpdf.connect.v1 auprès du worker gRPC Spiral. Quand la dépendance moteur n’est pas disponible, le serveur gRPC démarre tout de même et répond aux requêtes de santé et de capacités. Dans cet état, le processus ne refuse pas de démarrer ; à la place, les RPC porteuses de données échouent proprement.

Découverte des outils

La découverte correspond à l’étape d’enregistrement par défaut du registre. Le niveau Core s’enregistre en premier. Les fournisseurs Pro et Enterprise s’enregistrent ensuite, si leurs classes se résolvent via class_exists(). Les fournisseurs AST et de mutation fournis s’enregistrent ensuite sous le niveau Pro, sous réserve de leurs gates d’environnement. Chaque enregistrement est filtré par la liste d’autorisation de sécurité enabled_tools, et les totaux par niveau qui en résultent sont rapportés dans la réponse MCP initialize. Voir /connect/tool-catalog/.

Découverte des transports

Il n’existe pas de réglage de configuration unique qui « active les transports ». Chaque transport est un point d’entrée distinct. REST et gRPC disposent chacun d’un profil RoadRunner distinct. Un déploiement choisit ses transports via le profil qu’il exécute : .rr.yaml pour REST, .rr.grpc.yaml pour gRPC, ou .rr.full.yaml pour les deux. Les transports s’exécutent dans des processus indépendants. Un client MCP manquant ne bloque jamais le serveur REST, et un client REST manquant ne bloque jamais MCP. Voir /connect/deployment/.

Ordre de résolution de la configuration

Le serveur MCP résout la configuration dans cet ordre de priorité : l’environnement (NEXTPDF_MCP_*) prime sur la section nextpdf_mcp du fichier YAML, qui prime elle-même sur les valeurs par défaut intégrées. Les serveurs REST et gRPC lisent HttpConfig depuis les variables d’environnement NEXTPDF_* avec des valeurs par défaut sûres. Ils ne lisent pas le fichier YAML MCP. Voir /connect/configuration/.

Liaisons du conteneur

Il n’y a aucun conteneur d’injection de dépendances ni service provider à enregistrer. Chaque fabrique create() construit explicitement et de façon déterministe son propre graphe d’objets. Deux points d’injection existent — le transport et la fabrique de workers — et tous deux servent aux tests, pas au câblage applicatif.

Exemple de code — Démarrage rapide

Inspecte ce que la découverte a produit, sans servir de trafic :

./vendor/bin/generate-skills --dry-run --list-tools

Exemple de code — Production

Démarre les transports combinés sous un superviseur unique :

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Cas limites et pièges

• Un niveau manquant ne fait pas échouer le démarrage. La découverte des niveaux ignore silencieusement l’absence d’un package Pro ou Enterprise. Le serveur démarre avec le catalogue Core.

• Une surcharge qui affaiblit le niveau de risque fait échouer le démarrage. Une entrée risk_level_overrides qui affaiblit un outil approval_required lève une erreur au chargement de la configuration ; le serveur refuse de démarrer. C’est intentionnel.

• Une panne de Redis entraîne une dégradation, pas un plantage. Si Redis est configuré mais inaccessible au démarrage, le serveur REST se rabat sur des magasins en mémoire. Vérifie la santé de Redis plutôt que de supposer que Redis est utilisé.

Performances

Le coût du démarrage correspond à l’analyse de la configuration, à l’analyse du registre et à la détection des niveaux. La page performance_budget borne ce coût. Il est payé une fois par démarrage de processus, pas par requête.

Notes de sécurité

La politique de sécurité est construite avant le registre ; la liste d’autorisation enabled_tools contraint donc la découverte dès le premier enregistrement. Les clés d’API ne sont jamais lues depuis le fichier YAML MCP ; les transports réseau résolvent les clés depuis un fichier de secret ou l’environnement. Voir /connect/security-and-operations/.

Conformité

Cette page décrit la mécanique du démarrage. Les citations de protocole et de sécurité sont épinglées sur /transports/mcp/, /transports/rest/, /transports/grpc/ et /connect/security-and-operations/.

Contexte commercial

La détection des niveaux au démarrage est le seul point où nextpdf/premium apporte ses outils Pro et Enterprise au catalogue, lorsque nextpdf/premium est installé aux côtés du serveur.

Voir aussi

• /connect/tool-catalog/ — ce que la découverte enregistre et pourquoi le nombre varie
• /connect/configuration/ — l’ordre de résolution en détail
• /connect/deployment/ — choisir les transports via les profils RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — détail par transport