📘 goblin-repositor

Aperçu

Le module goblin-repositor est un gestionnaire de dépôts Debian pour l'écosystème Xcraft. Il permet de créer, initialiser et administrer des dépôts APT personnalisés (basés sur reprepro), de signer les paquets avec des clés GPG générées automatiquement, et d'exposer ces dépôts via un serveur HTTP intégré. Il facilite ainsi la distribution contrôlée de paquets .deb produits par la chaîne de build Xcraft (via xcraft-contrib-pacman).

Sommaire

• Structure du module
• Fonctionnement global
• Exemples d'utilisation
• Interactions avec d'autres modules
• Configuration avancée
• Détails des sources
• Licence

Structure du module

Le module s'articule autour de trois composants principaux :

• lib/service.js — Un acteur Goblin singleton (repositor) qui expose les quêtes de gestion des dépôts : bootstrap des dépendances système, initialisation d'un dépôt, publication et suppression de paquets .deb.
• lib/debHttp.js — La classe DebHttp, un serveur HTTP basé sur Express qui expose les dépôts Debian générés sous forme de fichiers statiques, avec une surveillance dynamique des nouveaux dépôts via Chokidar.
• lib/index.js — Point d'entrée qui instancie (si activé) le serveur DebHttp et fournit la fonction de nettoyage (dispose) appelée à l'arrêt de l'application.
• repositor.js — Fichier racine qui expose les commandes du module (xcraftCommands) sur le bus Xcraft, en délégant à lib/service.js.

Fonctionnement global

Le cycle de vie d'un dépôt Debian géré par ce module suit trois étapes :

1. Bootstrap (bootstrap) : installe les paquets système nécessaires (gnupg, reprepro) via xcraft-contrib-pacman, en enchaînant les commandes pacman.make, pacman.build et pacman.install.
2. Initialisation (initialize) : crée l'arborescence reprepro du dépôt pour une distribution donnée, génère (si besoin) une paire de clés GPG dédiée à la signature des paquets, et écrit le fichier de configuration conf/distributions.
3. Publication (publishDeb / publishPackage) : ajoute un ou plusieurs fichiers .deb au dépôt via reprepro includedeb. À l'inverse, removePackage retire un paquet du dépôt via reprepro remove.

Une fois qu'au moins un dépôt existe, le fichier lib/index.js peut démarrer un serveur HTTP (DebHttp) qui :

• surveille (via Chokidar) les répertoires *root* sous var/ du xcraftRoot, correspondant aux racines de production/développement des distributions ;
• enregistre dynamiquement une route Express (/<distribution>) pointant vers le sous-répertoire var/deb de chaque racine détectée, dès qu'un nouveau dossier apparaît ;
• sert ces fichiers statiquement, permettant à un client apt d'accéder aux paquets via HTTP.

Ce démarrage du serveur HTTP est déclenché par le handler spécial _postload, appelé automatiquement après le chargement du module sur le bus Xcraft (mécanisme xcraft-core-server).

Exemples d'utilisation

repositor est un acteur Goblin (et non Elf, car défini via Goblin.configure / Goblin.createSingle) : son instanciation et ses quêtes s'invoquent donc via le système de quêtes Xcraft plutôt que par instanciation de classe.

Initialiser un nouveau dépôt

// Depuis une quête d'un autre acteur
yield this.quest.cmd('repositor.initialize', {
  distribution: 'myDistribution',
  $suite: 'stable',
});

Publier un paquet spécifique

yield this.quest.cmd('repositor.publishDeb', {
  distribution: 'myDistribution',
  packageDeb: '/path/to/package.deb',
});

Publier tous les paquets d'une distribution source

yield this.quest.cmd('repositor.publishPackage', {
  distribution: 'myDistribution',
  packageDistrib: 'sourceDistribution',
});

Retirer un paquet du dépôt

yield this.quest.cmd('repositor.removePackage', {
  distribution: 'myDistribution',
  packageName: 'my-package',
});

Ajouter le dépôt sur un système Debian

Une fois le dépôt initialisé et des paquets publiés, il peut être déclaré dans un fichier sources.list d'un système Debian.

Accès direct au dépôt local (sans passer par HTTP) :

deb [signed-by=/xcraft/var/prodroot.<distribution>/linux-amd64/var/deb/public.gpg.key] file:/xcraft/var/prodroot.<distribution>/linux-amd64/var/deb/ <codename> non-free

Accès via le serveur HTTP intégré (DebHttp) :

deb [signed-by=/path/to/public.gpg.key] http://<hostname>:<port>/<distribution>/ <codename> non-free

Dans les deux cas, <codename> correspond au nom de code de la distribution (VERSION_CODENAME, ex. bullseye), et public.gpg.key est la clé publique générée par _generateKey lors de l'initialisation du dépôt, à copier localement pour que apt puisse vérifier la signature.

Interactions avec d'autres modules

