Démarrage et découverte de Gotenberg avec NextPDF

En bref

Le pont n’a aucun mécanisme de découverte automatique propre. C’est un simple service que tu construis par injection explicite dans le constructeur : un objet-valeur de configuration ainsi que des collaborateurs HTTP PSR. Ce paquet ne fournit aucun service provider, aucun bundle ni aucune extension de conteneur, et ne lit lui-même aucune variable d’environnement. Ici, la « découverte » désigne la façon dont un framework hôte fournit les collaborateurs ; c’est le rôle du framework, pas celui de ce paquet.

Comment le pont est découvert

Il n’est pas découvert automatiquement. C’est toi qui le construis. GotenbergBridge exige quatre arguments et en accepte trois optionnels :

• Obligatoire : un GotenbergConfig, un client PSR-18, une fabrique de requêtes PSR-17, une fabrique de flux PSR-17.
• Optionnel : un journaliseur PSR-3, une politique de sécurité HTML (par défaut, celle du cœur NextPDF) et une fabrique de réponses PSR-17.

La fabrique de réponses sert d’interrupteur d’activation pour le transport épinglé sur cURL. Fournis-la et, lorsqu’il y a quelque chose à épingler (adresses résolues ou empreintes SPKI configurées), le pont utilise le transport à épinglage. Omets-la, et le client PSR-18 injecté reste utilisé. Le contrat complet des arguments se trouve dans /integrations/gotenberg/configuration/.

Séquence de démarrage

Il n’y a aucune étape d’enregistrement. Le cycle de vie est le suivant :

1. L’hôte résout un client PSR-18 et des fabriques PSR-17. C’est le conteneur hôte qui s’en charge ; le paquet ne le fait pas.
2. L’application construit un GotenbergConfig à partir de sa source de configuration. GotenbergConfig::fromArray() accepte un tableau en snake_case et tolère les valeurs malformées en leur substituant les valeurs par défaut. Valide la source dans ton chemin de démarrage, afin qu’une URL manquante fasse échouer le démarrage, et non chaque conversion.
3. L’application construit GotenbergBridge avec la configuration et les collaborateurs.
4. Le premier appel de conversion exécute la validation de l’URL, le filtrage SSRF et le contrôle du nom de fichier, ainsi que la requête. Aucun traitement n’a lieu au moment de la construction ; le pont reste inerte tant que tu ne l’appelles pas.

Liaisons de conteneur

Ce paquet ne fournit aucune liaison de conteneur. Pour rendre le pont injectable, enregistre-le dans le conteneur de ton application hôte comme suit :

• Lie GotenbergConfig à partir de ta source de configuration.
• Lie le client PSR-18 et les fabriques PSR-17 aux implémentations que tu as choisies.
• Lie GotenbergBridge en tant que service qui reçoit ce qui précède.

Le câblage automatique natif du framework, la publication de la configuration et l’enregistrement du service provider ou du bundle se trouvent dans les paquets d’intégration dédiés au framework, et non ici. Ce paquet reste volontairement agnostique vis-à-vis du framework. Comme il ne dépend que des interfaces PSR, il fonctionne avec n’importe quel conteneur.

Ordre de résolution de la configuration

Le paquet ne lit de lui-même aucune configuration. L’ordre de résolution est celui que ton application met en œuvre avant d’appeler GotenbergConfig::fromArray() ou le constructeur. Un ordre courant consiste à lire d’abord les variables d’environnement, puis un fichier de configuration publié, puis les valeurs par défaut du code. Cet ordre relève du contrat de ton application, pas de celui de ce paquet. En revanche, ce que le paquet définit, c’est la valeur par défaut de chaque champ omis par le tableau transmis à fromArray() : URL d’API vide, délai d’expiration de 30 secondes, plafond de taille de 50 Mio, clé d’API vide, listes d’empreintes vides.

Diagnostics

Deux signaux intégrés confirment le câblage :

• isAvailable() valide l’URL sans aucun trafic réseau, puis envoie une requête HEAD vers <apiUrl>/health et signale la disponibilité lorsque le statut est inférieur à 500. Elle renvoie false au lieu de lever une exception en cas d’échec, quel qu’il soit. Appelle-la depuis un contrôle de disponibilité.
• Une conversion de validation d’un petit document réputé valide confirme l’intégralité du chemin de bout en bout. Cela comprend la requête multipart vers <apiUrl>/forms/libreoffice/convert et la validation de la réponse.

Voir aussi

• /integrations/gotenberg/integration/ — piloter un pipeline NextPDF au moyen du service.
• /integrations/gotenberg/install/ — installation du paquet et du service.
• /integrations/gotenberg/configuration/ — le contrat complet du constructeur et de la configuration.
• /integrations/gotenberg/overview/ — le flux de conversion et le modèle de dépendances.