284 lines
11 KiB
Markdown
284 lines
11 KiB
Markdown
# 📊 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)
|
||
|