Aller au contenu

04. Spécification des Dépôts et Distribution Légère (Buckets)

Navigation : Documentation > 04. Dépôts et Distribution Légère

Sommaire

  1. Architecture de Distribution Client / Serveur
  2. Spécification des Composants de Distribution
  3. Index Centralisé (index.nuon)
  4. Téléchargement des Manifestes à la Demande (Sparse Fetch)
  5. Immunité contre le Rate-Limiting des Plateformes (Anti-403)
  6. Organisation des Dépôts et Gouvernance de Sécurité
  7. 4.1 Segmentation Macro des Buckets
  8. 4.2 Partitionnement par Sharding Alphabétique
  9. 4.3 Templates d'Issues et Planification Horaire
  10. Déploiement en Réseaux Complètement Isolés (Air-Gapped) et Miroirs Privés
  11. Réécriture Dynamique d'URLs
  12. Préservation de l'Intégrité Cryptographique

1. Architecture de Distribution Client / Serveur

erable repose sur une architecture de distribution découplée : Index Centralisé Compilé + Téléchargement des Manifestes à la Demande.
Le client ne télécharge aucun historique Git local sur la machine utilisateur.

flowchart LR
    subgraph RemoteBucket ["1. Dépôt Distant (Bucket Git)"]
        CI["GitHub Action (Compilation sur push)"]
        IDX["index.nuon.sig (~500 Ko)"]
        PKGS["packages/r/ripgrep/parts/*.toml"]
        CI -->|Compile & Signe| IDX
    end

    subgraph ClientHost ["2. Poste Client (~/.erable)"]
        CACHE["indices/core.nuon (Cache TTL 24h)"]
        INST["installed/ripgrep/parts/*.toml"]
        BINS["packages/ripgrep/14.1.0/"]
    end

    IDX -->|"1. erable update (HTTP CDN direct, < 1 sec)"| CACHE
    CACHE -->|"2. erable search (Lecture directe en RAM O(1))"| ClientHost
    PKGS -->|"3. erable install (Téléchargement à la demande)"| INST
    INST -->|"4. Déploiement des binaires"| BINS

2. Spécification des Composants de Distribution

2.1 Index Centralisé (index.nuon)

  • Chaque bucket publie à sa racine un fichier d'index compilé automatiquement par intégration continue (index.nuon), accompagné de sa signature cryptographique Ed25519 (index.nuon.sig).
  • Protection anti-rejeu et anti-gel (Spécification TUF) : L'en-tête de index.nuon contient un compteur strictement croissant (sequence_id) et une date d'expiration signée (valid_until, max 7 jours). Tout index expiré ou dont le sequence_id est inférieur à l'index local est rejeté par le moteur client.
  • Il contient le résumé structuré de l'ensemble des paquets du bucket : nom, version courante, description, tags, licence, catégories et architectures cibles supportées.
  • Taille : Moins de 600 Ko pour un dépôt de 5 000 paquets.
  • Mise en cache locale : Le client conserve cet index avec un TTL de 24 heures par défaut. La recherche s'exécute en mémoire vive en quelques millisecondes.

