ADR-020 : Périmètre de `forge-mvc-files` : primitives de stockage média génériques¶

Statut¶

Acceptée, Forge 1.0.0-beta.x. Primitives de stockage livrées dans forge-mvc-files.

Décision de direction (option B ci-dessous). L'ADR fixe le périmètre cible
de forge-mvc-files ; l'exécution est progressive et non urgente (les
opt-ins déjà livrés ne sont pas refondus avant la 1.0).

Date¶

2026-06-05

Contexte¶

Depuis ADR-019, forge-mvc-files détient le pipeline d'upload générique
extrait du core : écriture disque anti-traversal, save_upload/SavedUpload,
service de fichiers serve_media_file (HTTP Range), suppression, rate-limit.
La validation pure (extension/MIME/taille, UploadError) reste dans le core
(core.forms.upload_validation), réexportée par files, le core ne peut pas
dépendre d'un opt-in (ADR-004).

forge-mvc-files est présenté comme l'upload générique de Forge. Mais l'audit
des dépendances révèle qu'il n'est pas la fondation commune annoncée :

Module	S'appuie sur `forge-mvc-files` ?	Modèle de stockage
`forge-mvc-images`	Oui (dépendance déclarée + imports réels)	nom assaini + variantes (même forme que le « document » de files)
`forge-mvc-video`	Non (0 dépendance, 0 import)	propre storage UUID, multi-rendition (`originals/mp4/posters`), transcodage
`forge-mvc-audio`	Non (0 dépendance, 0 import)	propre storage UUID, transcodage

Il existe donc deux approches de stockage parallèles dans Forge :

le pipeline générique core→files (utilisé par images) ;
des stockages dédiés UUID (video, audio), indépendants.

Pourquoi cette divergence ? Elle est principielle, pas accidentelle :

video/audio adoptent un chemin 100% UUID (le nom utilisateur n'apparaît
jamais, anti-traversal par construction), plus strict que le modèle
« nom assaini conservé » de save_upload ;
ils produisent plusieurs fichiers dérivés par upload (source + MP4/MP3 +
poster), dans un sous-arbre dédié ;
ils ont un cycle de vie (transcodage ffmpeg, états uploaded→processing→ready)
hors périmètre de files.

À noter : le service HTTP Range est déjà mutualisé dans le core
(Response.file), files et le http.py de video y délèguent tous deux. La
duplication réelle n'est donc pas dans le service, mais dans l'écriture sûre
et les helpers anti-traversal, ré-implémentés côté video/audio.

Le résultat : la promesse « files = socle média générique » n'est tenue qu'à
moitié, et chaque nouvel opt-in média risque de re-diverger (tension avec le
principe 11, « une seule façon officielle »).

Décision¶

Option B, forge-mvc-files devient une boîte à primitives de stockage média
génériques sur laquelle tout opt-in média (image, video, audio, futurs)
compose sa propre disposition.

files reste un opt-in, hors du core (confirmation d'ADR-019/ADR-004 :
le core n'a pas à traiter de fichiers).
files expose des primitives composables, pas un pipeline imposé :
- écriture disque sûre, y compris un mode UUID (nom utilisateur absent du
chemin) en plus du mode « nom assaini » actuel ;
- helpers anti-traversal / chemin (secure_filename, is_safe_media_path,
normalize_media_path, save_bytes) ;
- un appui pour les dispositions multi-rendition (un média = plusieurs
fichiers dérivés sous une racine) ;
- service Range (mince enveloppe sur la primitive core), rate-limit, suppression.
save_upload reste la convenance « document » bâtie sur ces primitives,
c'est elle qu'images réutilise pour le chemin document. Elle n'est plus
présentée comme « la » façon de stocker un média, mais comme une façade.
Règle pérenne : tout nouvel opt-in média s'appuie sur les primitives
de files (et on vérifie que files expose ce dont il a besoin).
L'API des primitives est conçue contre les 3 clients réels (image, video,
audio) déjà existants, on extrait la forme commune observée, on n'invente pas
une abstraction spéculative.

Hors périmètre¶

Pas de big-bang : video et audio (déjà livrés, video publié) ne sont pas
refondus en urgence. Leur repointage sur les primitives de files est
opportuniste et post-1.0.
files ne devient pas un framework configurable à options (anti principe 8) :
des primitives, pas une usine.
files n'absorbe pas la validation de domaine (codecs/ffprobe), le
transcodage, ni aucun état/BDD, cela reste propriété des opt-ins métier.
On ne force pas video/audio sur le modèle « nom assaini » : ce serait un
recul de sécurité par rapport à leur chemin UUID.

Conséquences¶

Positives¶

Sécurité à un seul endroit : l'écriture sûre / anti-traversal écrite,
auditée et corrigée une fois, partagée par tous les médias.
Clarté conceptuelle : « files = la fondation média » devient vrai, pas un
slogan à moitié tenu.
Extensibilité : un nouvel opt-in média assemble au lieu de réinventer.
Cohérence (principe 11) : une seule façon officielle de stocker/servir un
fichier en bas niveau.

Coûts / ruptures¶

L'API de files grandit (mode UUID, appui multi-rendition), à garder
minimale et justifiée par les 3 clients réels.
video et audio gagneront (à terme) une dépendance sur files qu'ils n'ont
pas aujourd'hui.
Effort de repointage sur du code livré/publié (video b13) → assumé
progressif, post-1.0.
Gain de dé-duplication modéré : le service Range est déjà core ; l'essentiel
partagé est l'écriture sûre + helpers. La valeur est cohérence + sécurité +
extensibilité, pas un dégraissage massif.
Risque : sur-généraliser files en framework. Garde-fou : revue stricte au
regard du principe 8 à chaque ajout de primitive.

Plan d'exécution (tickets)¶

Cet ADR, fixe la direction (option B).
FILES-PRIMITIVES-*, exposer proprement le mode UUID + l'appui
multi-rendition, validés contre la forme de image/video/audio, sans
modifier encore aucun consommateur.
Repointage opportuniste de video puis audio sur les primitives de files
(post-1.0, tickets dédiés, suite verte à chaque étape).
Règle de contribution : documenter que tout nouvel opt-in média s'appuie
sur files (à refléter dans docs/philosophy/module-author-guide.md et la
page médias).

Alternatives écartées¶

(A) Statu quo, files = pipeline document unique. Laisse video/audio
divergents et la promesse « socle générique » à moitié fausse ; la dérive se
répète au prochain opt-in média. Écarté.
Forcer video/audio à utiliser save_upload. Les mettrait sur le modèle
« nom assaini conservé », un recul de sécurité vs leur chemin UUID par
construction. Écarté.
Réintégrer un stockage commun dans le core. Contredit ADR-004 et le
principe 8 (le core n'a pas à traiter de fichiers). Écarté.
Tout laisser tel quel et l'assumer. Deux stockages parallèles non
documentés = dette implicite ; au minimum la frontière doit être actée, ce que
fait cet ADR. Écarté au profit de la convergence dirigée par B.

Références¶

ADR-004, Périmètre du core minimal strict (le core ne dépend pas d'un opt-in).
ADR-018, Extraction du traitement d'image (forge-mvc-images).
ADR-019, Extraction de l'upload générique (forge-mvc-files).
Charte v2, principe 8 (noyau minimal, briques opt-in) et principe 11 (une
seule façon officielle de faire chaque chose).

ADR-020 : Périmètre de forge-mvc-files : primitives de stockage média génériques¶