Skip to main content
View as Markdown

Opérations sur les fichiers

Chaque bucket expose une API REST pour le cycle de vie principal des fichiers : téléversement, téléchargement et suppression. Les opérations sont authentifiées par rapport aux permissions du bucket, durcies contre la traversée de chemin et le XSS, et intégrées au modèle de soft-delete de Sovrium.

Le paramètre de chemin {bucket} référence un nom de bucket déclaré dans votre tableau buckets[]. Voir Présentation des buckets.

Points de terminaison

Méthode Point de terminaison Description
POST /api/buckets/{bucket}/files Téléverse un fichier (données de formulaire multipart). Renvoie 201 avec la clé de fichier générée.
GET /api/buckets/{bucket}/files/{key} Télécharge un fichier par clé. Renvoie le contenu du fichier avec le bon Content-Type.
DELETE /api/buckets/{bucket}/files/{key} Supprime un fichier par clé du stockage.
GET /api/admin/buckets/quota (Admin) Renvoie l'utilisation actuelle du stockage en octets.

Téléversement

Envoyez le fichier sous forme de données de formulaire multipart. Le serveur le valide par rapport aux maxFileSize et allowedMimeTypes du bucket, génère une clé imprévisible, et le stocke dans le backend configuré.

curl -X POST https://app.example.com/api/buckets/documents/files \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@report.pdf"
{
  "key": "documents/9f3c1e2a-7b44-4d10-9e21-8a6f0c1d2e3b.pdf",
  "filename": "report.pdf",
  "size": 245760,
  "mimeType": "application/pdf"
}
Comportement Résultat
Fichier valide dans les limites 201 avec la clé de fichier générée.
Corps de requête vide 400 Bad Request.
Dépasse la taille max du bucket ou globale 413 Payload Too Large (rejeté tôt, avant la lecture complète du corps).
Dépasse le quota STORAGE_MAX_TOTAL_SIZE 507 Insufficient Storage.
Requête non authentifiée vers un bucket authentifié 401 Unauthorized.

Téléchargement

curl https://app.example.com/api/buckets/documents/files/{key} \
  -H "Authorization: Bearer $TOKEN" -O
Comportement Résultat
Le fichier existe, l'appelant a la permission download 200 avec le contenu du fichier et le bon Content-Type.
Clé inexistante 404 Not Found.
Fichier privé, pas d'auth et pas d'URL signée 403 Forbidden.

Les réponses incluent un en-tête Content-Disposition — les fichiers non image sont servis en attachment pour empêcher le navigateur de les afficher en ligne.

Suppression

curl -X DELETE https://app.example.com/api/buckets/documents/files/{key} \
  -H "Authorization: Bearer $TOKEN"
Comportement Résultat
Le fichier existe, l'appelant a la permission delete 200, fichier retiré du stockage.
Clé inexistante 404 Not Found.

Durcissement de sécurité

Les opérations sur les fichiers appliquent automatiquement la base de sécurité de pré-lancement récurrente pour les téléversements :

Mesure Comportement
Traversée de chemin Les séquences ../ dans les noms de fichiers sont assainies ou rejetées.
Octets nuls Les noms de fichiers contenant des octets nuls sont rejetés.
Caractères spéciaux / unicode Encodés en toute sécurité pour le stockage.
Clés aléatoires Les clés basées sur UUID empêchent les URL devinables.
X-Content-Type-Options: nosniff Envoyé sur chaque fichier servi.
Content-Security-Policy Envoyé sur chaque fichier servi.
Types sujets au XSS (HTML, SVG) Servis avec un Content-Type sûr ou forcés au téléchargement en pièce jointe.

Cycle de vie des fichiers

Les pièces jointes suivent le cycle de vie soft-delete-par-défaut de Sovrium. La présence du fichier suit l'enregistrement propriétaire :

Action sur l'enregistrement Comportement du fichier
Soft-delete de l'enregistrement Fichier préservé dans le stockage.
Restauration de l'enregistrement Accès au fichier restauré.
Hard-delete (purge) Fichier retiré du stockage.
Remplacement de la pièce jointe Ancien fichier retiré du stockage.
Effacement de la pièce jointe (mettre null) Fichier retiré du stockage.
Référence partagée Fichier préservé tant qu'un autre enregistrement le référence.

Téléversements volumineux et quota

Les téléversements diffusent en flux plutôt que de tamponner en bloc, donc les gros fichiers ne font pas grimper la mémoire. Les limites sont contrôlées par l'opérateur via des variables d'environnement.

Variable Par défaut Objectif
STORAGE_MAX_FILE_SIZE 104857600 (100 Mo) Taille maximale d'un fichier unique en octets. Le maxFileSize d'un bucket surcharge ceci par bucket.
STORAGE_MAX_TOTAL_SIZE Illimité Stockage total maximal par application en octets (sécurité multi-locataire). 
STORAGE_MAX_FILE_SIZE=52428800
STORAGE_MAX_TOTAL_SIZE=10737418240

Le point de terminaison de quota admin rapporte l'utilisation :

curl https://app.example.com/api/admin/buckets/quota \
  -H "Authorization: Bearer $ADMIN_TOKEN"
{ "usedBytes": 524288000, "maxBytes": 10737418240 }

La suppression de fichiers réduit l'utilisation suivie. Lorsqu'aucun STORAGE_MAX_TOTAL_SIZE n'est configuré, les téléversements sont illimités.

Pages associées