88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
|
# Plan d'amélioration technique - obiskio
|
|||
|
|
|
|||
|
|
## 1. Contexte et objectifs
|
|||
|
|
- **Objectif** : Renforcer la robustesse, la maintenabilité et les performances de la crate `obiskio`.
|
|||
|
|
- **Priorités** :
|
|||
|
|
1. Gestion des erreurs
|
|||
|
|
2. Optimisation de la mémoire du pool
|
|||
|
|
3. Robustesse concurrente
|
|||
|
|
4. Couverture de tests
|
|||
|
|
5. Documentation
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. Axes d'amélioration détaillés
|
|||
|
|
|
|||
|
|
### 2.1 Gestion des erreurs
|
|||
|
|
- **Problème** : `SKError` ne couvre pas tous les cas (format invalide, taille maximale, CRC)
|
|||
|
|
- **Actions** :
|
|||
|
|
- Ajouter variante `ParseError(String)` dans `src/error.rs`
|
|||
|
|
- Valider les tailles de SuperKmer avant parsing
|
|||
|
|
- Remplacer `expect()` par `unwrap_or_else` avec messages explicites
|
|||
|
|
- Documenter chaque variante d’erreur dans le README
|
|||
|
|
|
|||
|
|
### 2.2 Optimisation du pool de fichiers
|
|||
|
|
- **Problème** : `SKFilePool` utilise un `Vec<WriteEntry>` non contraint et n’effectue pas de nettoyage en cas d’erreur
|
|||
|
|
- **Actions** :
|
|||
|
|
- Implémenter un `LimitedVec` avec limite stricte à `MAX_POOL_SIZE`
|
|||
|
|
- Créer `clear_memory()` qui supprime les entrées orphelines
|
|||
|
|
- Ajouter `evict_lru_threshold()` pour éviction proactive
|
|||
|
|
- Introduire un `RwLock` pour les opérations de lecture massives
|
|||
|
|
|
|||
|
|
### 2.3 Robustesse concurrente
|
|||
|
|
- **Problème** : Risque de deadlocks dans `SKFileWriter::write_batch()` et `SKFileReader::reopen_and_seek()`
|
|||
|
|
- **Actions** :
|
|||
|
|
- Remplacer `Mutex` par `RwLock` pour les accès en lecture
|
|||
|
|
- Ajouter un compteur de blocage et logs de timeout
|
|||
|
|
- Utiliser `std::thread::park_timeout` pour débloquer
|
|||
|
|
- Insérer `debug_assert!` sur les états invariants
|
|||
|
|
|
|||
|
|
### 2.4 Couverture de tests
|
|||
|
|
- **Problème** : Absence de benchmarks, de tests de migration, de résilience de fichiers corrompus
|
|||
|
|
- **Actions** :
|
|||
|
|
- Benchmarks I/O sur 10k+ SuperKmer avec `criterion`
|
|||
|
|
- Tests de migration de version de fichier `.meta` → `.v2.meta`
|
|||
|
|
- Tests de corruption volontaire (truncature, inversion de bits)
|
|||
|
|
- Tests de stress sur pool saturation (100 threads)
|
|||
|
|
|
|||
|
|
### 2.5 Documentation & exemples
|
|||
|
|
- **Actions** :
|
|||
|
|
- Ajouter des examples dans chaque module (`# Examples`)
|
|||
|
|
- Documenter la logique LRU avec diagrammes Mermaid
|
|||
|
|
- Créer un guide « How to recover from eviction »
|
|||
|
|
- Mettre à jour le `README.md` avec tableau des variantes d’erreur
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. Plan d'exécution (Roadmap)
|
|||
|
|
|
|||
|
|
| Sprint | Durée | Livrables clés |
|
|||
|
|
|--------|-------|----------------|
|
|||
|
|
| **S1** | 2 jours | Refactorisation `SKError`, ajout de tests unitaires |
|
|||
|
|
| **S2** | 3 jours | Implémentation `clear_memory()` + `LimitedVec` |
|
|||
|
|
| **S3** | 2 jours | Passage à `RwLock`, ajout de compteurs de blocage |
|
|||
|
|
| **S4** | 2 jours | Benchmarks + tests de migration |
|
|||
|
|
| **S5** | 1 jour | Documentation finale & mise à jour du README |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. Dépendances externes
|
|||
|
|
- Mettre à jour `niffler` vers la version 2.0 (performance compression)
|
|||
|
|
- Évaluer `bincode` vs `serde_json` pour les métas (I/O)
|
|||
|
|
- Ajouter dépendance `criterion` (dev‑dependencies)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. KPI de suivi
|
|||
|
|
- **Couverture de tests** : ≥85 % des chemins critiques
|
|||
|
|
- **Latence moyenne d’écriture** : ↓15 % après optimisation du pool
|
|||
|
|
- **Taux d’erreurs résolues** : 100 % des nouvelles variantes couvertes
|
|||
|
|
- **Temps de build CI** : ≤5 min pour l’ensemble des benchmarks
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. Validation finale
|
|||
|
|
- Revue de code avec `cargo clippy -- -D warnings`
|
|||
|
|
- Analyse de toxicité avec `cargo deny open-source-licenses`
|
|||
|
|
- Vérification de la conformité aux standards de naming du projet
|