Rapport Final : Items Épinglables et TTL dans PMOcache

Fichiers modifiés

Phase 1 : Implémentation de base

1. pmocache/src/db.rs (380 lignes ajoutées)
   • Modification du schéma SQL (colonnes pinned, ttl_expires_at)
   • Ajout de champs dans CacheEntry
   • 8 nouvelles méthodes : count_unpinned(), pin(), unpin(), is_pinned(), set_ttl(), clear_ttl(), get_expired()
   • Modification de get_oldest() pour exclure les items épinglés
   • Mise à jour de toutes les requêtes SELECT
2. pmocache/src/cache.rs (135 lignes ajoutées)
   • 5 nouvelles méthodes publiques : pin(), unpin(), is_pinned(), set_ttl(), clear_ttl()
   • Refonte complète de enforce_limit() :
     • Suppression prioritaire des items expirés
     • Utilisation de count_unpinned()
     • Protection des items épinglés
3. pmocache/tests/test_pinnable.rs (280 lignes, nouveau fichier)
   • 9 tests exhaustifs
   • Couverture complète des cas d’usage
   • Validation des règles métier

Phase 2 : Enrichissement API REST

4. pmocache/src/api.rs (230 lignes ajoutées)
   • 3 nouvelles structures : SetTtlRequest, PinResponse, PinStatus
   • 5 nouveaux handlers HTTP avec gestion d’erreurs complète
   • Validation des règles métier au niveau HTTP
   • Codes de statut appropriés (200, 400, 404, 409, 500)
5. pmocache/src/pmoserver_ext.rs (15 lignes modifiées)
   • 2 nouvelles routes dans create_api_router() :
     • /{pk}/pin (GET, POST, DELETE)
     • /{pk}/ttl (POST, DELETE)
   • Documentation des routes mise à jour
6. pmocache/src/openapi.rs (10 lignes modifiées)
   • Macro create_cache_openapi! enrichie
   • 5 nouveaux endpoints documentés
   • 3 nouveaux schémas de données
7. pmocache/src/lib.rs (5 lignes modifiées)
   • Export des structures publiques pour l’API

Total : 7 fichiers modifiés, ~1055 lignes de code ajoutées

Avantages de la solution

1. Architecture propre et extensible

• Séparation des responsabilités :
  • db.rs : logique de base de données
  • cache.rs : logique métier
  • api.rs : interface HTTP
• Réutilisabilité :
  • Traits existants conservés
  • Pas de duplication de code
  • Pattern cohérent avec l’architecture PMOcache

2. Sécurité et fiabilité

• Règles métier strictes :
  • Incompatibilité TTL ↔︎ Pinned appliquée à tous les niveaux
  • Validation au niveau DB, cache ET API
• Gestion d’erreurs robuste :
  • Codes HTTP sémantiques
  • Messages explicites
  • Pas d’état incohérent possible

3. Performance

• Requêtes SQL optimisées :
  • Index sur pinned pour requêtes rapides
  • WHERE pinned = 0 évite le scan complet
• Comptage efficace :
  • count_unpinned() utilise un index
  • Pas de post-filtrage en mémoire

4. Expérience développeur

• API intuitive :
  • Méthodes async cohérentes avec l’existant
  • Nommage clair (pin(), unpin(), set_ttl())
• Documentation complète :
  • OpenAPI générée automatiquement
  • Swagger UI interactive
  • Exemples d’utilisation

5. Compatibilité

• Migration transparente :
  • Aucune intervention manuelle
  • Valeurs par défaut appropriées
• Pas de breaking change :
  • API existante inchangée
  • Nouveaux champs optionnels dans CacheEntry

Cas d’usage concrets

1. Cache de couvertures d’albums

// Épingler les couvertures des albums favoris
for album in user.favorite_albums {
    let cover_pk = covers_cache.get_cover_pk(&album.id).await?;
    covers_cache.pin(&cover_pk).await?;
}

// → Les couvertures favorites restent toujours en cache
// → Même si le cache se remplit de nouvelles couvertures

// Pistes complètes : épinglées si dans la playlist courante
for track in current_playlist.tracks {
    audio_cache.pin(&track.pk).await?;
}

// Previews de 30 secondes : TTL de 1 heure
let preview_pk = audio_cache.add_preview(&track_url).await?;
let expires_at = (Utc::now() + Duration::hours(1)).to_rfc3339();
audio_cache.set_ttl(&preview_pk, &expires_at).await?;

// → Pistes courantes toujours disponibles
// → Previews nettoyées automatiquement

// Métadonnées d'album : TTL de 24h pour forcer le rafraîchissement
let metadata_pk = metadata_cache.add_metadata(&album).await?;
let tomorrow = (Utc::now() + Duration::days(1)).to_rfc3339();
metadata_cache.set_ttl(&metadata_pk, &tomorrow).await?;

// → Métadonnées rafraîchies quotidiennement
// → Pas de données obsolètes

// Surveiller le nombre d'items épinglés
let pinned_count = cache.db.count()? - cache.db.count_unpinned()?;
if pinned_count > MAX_PINNED_ITEMS {
    warn!("Too many pinned items: {}", pinned_count);
}

// Option 1 : Appel périodique
tokio::spawn(async move {
    loop {
        tokio::time::sleep(Duration::from_secs(3600)).await;
        cache.enforce_limit().await?;
    }
});

// Option 2 : Vérification à l'accès
if let Ok(entry) = cache.db.get(&pk, false) {
    if let Some(ttl) = entry.ttl_expires_at {
        if Utc::now() > DateTime::parse_from_rfc3339(&ttl)? {
            cache.delete_item(&pk).await?;
        }
    }
}

2025-01-15T10:30:00Z           ✅ UTC
2025-01-15T10:30:00+01:00      ✅ Avec timezone
2025-01-15T10:30:00.123Z       ✅ Avec millisecondes
2025-01-15 10:30:00            ❌ Format invalide

pub async fn start_ttl_worker(&self) {
    tokio::spawn(async move {
        loop {
            self.enforce_limit().await;
            tokio::time::sleep(Duration::from_secs(60)).await;
        }
    });
}

pub async fn pin_if<F>(&self, predicate: F) -> Result<Vec<String>>
where
    F: Fn(&CacheEntry) -> bool,
{
    let entries = self.db.get_all(false)?;
    let mut pinned = Vec::new();
    
    for entry in entries {
        if predicate(&entry) && !entry.pinned {
            self.pin(&entry.pk).await?;
            pinned.push(entry.pk);
        }
    }
    
    Ok(pinned)
}

// Utilisation
cache.pin_if(|e| e.hits > 100).await?;  // Épingler les plus utilisés

pub async fn set_ttl_relative(&self, pk: &str, duration: Duration) -> Result<()> {
    let expires_at = (Utc::now() + duration).to_rfc3339();
    self.set_ttl(pk, &expires_at).await
}

// Utilisation
cache.set_ttl_relative(&pk, Duration::hours(24)).await?;

pub async fn get_pinning_stats(&self) -> Result<PinningStats> {
    Ok(PinningStats {
        total_items: self.db.count()?,
        pinned_items: self.db.count()? - self.db.count_unpinned()?,
        items_with_ttl: self.db.count_with_ttl()?,
        expired_items: self.db.get_expired()?.len(),
    })
}