Ajout de fonctionnalité de download asynchrone au pmocache

pmocache/examples/README_EXAMPLES.md

@@ -0,0 +1,205 @@
+# Exemples du module Download
+
+Ce répertoire contient des exemples d'utilisation du module `download` de pmocache.
+
+## Fichiers
+
+### `test_download.rs`
+Exemple basique de téléchargement sans transformation.
+
+**Utilisation:**
+```bash
+cargo run --example test_download
+```
+
+### `test_download_transformer.rs`
+Exemples complets de transformers :
+- Transformation en majuscules
+- Suppression de header (skip N bytes)
+- Numérotation des lignes
+- Compression GZIP (commenté, nécessite async-compression)
+
+**Utilisation:**
+```bash
+cargo run --example test_download_transformer
+```
+
+### `simple_transformer.rs`
+Exemple de documentation montrant la syntaxe et l'API.
+
+**Utilisation:**
+```bash
+cargo run --example simple_transformer
+```
+
+## Concepts clés
+
+### 1. Téléchargement simple
+
+```rust
+use pmocache::download::download;
+
+let dl = download("/tmp/file.dat", "https://example.com/file.dat");
+dl.wait_until_finished().await?;
+```
+
+### 2. Téléchargement avec transformer
+
+Un transformer est une fonction qui :
+1. Reçoit le stream de réponse HTTP
+2. Reçoit un fichier ouvert en écriture
+3. Reçoit un callback de progression
+4. Traite les données à la volée
+5. Écrit le résultat transformé dans le fichier
+
+```rust
+let transformer: StreamTransformer = Box::new(|response, mut file, update_progress| {
+    Box::pin(async move {
+        let mut stream = response.bytes_stream();
+        let mut total = 0u64;
+
+        while let Some(chunk_result) = stream.next().await {
+            let chunk = chunk_result.map_err(|e| e.to_string())?;
+
+            // Transformer les données
+            let transformed = your_transformation(&chunk);
+
+            // Écrire le résultat
+            file.write_all(&transformed).await.map_err(|e| e.to_string())?;
+
+            // Mettre à jour la progression
+            total += transformed.len() as u64;
+            update_progress(total);
+        }
+
+        file.flush().await.map_err(|e| e.to_string())?;
+        Ok(())
+    })
+});
+
+let dl = download_with_transformer("/tmp/output.dat", "https://example.com/input.dat", Some(transformer));
+```
+
+### 3. Suivi de progression
+
+```rust
+let dl = download("/tmp/file.dat", "https://example.com/file.dat");
+
+// Attendre au moins 1MB
+dl.wait_until_min_size(1024 * 1024).await?;
+println!("Au moins 1MB téléchargés");
+
+// Voir la progression
+loop {
+    let current = dl.current_size().await;
+    let expected = dl.expected_size().await;
+
+    if let Some(total) = expected {
+        println!("Progression: {}/{} bytes ({:.1}%)",
+            current, total, 100.0 * current as f64 / total as f64);
+    } else {
+        println!("Téléchargés: {} bytes", current);
+    }
+
+    if dl.finished().await {
+        break;
+    }
+
+    tokio::time::sleep(Duration::from_millis(100)).await;
+}
+```
+
+## Cas d'usage pour PMOMusic
+
+### Conversion d'images pour le cache
+
+```rust
+// Télécharger une couverture d'album et la convertir en WebP
+fn webp_transformer() -> StreamTransformer {
+    Box::new(|response, mut file, update_progress| {
+        Box::pin(async move {
+            let bytes = response.bytes().await.map_err(|e| e.to_string())?;
+            let img = image::load_from_memory(&bytes)
+                .map_err(|e| format!("Decode error: {}", e))?;
+
+            let encoder = webp::Encoder::from_image(&img)
+                .map_err(|e| format!("Encode error: {}", e))?;
+            let webp = encoder.encode(75.0);
+
+            file.write_all(&*webp).await.map_err(|e| e.to_string())?;
+            file.flush().await.map_err(|e| e.to_string())?;
+
+            update_progress(webp.len() as u64);
+            Ok(())
+        })
+    })
+}
+
+// Utilisation dans pmocovers
+let transformer = webp_transformer();
+let dl = download_with_transformer(cache_path, cover_url, Some(transformer));
+```
+
+### Conversion audio pour le cache
+
+```rust
+// Télécharger du MP3 et le convertir en FLAC
+fn mp3_to_flac_transformer() -> StreamTransformer {
+    Box::new(|response, mut file, update_progress| {
+        Box::pin(async move {
+            let mp3_bytes = response.bytes().await.map_err(|e| e.to_string())?;
+
+            // Décoder MP3
+            let decoded = decode_mp3(&mp3_bytes)?;
+
+            // Encoder FLAC
+            let flac_bytes = encode_flac(&decoded)?;
+
+            file.write_all(&flac_bytes).await.map_err(|e| e.to_string())?;
+            file.flush().await.map_err(|e| e.to_string())?;
+
+            update_progress(flac_bytes.len() as u64);
+            Ok(())
+        })
+    })
+}
+
+// Utilisation dans pmoaudiocache
+let transformer = mp3_to_flac_transformer();
+let dl = download_with_transformer(cache_path, audio_url, Some(transformer));
+```
+
+### Streaming progressif
+
+```rust
+// Commencer à lire pendant le téléchargement
+let dl = download(audio_path, stream_url);
+
+// Attendre le buffer minimal (256KB)
+dl.wait_until_min_size(256 * 1024).await?;
+
+// Ouvrir et commencer à lire
+let mut file = dl.open()?;
+let mut buffer = [0u8; 4096];
+
+loop {
+    // Lire ce qui est disponible
+    match file.read(&mut buffer) {
+        Ok(0) if dl.finished().await => break, // EOF
+        Ok(0) => {
+            // Pas encore de données, attendre un peu
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+        Ok(n) => {
+            // Traiter les données lues
+            process_audio_chunk(&buffer[..n]);
+        }
+        Err(e) => return Err(e.into()),
+    }
+}
+```
+
+## Voir aussi
+
+- [DOWNLOAD_MODULE.md](../DOWNLOAD_MODULE.md) - Documentation complète du module
+- [src/download.rs](../src/download.rs) - Code source