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

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

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)

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)

# 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"

• Le module compile sans erreur avec la commande recommandée
• Les migrations passent sur veza_lab sans erreur
• Le module se lance en utilisant la vraie BDD (pas de mode offline)
• L'endpoint /healthz renvoie un statut OK (200)
• L'endpoint /health renvoie un statut OK (200) - ÉCHEC (retourne 503)
• Les logs au démarrage sont propres (pas de panic / stacktrace critique)
• Le serveur écoute sur le port configuré (8082)
• 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:

# 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:

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)