• xcraft-core-goblin — Fournit l'infrastructure d'acteur Goblin (Goblin.configure, Goblin.registerQuest, Goblin.createSingle).
• xcraft-core-etc — Charge la configuration du module (goblin-repositor) ainsi que la configuration globale xcraft (pour xcraftRoot).
• xcraft-contrib-pacman — Fournit l'accès aux racines de production/build des distributions (getTargetRoot) et pilote l'installation des dépendances système (pacman.make, pacman.build, pacman.install).
• xcraft-core-env — Gère le basculement du devroot courant (devrootUpdate) le temps des opérations sur un dépôt.
• xcraft-core-platform — Détermine l'architecture cible de la chaîne de compilation (getToolchainArch).
• Le module utilise également xcraft-core-process pour piloter les commandes externes (gpg, gpgconf, reprepro), xcraft-core-log pour la journalisation du serveur HTTP, et xcraft-core-fs pour lister les fichiers .deb d'une distribution source.

Configuration avancée

Le module expose un fichier config.js exploité par xcraft-core-etc :

| Option | Description | Type | Valeur par défaut | | --------------- | ---------------------------------------------------------------------------------------------- | ------- | ----------------- | | http.enabled | Active le serveur HTTP pour les dépôts Debian | Boolean | true | | http.port | Port d'écoute du serveur HTTP des dépôts | Number | 23432 | | http.hostname | Nom d'hôte/adresse d'écoute du serveur HTTP | String | 0.0.0.0 | | osRelease | Nom de code de la distribution (stretch, buster, …) utilisé si /etc/os-release ne suffit pas | String | `` (vide) |

Variables d'environnement

| Variable | Description | Exemple | Valeur par défaut | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------- | | GNUPGHOME | Répertoire contenant le trousseau GPG utilisé pour signer les dépôts. Obligatoire lors de la génération d'une clé (initialize) : une erreur est levée si absente. | /home/user/.gnupg | - |

Détails des sources

repositor.js

Point d'entrée du module côté bus Xcraft. Expose exports.xcraftCommands, recherché dynamiquement par xcraft-core-server au démarrage, et qui délègue simplement au service défini dans lib/service.js.

lib/service.js

Définit l'acteur Goblin singleton repositor, sans état persistant (logicState et logicHandlers sont vides — l'acteur ne fait que déclencher des actions système, il ne maintient pas de modèle de données mutable).

Le fichier gère aussi la lecture de la release de l'OS (fonction interne getOsRelease), en lisant /etc/os-release et en le complétant éventuellement avec l'option osRelease de la configuration.

Un handler spécial _postload est attaché directement à module.exports.handlers : il est invoqué automatiquement après le chargement du module sur le bus et démarre le serveur HTTP (lib/index.js → debHttp().serve()) si celui-ci est activé dans la configuration.

Méthodes publiques

• bootstrap() — Installe les dépendances système requises (gnupg, reprepro) en enchaînant les commandes pacman.make, pacman.build puis pacman.install sur les paquets gnupg+gnupg et debian+reprepro.
• initialize(distribution, $suite='stable') — Crée l'arborescence reprepro du dépôt pour la distribution donnée si elle n'existe pas déjà, génère une clé GPG dédiée via _generateKey, puis écrit le fichier conf/distributions (suite, codename, architecture, clé de signature) et exécute reprepro export. En cas d'échec, le répertoire du dépôt nouvellement créé est supprimé.
• publishDeb(distribution, packageDeb) — Ajoute le fichier .deb indiqué au dépôt de la distribution via reprepro includedeb.
• publishPackage(distribution, packageDistrib) — Recherche tous les fichiers .deb produits pour la distribution source packageDistrib (sous opt/packages/deb) et les publie un par un dans le dépôt distribution via publishDeb.
• removePackage(distribution, packageName) — Retire le paquet packageName du dépôt de la distribution via reprepro remove.
• _generateKey(distribution, repoDir) (interne) — Génère (ou récupère si elle existe déjà) une paire de clés GPG dédiée à la distribution, exporte la clé publique dans repoDir/public.gpg.key, et retourne l'identifiant de la clé à utiliser pour la signature du dépôt. Nécessite que la variable d'environnement GNUPGHOME soit définie.

lib/debHttp.js

Définit la classe DebHttp, un serveur HTTP Express dédié à l'exposition des dépôts Debian existants.

• constructor(port=80, hostname='127.0.0.1') — Initialise l'application Express, calcule la racine var du xcraftRoot, puis met en place un watcher Chokidar sur les répertoires correspondant au motif *root* (racines de production/développement des distributions).
• _refreshRoute(dir) (interne) — Appelée à chaque nouveau répertoire détecté par le watcher ; en déduit le nom de distribution (devroot étant traité comme toolchain) et enregistre la route HTTP correspondante si elle ne l'est pas déjà.
• _addRoute(dirPath, webRoute) (interne) — Monte un middleware express.static sur la route donnée pour servir le contenu du répertoire var/deb de la distribution.
• serve() — Démarre effectivement le serveur HTTP sur le port et l'hôte configurés.
• dispose() — Ferme proprement le serveur HTTP et le watcher Chokidar ; utilisé lors de l'arrêt de l'application.

lib/index.js

Fait le lien entre la configuration du module et la classe DebHttp.

• debHttp() — Charge la configuration goblin-repositor ; si http.enabled est faux, ne fait rien (retourne null). Sinon, instancie DebHttp avec le port et l'hôte configurés et conserve une référence unique au serveur créé.
• dispose() — Appelle dispose() sur l'instance DebHttp si celle-ci a été créée, afin de libérer proprement le serveur HTTP et le watcher à l'arrêt de l'application.

Licence

Ce module est distribué sous licence MIT.

Ce contenu a été généré par IA