Lorsque l’on publie du code Go, l’habitude est d’en distribuer les sources directement depuis la forge qui l’héberge : github.com/org/projet, framagit.org/org/projet, …
C’est pratique, mais cela lie durablement le chemin d’import au prestataire choisi : le jour où l’on migre d’une forge à une autre, tous les utilisateurs doivent modifier leurs imports, tandis que chaque fork historique continue de pointer vers l’ancienne adresse.
Heureusement, le mécanisme go-import permet de dissocier le chemin d’import du lieu d’hébergement réel du code.
Il suffit pour cela d’exposer, sur le domaine de son choix, une page HTML contenant une balise <meta name="go-import"> décrivant où se trouvent les sources.
Cette technique est décrite depuis longtemps sur le blog de Julien Vehent, qui montre comment configurer HAProxy pour servir un fichier HTML statique renvoyant la balise adéquate pour un module unique. Cependant, dès que l’on gère une poignée de modules, voire une collection entière, maintenir un fichier par module devient vite fastidieux. Cette approche ne répond pas non plus à la gestion des versions majeures, introduite avec les modules Go.
Ma solution a consisté à tout faire porter par nginx, au moyen d’une seule location utilisant une expression rationnelle.
Voyons comment la mettre en place.
L’intérêt d’un chemin d’import personnalisé
Lorsqu’un utilisateur exécute go get git.happydns.org/happydomain, le client Go interroge d’abord l’URL https://git.happydns.org/happydomain?go-get=1 et y cherche une balise :
<meta name="go-import" content="git.happydns.org/happydomain git https://framagit.org/happyDomain/happydomain.git">
Cette balise indique à Go :
- le préfixe qui sert d’identifiant pour ce module ;
- le type de gestionnaire de versions (ici
git) ; - l’URL réelle où cloner le dépôt.
Tant que l’on contrôle le domaine git.happydns.org, peu importe où se trouve réellement le code source.
On peut passer de GitHub à GitLab, de GitLab à Codeberg, ou même héberger sa propre forge : les chemins d’import restent identiques.
Aucun utilisateur n’a besoin de modifier ses import ni son go.mod.
Ces plateformes pouvant changer leurs conditions d’utilisation unilatéralement, il vaut mieux en rester indépendant et ne pas accroître la puissance de plateformes centralisées. Il est donc important pour moi de garder la main sur l’identité des modules que je mets à disposition, sans avoir à gérer moi-même la forge qui les héberge.
Limitations de l’approche par fichiers HTML
L’article initial propose de servir, pour chaque module, un fichier HTML statique contenant la bonne balise. Cela fonctionne, mais présente deux inconvénients dès que l’on dépasse le module unique.
D’une part, chaque nouveau module ou renommage implique de créer ou mettre à jour un fichier supplémentaire sur le serveur web. Le projet happyDomain, qui sert d’exemple dans la suite, compte une trentaine de modules (le cœur, le SDK client, des bibliothèques de vérification, …) : autant de fichiers à synchroniser.
D’autre part, depuis l’arrivée des modules Go et de leur règle du semantic import versioning, tout module dont la version majeure dépasse 1 doit être importé avec un suffixe /v2, /v3, …
Le chemin git.happydns.org/happydomain/v2 doit alors continuer à résoudre correctement, en renvoyant la même balise go-import que le module de base.
Servir un fichier HTML par module et par version majeure devient vite ingérable.
Une location générique dans nginx
Plutôt que de multiplier les fichiers, on peut faire générer la réponse HTML directement par nginx, à partir d’une expression rationnelle qui capture à la fois le nom du module et son éventuel suffixe de version.
Voici la configuration en place sur git.happydns.org :
server {
# [...]
location / {
rewrite ^(.*)$ https://framagit.org/happyDomain$1;
}
location ~ ^/(golang-sdk|happydomain|happyDomain/happyDeliver|happydeliver|checker-sdk-go|checker-(caa|dav|delegation|dummy|email-autoconfig|kerberos|ldap|matrix|ns-restrictions|pgp|ping|smtp|ssh|sip|srv|stun-turn|tls|zonemaster))(/v[0-9])?$ {
default_type text/html;
return 200 '<!DOCTYPE html><html><head>
<meta name="go-import" content="git.happydns.org/$1$3 git https://framagit.org/happyDomain/$1.git">
<meta http-equiv="refresh" content="0; url=https://framagit.org/happyDomain/$1">
<link rel="me" href="https://floss.social/@happyDomain">
</head><body>Nothing to see here; <a href="https://framagit.org/happyDomain/$1">move
along</a>.</body></html>';
}
}
Décortiquons-la.
Aiguillage des requêtes
La première instruction location renvoie toute requête qui ne correspond à rien d’autre vers l’URL équivalente sur Framagit.
Autrement dit, git.happydns.org/happydomain/-/issues/42 renvoie l’utilisateur directement vers le bon ticket de la forge.
On conserve ainsi la cohérence entre l’adresse canonique et l’interface de la forge sous-jacente, sans avoir à dupliquer quoi que ce soit.
La dernière location, enfin, est celle qui nous intéresse : elle déclenche la génération de la réponse HTML pour les chemins d’import reconnus.
L’expression rationnelle
Le motif ^/(golang-sdk|happydomain|happyDomain/happyDeliver|...)(/v[0-9])?$ reconnaît l’ensemble des modules distribués.
L’énumération explicite est volontaire : elle sert de liste blanche et évite que n’importe quel chemin inconnu déclenche la génération d’une balise go-import qui pointerait vers un dépôt inexistant.
Deux groupes de capture sont définis :
$1correspond au nom du module ;$3correspond au suffixe de version (/v2,/v3, …) lorsqu’il est présent, ou à une chaîne vide sinon. Le groupe$2est implicitement utilisé par les alternatives internes du second sous-motifchecker-(...).
On construit ensuite, dans la directive return 200, une page HTML dont les éléments varient en fonction des captures.
La réponse générée
La page renvoyée contient trois éléments utiles.
La balise go-import déclare au client Go où aller chercher les sources :
<meta name="go-import" content="git.happydns.org/$1$3 git https://framagit.org/happyDomain/$1.git">
Notez que le chemin annoncé inclut le suffixe de version ($3) lorsqu’il existe, de sorte que git.happydns.org/happydomain/v2 renvoie bien git.happydns.org/happydomain/v2 comme identifiant de module.
L’URL du dépôt, elle, ne le comporte pas : Go se chargera de résoudre la bonne branche ou le bon tag à partir du contenu du dépôt.
Une directive meta refresh redirige les navigateurs humains vers la page du projet sur Framagit.
Ainsi, lorsqu’un développeur colle dans son navigateur un chemin d’import qu’il a vu dans un go.mod, il arrive directement sur la page du dépôt, sans se retrouver face à une page blanche.
Enfin, un lien rel="me" associe le domaine au compte Mastodon du projet, pour la vérification d’identité sur le fediverse.
Tester le résultat
On peut vérifier le bon fonctionnement de la configuration avec curl, en passant le paramètre ?go-get=1 que Go ajoute systématiquement :
42sh$ curl -s 'https://git.happydns.org/happydomain?go-get=1'
<!DOCTYPE html><html><head>
<meta name="go-import" content="git.happydns.org/happydomain git https://framagit.org/happyDomain/happydomain.git">
[...]
42sh$ curl -s 'https://git.happydns.org/happydomain/v2?go-get=1'
<!DOCTYPE html><html><head>
<meta name="go-import" content="git.happydns.org/happydomain/v2 git https://framagit.org/happyDomain/happydomain.git">
[...]
Pour s’assurer que le client Go accepte bien la réponse, l’option -x de go get (ou la variable GOFLAGS="-x") affiche en détail toutes les requêtes effectuées lors de la résolution.
Pourquoi ne pas utiliser un motif générique ?
Il serait tentant de remplacer l’énumération explicite par un motif générique du type ^/([a-z0-9-]+)(/v[0-9])?$.
Mieux vaut l’éviter : une faute de frappe dans un import produirait une réponse 200 OK avec une balise go-import pointant vers un dépôt inexistant, et le message d’erreur renvoyé à l’utilisateur serait moins explicite qu’un honnête 404.
Attention à l'injection HTML
Soyez vigilant sur la rigueur de votre expression rationnelle : le contenu capturé est injecté tel quel dans le corps de la réponse HTML, sans aucun échappement de la part de nginx.
Un motif trop permissif comme ^/(.+)(/v[0-9])?$ ouvrirait la porte à des injections HTML, voire à du cross-site scripting (XSS), en glissant du code dans l’URL.
Restreignez les caractères acceptés au strict nécessaire ([a-zA-Z0-9_/-] au plus) et préférez une liste blanche lorsque c’est possible.
Ajouter un nouveau module
Lorsqu’on ajoute un module au projet, la procédure se résume à deux étapes :
- insérer le nom du module dans l’expression rationnelle de la configuration
nginx; - recharger la configuration avec
nginx -s reload.
Le module devient immédiatement importable sous git.happydns.org/nouveau-module.
Sa version majeure /v2 fonctionne sans rien ajouter d’autre.
Conclusion
Cette configuration est en production depuis plusieurs années sur git.happydns.org, sans que j’aie eu à m’en soucier.
Le jour où il faudra quitter Framagit pour une autre forge, il suffira de modifier l’adresse de la forge dans la configuration nginx : tous les utilisateurs actuels et passés de ces modules continueront d’accéder au code, sans modifier la moindre ligne chez eux.