2.2 Téléchargement des Manifestes à la Demande (Sparse Fetch)

  • Le client erable ne télécharge jamais l'arborescence complète du dépôt.
  • Lors de l'installation d'un outil (erable install <pkg>), le moteur télécharge uniquement les fichiers modulaires du paquet (parts/*.toml et scripts .nu) depuis l'endpoint CDN Raw statique.
  • Le manifeste actif est enregistré localement dans ~/.erable/installed/<pkg>/.

3. Immunité contre le Rate-Limiting des Plateformes (Anti-403)

  1. Client Utilisateur (Zéro Appel REST GitHub) :
  2. Le client n'interroge jamais les endpoints REST api.github.com.
  3. Toutes les requêtes transitent par les CDN de fichiers bruts statiques (raw.githubusercontent.com ou miroir CDN Cloudflare/Fastly), éliminant toute restriction de quota (60 req/h).
  4. Bot d'Autoupdate CI :
  5. Le bot s'exécute avec le jeton officiel GITHUB_TOKEN (5 000 req/h).
  6. La surveillance des nouvelles versions amont s'effectue prioritairement via les flux RSS/Atom de releases (https://github.com/{owner}/{repo}/releases.atom), qui ne consomment aucun quota d'API REST.

4. Organisation des Dépôts et Gouvernance de Sécurité

4.1 Segmentation Macro des Buckets

Bucket Vocation Niveau d'Audit Critères de Publication & Sécurité
main Utilitaires CLI / TUI majeurs et essentiels 100% Automatisée (CI stricte, zéro humain requis) Binaire stable, multiplateforme, $\ge 500$ étoiles GitHub/GitLab, tests de validation obligatoires (check_version, check_help), linter AST, provenance SLSA Level 3 / Sigstore.
gui Applications fenêtrées graphiques Élevée (CI + tests raccourcis) Déclaration de parts/shortcuts.toml, sous-système Windows GUI.
community Outils émergents ou de niche Automatisée (CI stricte) Audit obligatoire par le linter AST anti-exfiltration, SHA-256 certifiés.
commercial Logiciels propriétaires ou sous licence commerciale Légale & Stricte Téléchargement direct chez l'éditeur, consentement obligatoire --accept-license.

4.2 Partitionnement par Sharding Alphabétique

Pour optimiser les accès et éviter l'engorgement des systèmes de fichiers, l'arborescence des paquets est partitionnée par initiale :

bucket-main/
├── index.nuon                      # Index compilé
├── index.nuon.sig                  # Signature Ed25519
├── README.md
└── packages/
    ├── a/
    │   └── aria2/
    ├── b/
    │   └── bat/
    ├── r/
    │   └── ripgrep/
    │       ├── manifest.toml
    │       ├── pre_install.nu
    │       ├── post_install.nu
    │       ├── pre_uninstall.nu
    │       ├── post_uninstall.nu
    │       └── parts/
    │           ├── package.toml
    │           ├── targets.toml
    │           └── verification.toml

    └── z/
        └── zoxide/

4.3 Templates d'Issues et Planification Horaire

Chaque bucket officiel (main, gui, community, commercial, fonts) expose trois templates dans .gitlab/issue_templates/ traités par les pipelines centralisés du dépôt core selon une chaîne horaire ordonnée :

  1. package_add.md (package-add) : ajout d'un paquet inexistant — détecté en amont à :00 (hourly_00, --action-filter create) et traité à :15 (hourly_15).
  2. package_update.md (package-update) : mise à jour de version d'un paquet existant — détectée à :15 (hourly_15) et traitée à :30 (hourly_30).
  3. platform_add.md (platform-add) : extension multiplateforme d'un paquet existant — détectée à :30 (hourly_30, --action-filter enrich_targets) et fusionnée dans targets.toml à :45 (hourly_45).

5. Déploiement en Réseaux Complètement Isolés (Air-Gapped) et Miroirs Privés

Dans les infrastructures critiques sans connectivité Internet directe, les requêtes vers les CDN publics et GitHub Releases sont inaccessibles.

5.1 Réécriture Dynamique d'URLs

Le fichier de configuration global ~/.erable/config.nu permet de définir des règles de réécriture transparentes vers un gestionnaire d'artefacts d'entreprise (JFrog Artifactory, Sonatype Nexus ou bucket S3 interne) : 

$env.erable_MIRROR_REWRITE = {
    enabled: true,
    prefix_match: "https://github.com/",
    replace_with: "https://artifactory.corp.internal/artifactory/github-cache/"
}

5.2 Préservation de l'Intégrité Cryptographique

Le module lib/network.nu intercepte et réécrit les URLs de téléchargement à la volée. L'intégrité reste garantie par le calcul de l'empreinte SHA-256 et la validation de provenance SLSA 3 / Sigstore sur l'artefact obtenu depuis le miroir.