clonepack/README.md

# ClonePack

ClonePack est un système de clonage et de gel d'artefacts. Il permet de synchroniser des dépôts externes, de les figer à un instant donné, et de les exposer localement via un miroir HTTP.

## Types d'artefacts supportés

- Enterprise Linux (RPM/YUM/DNF)
- Debian/Ubuntu (APT)
- Docker images — *à venir*
- Binaires — *à venir*

## Fonctionnalités

- Clonage de dépôts RPM et APT avec vérification SHA256
- Scan régulier des sources pour détecter les nouveaux paquets
- Validation manuelle ou automatique des mises à jour
- Blocklist permanente par paquet (toutes versions)
- Snapshots avec diff et rollback (RPM + APT)
- Proxy miroir HTTP accessible par ID ou par nom de dépôt
- Logging structuré configurable (niveaux + format JSON)
- Accès API restreint à localhost (extensible vers RBAC token)

---

## Compilation

**Prérequis** : Go 1.25+

```bash
make build        # compile → bin/clonepack
make run          # compile + démarre le serveur
make test         # lance les tests
make vet          # analyse statique
make clean        # supprime bin/
```

Le binaire est généré dans `bin/clonepack`.

---

## Configuration

ClonePack se configure via fichier YAML ou variables d'environnement (préfixe `CLONEPACK_`).

**Fichier de config (optionnel) :**
```yaml
server:
  host: 0.0.0.0
  port: 8080

db:
  path: ./clonepack.db

data_dir: ./data

sync:
  interval: 1h

log:
  level: info    # debug | info | warn | error
  format: text   # text | json
```

**Variables d'environnement :**
```bash
CLONEPACK_SERVER_PORT=9090
CLONEPACK_DB_PATH=/var/lib/clonepack/clonepack.db
CLONEPACK_DATA_DIR=/var/lib/clonepack/data
CLONEPACK_SYNC_INTERVAL=30m
CLONEPACK_LOG_LEVEL=debug
CLONEPACK_LOG_FORMAT=json
```

**Démarrer le serveur :**
```bash
./bin/clonepack serve
./bin/clonepack serve --config /etc/clonepack/config.yaml
```

Par défaut le serveur écoute sur `http://0.0.0.0:8080`.

---

## CLI

Toutes les commandes CLI appellent l'API REST. L'URL du serveur se configure avec `--api-url` (défaut : `http://localhost:8080`).

### Dépôts

```bash
# Créer un dépôt RPM (sync auto)
./bin/clonepack repo create \
  --name rocky9-baseos \
  --type rpm \
  --source-url https://download.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os

# Créer un dépôt APT
./bin/clonepack repo create \
  --name debian-bookworm \
  --type apt \
  --source-url https://deb.debian.org/debian \
  --suite bookworm \
  --components main,contrib \
  --arch amd64

# Créer avec validation manuelle
./bin/clonepack repo create \
  --name debian-bookworm \
  --type apt \
  --source-url https://deb.debian.org/debian \
  --suite bookworm \
  --sync-mode manual

# Lister les dépôts
./bin/clonepack repo list

# Détail d'un dépôt
./bin/clonepack repo get 1

# Modifier un dépôt (source URL, sync mode, config APT)
./bin/clonepack repo update 1 --source-url https://archive.debian.org/debian
./bin/clonepack repo update 1 --suite bookworm-backports
./bin/clonepack repo update 1 --components main,contrib,non-free
./bin/clonepack repo update 1 --sync-mode manual

# Supprimer un dépôt
./bin/clonepack repo delete 1
```

Les flags `--suite`, `--components` et `--arch` ne s'appliquent qu'aux dépôts de type `apt`.
Seuls les flags fournis sont modifiés — les autres champs restent inchangés.

### Clonage

```bash
# Lancer le clonage complet d'un dépôt (télécharge tous les paquets)
./bin/clonepack repo clone 1
```

Le clonage est asynchrone : la commande affiche la progression du job jusqu'à completion.

### Synchronisation

```bash
# Déclencher un scan pour détecter les nouveaux paquets
./bin/clonepack repo sync 1

# Lister les paquets en attente de validation (mode manual)
./bin/clonepack repo sync-list 1

# Approuver des paquets spécifiques (téléchargement en arrière-plan)
./bin/clonepack repo sync-approve 1 42 43 44

# Approuver tous les paquets en attente
./bin/clonepack repo sync-approve 1 --all

# Rejeter des paquets (ils réapparaîtront au prochain scan)
./bin/clonepack repo sync-reject 1 42
```

Le scheduler tourne automatiquement selon l'intervalle configuré (`sync.interval`). En mode `auto`, les nouveaux paquets sont téléchargés directement. En mode `manual`, ils s'accumulent dans la liste d'attente.

### Blocklist

Les paquets bloqués n'apparaissent plus jamais dans la liste pending, quelle que soit leur version.

```bash
# Bloquer définitivement un paquet (par ID de la liste pending)
# → bloque la version exacte ET toutes les futures versions du même paquet
./bin/clonepack repo sync-block 1 42 43

# Voir les paquets bloqués
./bin/clonepack repo sync-blocklist 1

# Débloquer (par ID de la liste blocked)
./bin/clonepack repo sync-unblock 1 1 2
```

