veza/veza-stream-server/RAPPORT_LAB.md

# 📊 RAPPORT DE VÉRIFICATION - veza-stream-server

**Date**: 2025-12-07  
**Environnement**: Labo (PostgreSQL réel)  
**Base de données**: `veza_lab` (postgres://veza:veza_password@localhost:5432/veza_lab)

---

## 5.1. Résumé exécutable

### Commande de build recommandée

```bash
cd /home/senke/Documents/veza/veza-stream-server
export DATABASE_URL='postgres://veza:veza_password@localhost:5432/veza_lab?sslmode=disable'
cargo build
```

**Note importante**: SQLx vérifie les requêtes à la compilation. La base de données doit être accessible et les tables `stream_jobs` et `stream_segments` doivent exister avant la compilation.

### Commande de migrations sur la BDD réelle

```bash
cd /home/senke/Documents/veza/veza-stream-server
export VEZA_LAB_DSN='postgres://veza:veza_password@localhost:5432/veza_lab?sslmode=disable'
./scripts/apply_migrations_lab.sh
```

**Fichiers de migrations appliqués**:
- `migrations/001_create_stream_jobs.sql` ✅
- `migrations/002_create_stream_segments.sql` ✅

### Commande de démarrage lab (avec vraie BDD)

```bash
cd /home/senke/Documents/veza/veza-stream-server
export VEZA_LAB_DSN='postgres://veza:veza_password@localhost:5432/veza_lab?sslmode=disable'
./scripts/start_lab.sh
```

**Variables d'environnement requises** (définies automatiquement par le script):
- `DATABASE_URL`: DSN PostgreSQL (obligatoire)
- `SECRET_KEY`: Clé secrète HMAC (générée automatiquement si absente)
- `JWT_SECRET`: Clé JWT (générée automatiquement si absente)
- `STREAM_PORT`: Port d'écoute (défaut: 8082)
- `RUST_LOG`: Niveau de log (défaut: stream_server=info)
- `AUDIO_DIR`: Répertoire audio (défaut: ./audio)

### Tests rapides (curl / autres)

```bash
# Health check simple (liveness)
curl http://localhost:8082/healthz

# Health check détaillé (readiness)
curl http://localhost:8082/health

# Health check alternatif
curl http://localhost:8082/readyz

# Métriques Prometheus
curl http://localhost:8082/metrics

# Endpoint racine
curl http://localhost:8082/
```

---

## 5.2. État actuel du module

### ✅ Ce qui fonctionne réellement aujourd'hui

1. **Compilation**: Le module compile sans erreur avec `cargo build` (après application des migrations)
2. **Démarrage**: Le serveur démarre et écoute sur le port 8082
3. **Endpoints HTTP**: Les routes répondent correctement:
   - `/healthz` retourne `200 OK` avec statut "healthy"
   - `/health` retourne `503 Service Unavailable` (voir problèmes ci-dessous)
   - `/metrics` expose les métriques Prometheus
4. **Migrations SQL**: Les migrations s'appliquent correctement sur `veza_lab`
5. **Connexion initiale BDD**: Le script de démarrage vérifie la connexion PostgreSQL avec succès
6. **Mode dégradé**: Le serveur démarre même si RabbitMQ n'est pas disponible (mode dégradé)

### ⚠️ Ce qui est partiellement fonctionnel

1. **Health Monitor - Base de données**:
   - Le health monitor signale la base de données comme "down" alors que la connexion initiale fonctionne
   - **Cause probable**: Le health monitor utilise peut-être une URL différente ou un pool différent
   - **Impact**: `/health` retourne 503 au lieu de 200
   - **Workaround**: `/healthz` fonctionne et indique que le service est "healthy"

2. **Répertoire audio**:
   - Le répertoire `./audio` n'existe pas par défaut
   - Le script de démarrage le crée automatiquement, mais il est vide
   - **Impact**: Les endpoints de streaming ne peuvent pas servir de fichiers

3. **FFmpeg**:
   - FFmpeg n'est pas installé sur le système de test
   - **Impact**: Le transcodage audio est désactivé (mode dégradé)
   - **Workaround**: Le serveur démarre mais les fonctionnalités de transcodage sont indisponibles

4. **RabbitMQ**:
   - RabbitMQ n'est pas disponible (connexion refusée)
   - **Impact**: L'Event Bus est désactivé (mode dégradé)
   - **Workaround**: Le serveur fonctionne sans Event Bus

### 🔴 Ce qui est cassé ou bloquant

#### P0 – Bloquant

1. **Bug CORS corrigé** ✅
   - **Problème**: Panic au démarrage si `ALLOWED_ORIGINS=*`
   - **Erreur**: `Wildcard origin (*) cannot be passed to AllowOrigin::list`
   - **Statut**: ✅ **CORRIGÉ** dans `src/routes/api.rs`
   - **Solution**: Utilisation de `AllowOrigin::any()` quand `ALLOWED_ORIGINS=*`

2. **Health Monitor - Connexion BDD** 🔴
   - **Problème**: Le health monitor ne peut pas se connecter à la base de données
   - **Symptôme**: `/health` retourne 503 avec `"database_status": "down"`
   - **Cause à investiguer**: Différence entre l'URL utilisée par le health monitor et celle fournie via `DATABASE_URL`
   - **Impact**: Le readiness check échoue, mais le serveur fonctionne

#### P1 – Majeur

1. **Migrations non automatiques**:
   - Les migrations SQL ne sont pas appliquées automatiquement au démarrage
   - Le flag `migrate_on_start` existe dans la config mais n'est pas utilisé
   - **Impact**: Les migrations doivent être appliquées manuellement avant le premier démarrage

2. **Dépendances externes non vérifiées**:
   - FFmpeg n'est pas vérifié au démarrage (seulement détecté par le health monitor)
   - **Impact**: Erreurs silencieuses si FFmpeg est manquant

#### P2 – Moyen

1. **Warnings de compilation**:
   - Import inutilisé: `axum::serve` dans `src/main.rs`
   - Champs non utilisés dans `simple_stream_server.rs`
   - **Impact**: Aucun, mais pollue les logs de compilation

2. **Future incompatibilities**:
   - Packages `redis v0.25.4` et `sqlx-postgres v0.7.4` contiennent du code qui sera rejeté par une future version de Rust
   - **Impact**: Aucun immédiat, mais nécessitera une mise à jour des dépendances

#### P3 – Cosmétique

1. **Logs verbeux**: Les logs du health monitor sont très verbeux (beaucoup d'alertes répétées)
2. **Documentation**: Le fichier `env.example` ne documente pas toutes les variables d'environnement utilisées

---

## 5.3. Checklist "Aucune régression"

- [x] Le module compile sans erreur avec la commande recommandée
- [x] Les migrations passent sur `veza_lab` sans erreur
- [x] Le module se lance en utilisant la vraie BDD (pas de mode offline)
- [x] L'endpoint `/healthz` renvoie un statut OK (200)
- [ ] L'endpoint `/health` renvoie un statut OK (200) - **ÉCHEC** (retourne 503)
- [x] Les logs au démarrage sont propres (pas de panic / stacktrace critique)
- [x] Le serveur écoute sur le port configuré (8082)
- [x] Les métriques Prometheus sont exposées sur `/metrics`

**Note**: Le health check détaillé (`/health`) échoue car le health monitor signale la base de données comme "down", mais le serveur fonctionne correctement. Le health check simple (`/healthz`) fonctionne.

---

## 5.4. Recommandations courtes (max 5 actions)

### 1. 🔴 P0 - Corriger le health monitor pour la connexion BDD

**Action**: Investiguer pourquoi le health monitor ne peut pas se connecter à la base de données alors que la connexion initiale fonctionne.

**Fichiers à vérifier**:
- `src/health/mod.rs` (méthode `test_database_connection`)
- `src/analytics/mod.rs` (initialisation du pool)

**Commande de test**:
```bash
# Vérifier que le health monitor utilise la même URL que DATABASE_URL
grep -r "database_url\|DATABASE_URL" src/health/
```

### 2. 🟠 P1 - Implémenter l'application automatique des migrations

**Action**: Utiliser le flag `migrate_on_start` pour appliquer les migrations automatiquement au démarrage.

**Fichiers à modifier**:
- `src/lib.rs` ou `src/main.rs` (ajouter la logique d'application des migrations)

**Exemple d'implémentation**:
```rust
if config.database.migrate_on_start {
    sqlx::migrate!("./migrations")
        .run(&pool)
        .await?;
}
```

### 3. 🟡 P2 - Vérifier les dépendances au démarrage

**Action**: Vérifier la présence de FFmpeg et autres dépendances externes au démarrage et afficher un warning clair si elles sont manquantes.

**Fichiers à modifier**:
- `src/lib.rs` (dans `AppState::new`)

### 4. 🟡 P2 - Nettoyer les warnings de compilation

**Action**: Supprimer les imports et champs inutilisés.

**Fichiers à modifier**:
- `src/main.rs` (supprimer `use axum::serve;`)
- `src/simple_stream_server.rs` (supprimer ou utiliser les champs non utilisés)

### 5. ⚪ P3 - Améliorer la documentation des variables d'environnement

**Action**: Mettre à jour `env.example` avec toutes les variables d'environnement utilisées par le module.

**Variables manquantes dans `env.example`**:
- `DATABASE_URL` (obligatoire)
- `JWT_SECRET` (obligatoire)
- `BACKEND_URL`
- `RABBITMQ_URL`
- `REDIS_URL`
- `STREAM_PORT` (au lieu de `STREAM_SERVER_PORT`)

---

## 5.5. Inventaire rapide `veza-stream-server`

- **Langage principal**: Rust (édition 2021)
- **Point(s) d'entrée (main)**: 
  - `src/main.rs` → binaire `stream_server`
  - `src/simple_stream_server.rs` → binaire `simple_stream_server`
- **Fichier(s) de config principaux**: 
  - `env.example` (template)
  - `.env` (configuration locale)
  - `src/config/mod.rs` (chargement depuis variables d'environnement)
- **Dépendances externes**: 
  - PostgreSQL (obligatoire)
  - Redis (optionnel)
  - RabbitMQ (optionnel, mode dégradé si absent)
  - FFmpeg (optionnel, requis pour transcodage)
- **Vars d'environnement critiques**: 
  - `DATABASE_URL` (obligatoire)
  - `SECRET_KEY` (obligatoire, min 32 caractères)
  - `JWT_SECRET` (obligatoire, min 32 caractères)
  - `STREAM_PORT` (défaut: 8082)
  - `ALLOWED_ORIGINS` (défaut: localhost)
- **Ports utilisés**: 
  - 8082 (HTTP/WebSocket)
  - 9090 (métriques Prometheus, si activé)
- **Migrations SQL**: 
  - `migrations/001_create_stream_jobs.sql`
  - `migrations/002_create_stream_segments.sql`
- **Scripts utilitaires**:
  - `scripts/apply_migrations_lab.sh` (application des migrations)
  - `scripts/start_lab.sh` (démarrage en mode labo)

---

## 5.6. Notes techniques

### Architecture

Le module `veza-stream-server` est un serveur de streaming audio écrit en Rust utilisant:
- **Framework web**: Axum 0.7
- **Base de données**: SQLx 0.7 avec PostgreSQL
- **Async runtime**: Tokio 1.35
- **Logging**: tracing + tracing-subscriber
- **Métriques**: Prometheus via metrics-exporter-prometheus

### Points d'attention

1. **SQLx compile-time checks**: SQLx vérifie les requêtes SQL à la compilation. Les tables doivent exister dans la base de données avant la compilation (ou utiliser `SQLX_OFFLINE=true`, mais ce n'est pas recommandé pour le labo).

2. **Mode dégradé**: Le serveur est conçu pour fonctionner en mode dégradé si certaines dépendances sont absentes (RabbitMQ, Redis, FFmpeg). Le health monitor signale ces dégradations.

3. **Sécurité**: Les secrets (`SECRET_KEY`, `JWT_SECRET`) doivent être générés avec `openssl rand -hex 32` et ne jamais être commités dans le dépôt.

---

**Rapport généré le**: 2025-12-07  
**Statut global**: ⚠️ **Fonctionnel avec réserves** (health monitor BDD à corriger)