Rapport : Implémentation des items épinglables dans PMOcache

Modification de enforce_limit()

La politique d’éviction a été améliorée :

1. Suppression prioritaire des items expirés : Les items dont le TTL est dépassé sont supprimés en premier
2. Comptage des items non épinglés : Utilise count_unpinned() au lieu de count()
3. Protection des items épinglés : Ils ne peuvent pas être évincés par LRU
4. Logging amélioré : Messages distincts pour les items expirés et l’éviction LRU

3. Tests (pmocache/tests/test_pinnable.rs)

Création d’une suite complète de tests (9 tests, tous passants) :

1. test_pin_unpin : Vérifie l’épinglage et le désépinglage basiques
2. test_pinned_excluded_from_lru : Vérifie que les items épinglés ne sont pas évincés
3. test_pinned_count_separately : Vérifie le comptage séparé des items épinglés
4. test_cannot_pin_with_ttl : Vérifie la règle métier TTL → pas de pinning
5. test_cannot_set_ttl_when_pinned : Vérifie la règle métier pinned → pas de TTL
6. test_ttl_expiration : Vérifie la suppression automatique des items expirés
7. test_clear_ttl : Vérifie la suppression du TTL
8. test_get_expired : Vérifie la récupération des items expirés
9. test_cache_entry_fields : Vérifie les valeurs des champs dans CacheEntry

Règles métier implémentées

Incompatibilité TTL ↔︎ Pinned

Un item ne peut pas être à la fois épinglé ET avoir un TTL :

• Si TTL défini : pin() retourne une erreur
• Si épinglé : set_ttl() retourne une erreur

Cette règle garantit une sémantique claire : - Épinglé = permanent, protégé de l’éviction - TTL = temporaire, sera supprimé à expiration

Comptage des items

Les items épinglés sont exclus du comptage de la limite du cache :

• Un cache de limite 100 peut contenir 100 items non épinglés + N items épinglés
• Seuls les items non épinglés sont pris en compte pour l’éviction LRU

Ordre de suppression lors de enforce_limit()

1. Items expirés (TTL dépassé) : supprimés en priorité
2. Items LRU : si la limite est toujours dépassée, suppression des plus vieux items non épinglés

Compatibilité

Migration de base de données

Aucune migration nécessaire : Les colonnes pinned et ttl_expires_at ont des valeurs par défaut : - pinned = 0 (non épinglé) - ttl_expires_at = NULL (pas de TTL)

Les bases existantes seront automatiquement mises à jour au prochain démarrage via le CREATE TABLE IF NOT EXISTS avec les nouvelles colonnes.

Rétrocompatibilité du code

Toutes les méthodes existantes continuent de fonctionner sans modification : - Les items existants ne sont pas épinglés par défaut - Le comportement LRU standard reste identique pour les items non épinglés

Exemples d’utilisation

Utilisation programmatique (Rust)

use pmocache::{Cache, CacheConfig};
use chrono::{Duration, Utc};

// Créer un cache
let cache = Cache::<MyConfig>::new("./cache", 100).unwrap();

// Ajouter un fichier
let pk = cache.add_from_url("https://example.com/file.dat", None).await?;

// Épingler pour protéger de l'éviction
cache.pin(&pk).await?;

// Ou définir un TTL de 24 heures
let expires_at = (Utc::now() + Duration::hours(24)).to_rfc3339();
cache.set_ttl(&pk2, &expires_at).await?;

// Vérifier le statut
if cache.is_pinned(&pk).await? {
    println!("Fichier protégé");
}

GET /api/cache/{pk}/pin

Response 200 OK:
{
  "pk": "1a2b3c4d5e6f7a8b",
  "pinned": false,
  "ttl_expires_at": null
}

POST /api/cache/{pk}/pin

Response 200 OK:
{
  "pk": "1a2b3c4d5e6f7a8b",
  "message": "Item '1a2b3c4d5e6f7a8b' pinned successfully"
}

Response 409 CONFLICT (si TTL défini):
{
  "error": "CONFLICT",
  "message": "Cannot pin an item with TTL set. Clear TTL first."
}

DELETE /api/cache/{pk}/pin

Response 200 OK:
{
  "pk": "1a2b3c4d5e6f7a8b",
  "message": "Item '1a2b3c4d5e6f7a8b' unpinned successfully"
}

POST /api/cache/{pk}/ttl
Content-Type: application/json

{
  "expires_at": "2025-01-20T10:30:00Z"
}

Response 200 OK:
{
  "pk": "1a2b3c4d5e6f7a8b",
  "message": "TTL set successfully for item '1a2b3c4d5e6f7a8b'"
}

Response 409 CONFLICT (si épinglé):
{
  "error": "CONFLICT",
  "message": "Cannot set TTL on a pinned item. Unpin first."
}

Response 400 BAD REQUEST (format invalide):
{
  "error": "INVALID_DATE",
  "message": "Invalid RFC3339 date format"
}

DELETE /api/cache/{pk}/ttl

Response 200 OK:
{
  "pk": "1a2b3c4d5e6f7a8b",
  "message": "TTL cleared successfully for item '1a2b3c4d5e6f7a8b'"
}

{
  "error": "CODE_ERREUR",
  "message": "Description lisible de l'erreur"
}