### Snapshots

```bash
# Créer un snapshot manuellement
./bin/clonepack repo snapshot create 1
./bin/clonepack repo snapshot create 1 --label "avant-mise-a-jour"

# Lister les snapshots d'un dépôt
./bin/clonepack repo snapshot list 1

# Détail d'un snapshot (métadonnées + liste des paquets)
./bin/clonepack repo snapshot show 1 3

# Comparer deux snapshots
./bin/clonepack repo snapshot diff 1 2 3

# Rollback vers un snapshot (supprime les paquets intrus, re-télécharge les manquants)
./bin/clonepack repo snapshot rollback 1 2

# Supprimer un snapshot
./bin/clonepack repo snapshot delete 1 3
```

Un snapshot automatique est créé après chaque `sync-approve` sur un dépôt RPM.

---

## Proxy miroir

ClonePack expose chaque dépôt cloné comme un miroir HTTP. L'accès est possible par **ID numérique** ou par **nom du dépôt** :

```
http://<host>:<port>/mirror/<repo_id>/
http://<host>:<port>/mirror/<nom_du_depot>/
```

Le proxy sert uniquement ce qui a été cloné localement (mode local-only). Si un fichier est absent, le serveur retourne 404.

**Configuration YUM/DNF** (`/etc/yum.repos.d/clonepack.repo`) :
```ini
[rocky9-baseos]
name=Rocky Linux 9 BaseOS via ClonePack
baseurl=http://clonepack:8080/mirror/rocky9-baseos
enabled=1
gpgcheck=0
```

**Configuration APT** (`/etc/apt/sources.list.d/clonepack.list`) :
```
deb [trusted=yes] http://clonepack:8080/mirror/debian-bookworm bookworm main contrib
```

---

## Sécurité

L'API REST (`/api/v1/*`) est accessible à tous, mais **localhost** (`127.0.0.1` / `::1`) est une IP privilégiée — elle sera toujours autorisée sans token, y compris une fois le système d'authentification en place.

Le proxy miroir (`/mirror/*`) est accessible sans restriction — c'est intentionnel pour permettre aux machines clientes (serveurs APT/YUM) d'accéder aux paquets.

Chaque appel à l'API est identifié par une `Action` (`repos:read`, `sync:approve`, `snapshots:rollback`, etc.) et la ressource concernée (repo ID). Cette infrastructure est prête à accueillir un système RBAC par token sans modifier les handlers.

---

## API REST

| Méthode | Route | Action |
|---------|-------|--------|
| `GET` | `/health` | Santé du serveur |
| `POST` | `/api/v1/repos` | Créer un dépôt |
| `GET` | `/api/v1/repos` | Lister les dépôts |
| `GET` | `/api/v1/repos/{id}` | Détail d'un dépôt |
| `PATCH` | `/api/v1/repos/{id}` | Modifier un dépôt |
| `DELETE` | `/api/v1/repos/{id}` | Supprimer un dépôt |
| `POST` | `/api/v1/repos/{id}/clone` | Démarrer le clonage |
| `GET` | `/api/v1/repos/{id}/clone/status` | Statut du clonage |
| `POST` | `/api/v1/repos/{id}/sync/trigger` | Déclencher un scan |
| `GET` | `/api/v1/repos/{id}/sync/pending` | Paquets en attente |
| `POST` | `/api/v1/repos/{id}/sync/approve` | Approuver des paquets |
| `POST` | `/api/v1/repos/{id}/sync/reject` | Rejeter des paquets |
| `POST` | `/api/v1/repos/{id}/sync/block` | Bloquer définitivement des paquets |
| `POST` | `/api/v1/repos/{id}/sync/unblock` | Débloquer des paquets |
| `GET` | `/api/v1/repos/{id}/sync/blocked` | Lister les paquets bloqués |
| `POST` | `/api/v1/repos/{id}/snapshots` | Créer un snapshot |
| `GET` | `/api/v1/repos/{id}/snapshots` | Lister les snapshots |
| `GET` | `/api/v1/repos/{id}/snapshots/{snap_id}` | Détail d'un snapshot |
| `DELETE` | `/api/v1/repos/{id}/snapshots/{snap_id}` | Supprimer un snapshot |
| `GET` | `/api/v1/repos/{id}/snapshots/diff?from=X&to=Y` | Diff deux snapshots |
| `POST` | `/api/v1/repos/{id}/snapshots/{snap_id}/rollback` | Rollback |
| `GET` | `/mirror/{id_ou_nom}/*` | Proxy miroir HTTP |

**Exemple de création d'un dépôt APT via REST :**
```bash
curl -X POST http://localhost:8080/api/v1/repos \
  -H "Content-Type: application/json" \
  -d '{
    "name": "debian-bookworm",
    "type": "apt",
    "source_url": "https://deb.debian.org/debian",
    "apt_suite": "bookworm",
    "apt_components": ["main", "contrib"],
    "apt_architectures": ["amd64"],
    "sync_mode": "manual"
  }'
```

**Exemple de modification via REST :**
```bash
curl -X PATCH http://localhost:8080/api/v1/repos/1 \
  -H "Content-Type: application/json" \
  -d '{"source_url": "https://archive.debian.org/debian", "apt_suite": "buster"}'
```