Presets et mise en cache

Deux préoccupations situées derrière les paramètres de redimensionnement et de format : donner un nom à une combinaison récurrente, et faire que la deuxième requête ne coûte rien.

Presets nommés

Un preset regroupe width, height, fit, crop, quality et format sous un seul nom. C'est une configuration d'opérateur — un objet JSON dans une variable d'environnement, pas dans le schéma — car la bonne taille de vignette est une propriété du déploiement, pas du domaine métier.

STORAGE_TRANSFORM_PRESETS='{
  "thumbnail": { "width": 150, "height": 150, "fit": "cover" },
  "preview":   { "width": 600, "quality": 80 },
  "avatar":    { "width": 64, "height": 64, "fit": "cover", "crop": "attention" }
}'

GET /api/buckets/photos/files/{key}?preset=avatar
GET /api/buckets/photos/files/{key}?preset=thumbnail&quality=95

Situation	Résultat
Preset connu	Ses champs deviennent la transformation.
Paramètre explicite à côté d'un preset	La valeur explicite l'emporte, champ par champ.
Nom de preset inconnu	400
?preset= sans aucun preset configuré	400, avec un message le disant.

Les surcharges sont par champ, pas globales : ?preset=thumbnail&quality=95 conserve le 150×150 cover du preset et ne change que la qualité.

Les noms de presets doivent être alphanumériques avec des traits d'union simples (thumbnail, hero-banner), ce qui les garde sûrs dans une URL. Un JSON malformé, une valeur non-objet ou un nom illégal font échouer le serveur au démarrage plutôt qu'à la première requête — une faute de frappe dans cette variable se découvre au déploiement, pas par un utilisateur.

Mise en cache

Une transformation s'exécute une fois par combinaison distincte. Le résultat est conservé dans un cache LRU local au processus, indexé conjointement sur la clé de stockage, les paramètres de transformation et le format négocié.

Mécanisme	Comportement
Cache-Control	public, max-age=31536000, immutable — un an, jamais revalidé.
ETag	Dérivé du fichier source et des paramètres de transformation.
If-None-Match	Une correspondance renvoie 304 Not Modified.
Cache serveur	LRU en mémoire, évinçant les entrées les moins récemment utilisées à saturation.
Invalidation	Supprimer un fichier évince toutes les transformations dérivées de sa clé.

Variable	Défaut	Signification
STORAGE_TRANSFORM_CACHE_MAX_SIZE	256	Plafond du cache, en mégaoctets.

Une entrée plus lourde que le plafond entier est servie mais jamais conservée — elle évincerait tout le reste pour tenir.

L'en-tête immutable d'un an est sûr précisément parce que les clés sont adressées par contenu — une clé stockée vaut <uuid>-<nom-de-fichier>, donc un fichier remplacé est une nouvelle clé et une nouvelle URL. Rien n'est jamais servi de façon périmée sous une URL dont le contenu aurait changé, car cette situation ne peut pas se produire.

Les originaux ne sont jamais touchés

Garantie	Comportement
Octets sources	Identiques bit à bit après un nombre quelconque de transformations.
Requête sans paramètre	L'original, sous réserve de la seule négociation Accept.
?format=origin	Les octets originaux tels quels, négociation court-circuitée.
Vidage du cache	N'écarte que les variantes dérivées ; les originaux restent disponibles.
Fichiers non-image	Les paramètres de transformation répondent 400 — rien n'est tenté.

Les transformations sont dérivées, jetables et reproductibles : le cache peut être vidé à tout instant, la requête suivante le reconstruit. Les administrateurs peuvent le faire précisément avec DELETE /api/admin/storage/transform-cache.

Les types d'image reconnus sont ceux que Sovrium peut déduire de l'extension de la clé : PNG, JPEG, GIF, WebP, AVIF, SVG et ICO. Le SVG est transmis tel quel plutôt que rasterisé, et il est toujours servi en pièce jointe — voir Sécurité des téléversements.

Pages associées

• Redimensionnement et recadrage — les paramètres qu'un preset regroupe.
• Format et qualité — négociation de format et compression.
• Opérations sur les fichiers — le point de terminaison qui sert les résultats en cache.
• Cycle de vie et quotas — les originaux dont une transformation part.
• Variables d'environnement : services — la configuration des presets et du cache.