diff --git a/docs/superpowers/specs/2026-04-07-supervision-rust-design.md b/docs/superpowers/specs/2026-04-07-supervision-rust-design.md new file mode 100644 index 0000000..012a171 --- /dev/null +++ b/docs/superpowers/specs/2026-04-07-supervision-rust-design.md @@ -0,0 +1,151 @@ +# Design — supervision-rs + +**Date :** 2026-04-07 +**Objectif :** Réécrire l'application de supervision système en Rust pour produire un exécutable Windows standalone, sans dépendances, déployable par simple copie. + +--- + +## Contexte + +L'application actuelle est en Python (Flask + psutil + PyInstaller). Le tuteur a recommandé une réécriture en Rust pour obtenir un exécutable plus stable sur Windows. Le binaire doit être autonome : on le copie sur n'importe quel serveur Windows, on l'installe comme service, et c'est tout. + +--- + +## Périmètre fonctionnel + +Parité complète avec l'app Python actuelle : + +- Interface web sécurisée (login admin, cookie de session) +- Dashboard temps réel : CPU, RAM, disques, processus surveillés +- Alertes email (SMTP plain ou STARTTLS) avec cooldown configurable +- Configuration via UI (seuils, SMTP, intervalle, processus) +- Historique des alertes (max 500, rotation automatique) +- Fonctionne comme service Windows (démarre avec Windows, tourne en arrière-plan) + +--- + +## Architecture + +### Structure du projet + +``` +supervision-rs/ +├── Cargo.toml +├── src/ +│ ├── main.rs # Point d'entrée + intégration service Windows +│ ├── config.rs # Lecture/écriture config.json et alerts.json +│ ├── monitor.rs # Thread de collecte métriques + évaluation seuils +│ ├── alerter.rs # Envoi email SMTP +│ ├── auth.rs # Session admin, rate limiting login +│ └── routes.rs # Endpoints Axum (dashboard, API, config, login) +├── templates/ # Templates Tera (portés depuis Jinja2) +│ ├── base.html +│ ├── dashboard.html +│ ├── login.html +│ ├── config.html +│ └── alerts.html +└── data/ # Créé au premier lancement (gitignored) + ├── config.json + └── alerts.json +``` + +### Crates + +| Crate | Rôle | Équivalent Python | +|---|---|---| +| `axum` | Serveur HTTP async | Flask | +| `tokio` | Runtime async | — | +| `tera` | Templates HTML | Jinja2 | +| `sysinfo` | Métriques CPU/RAM/disque/processus | psutil | +| `lettre` | Email SMTP | smtplib | +| `serde` + `serde_json` | Sérialisation config/alertes | json | +| `windows-service` | Intégration service Windows | — | +| `tower-sessions` | Sessions auth (cookie signé) | Flask-Login | +| `tower_governor` | Rate limiting | Flask-Limiter | +| `tracing` | Logs | logging | + +--- + +## Modes de démarrage + +``` +supervision.exe → mode console (test, développement) +supervision.exe install → installe le service Windows +supervision.exe uninstall → supprime le service Windows +(lancé par Windows SCM) → mode service (background automatique) +``` + +Détection automatique dans `main.rs` : si lancé par le Service Control Manager de Windows, entre en mode service. Sinon, mode console. + +**Installation sur un serveur :** +```cmd +supervision.exe install +sc start Supervision +``` + +--- + +## State partagé (concurrence) + +``` +Arc +├── config: RwLock # Config lue/écrite par routes + monitor +├── metrics: RwLock # Écrit par monitor, lu par /api/metrics +└── alerter: Alerter # Utilisé par monitor +``` + +Le thread de monitoring est une `tokio::task` qui tourne en arrière-plan. Il met à jour `metrics` via `RwLock`. Les routes Axum lisent ce state sans bloquer. + +--- + +## Authentification + +- Un seul admin, identifiants stockés dans `config.json` (mot de passe hashé bcrypt) +- Session via cookie signé (`tower-sessions`) +- Rate limiting sur `POST /login` : 10 tentatives/minute +- Toutes les routes (sauf `/login`, `/static`) redirigent vers login si non authentifié + +--- + +## Métriques & seuils + +Collecte via `sysinfo` : +- CPU : pourcentage global +- RAM : pourcentage utilisé, total/utilisé/disponible en Go +- Disques : partitions physiques ≥1 Go, pourcentage, espace total/utilisé/libre +- Processus : recherche par pattern dans nom ou ligne de commande, mémoire RSS, CPU + +Niveaux de statut (identique au Python) : +- `ok` : < 80% du seuil +- `warning` : ≥ 80% du seuil +- `critical` : ≥ 100% du seuil + +--- + +## Alertes email + +- SMTP plain ou STARTTLS (configurable) +- Cooldown par clé (en mémoire, réinitialisé au redémarrage) +- Alertes déclenchées sur : CPU critique, RAM critique, disque critique, processus arrêté, mémoire processus critique +- Stockage dans `alerts.json` (max 500 entrées, rotation FIFO) + +--- + +## Persistance + +- `data/config.json` : configuration complète (seuils, SMTP, admin, processus surveillés, intervalle) +- `data/alerts.json` : historique des alertes +- Dossier `data/` créé automatiquement au premier lancement, dans le même répertoire que l'exe +- Pas de base de données + +--- + +## Déploiement + +1. Compiler sur Windows : `cargo build --release` +2. Récupérer `target/release/supervision.exe` +3. Copier l'exe seul sur le serveur cible +4. Lancer `supervision.exe install` puis `sc start Supervision` +5. Accéder à `http://localhost:5000` dans le navigateur + +Aucune autre dépendance requise sur le serveur cible.