Aller au contenu
Logo Aurabase
aurabase

Storage

API REST par projet sur un stockage S3 (SeaweedFS S3), transformations d’image à la volée avec cache des dérivés, URLs signées HMAC, buckets publics ou privés, corbeille et restauration.

Explication6 min de lectureNiveau intermédiaireRévisé le 15 avr. 2026

Un bucket, une origine, un CDN#

Le service aura-storage gère vos fichiers binaires : upload, download, transformations d'image, URLs signées, corbeille. Il expose sa propre API REST sous /v1/storage/{project_id} et s'appuie sur un stockage S3 (SeaweedFS S3) en interne — les outils S3 (rclone, boto3) ne s'y connectent pas directement.

Les objets sont organisés en buckets. Chaque bucket a une politique (public ou privé), des limites de taille, un TTL optionnel, et un ensemble de policies RLS qui contrôlent qui peut lire/écrire chaque chemin.

Informations

Les métadonnées vivent dans le schéma du projet : storage_buckets, storage_objects, storage_derivatives, storage_project_settings, storage_audit_log. Les octets, eux, sont dans le stockage S3.

Chemin → RLS → CDN → origine#

Lors d'une lecture, le service vérifie l'accès au chemin demandé, puis sert les octets depuis le stockage. Si la requête porte des paramètres de transformation, le dérivé correspondant est réutilisé s'il existe déjà, sinon calculé puis mis en cache. En upload, le flux est inversé : client → service → stockage, après contrôle d'écriture et des limites du bucket.

schematext
                              ┌──── derivative cache ────┐
   GET /v1/storage/{pid}/… ─▶ │ derivative cached?       │
                              │ no  ⇢ origin             │
                              └──────────┬───────────────┘
                                         │
                              ┌──────────▼───────────────┐
                              │ aura-storage             │
                              │  ─ access control        │
                              │  ─ transforms            │
                              │  ─ derivative cache      │
                              └──────────┬───────────────┘
                                         │
                                  S3 storage (SeaweedFS S3)

Six capacités natives#

  • API REST par projet. Routes /v1/storage/{project_id}/… sur un stockage S3 (SeaweedFS S3) — ce n'est pas une API S3 : les SDK S3 ne s'y branchent pas.
  • Transforms à la volée. width, height, fit, format (jpeg/png/webp/gif), quality, rotate, flip. Chaque combinaison est cachée comme dérivé.
  • URLs signées. Signature HMAC sur méthode + bucket + clé + expiration. TTL 3600 s par défaut, rotation du secret par projet.
  • Upload multipart. Upload simple en multipart/form-data, ou init / part / complete pour les gros fichiers.
  • Corbeille et restauration. Suppression réversible : /trash liste les objets supprimés, /restore/{key} les rétablit.
  • Buckets publics ou privés. Le bucket porte la politique d'accès, les limites de taille et la liste des types MIME autorisés.

Quatre opérations de base#

avatar.tstypescript
const { data, error } = await aura.storage.upload('avatars', `${user.id}/${file.name}`, file, {
    contentType: file.type,
    upsert: true,
})

// Sans upsert, un chemin déjà occupé échoue en 409 (code CONFLICT)
Astuce

Les URLs de transformation sont immuables par paramètres. ?width=240&format=png et ?width=240&format=webp sont deux URLs distinctes, donc deux dérivés distincts : chaque combinaison n'est calculée qu'une fois, puis relue depuis le cache de dérivés.

RLS sur les paths d’objets#

Les métadonnées d'objets vivent dans la table storage_objects du schéma du projet (colonnes bucket_name, key, owner_id, metadata, deleted_at), avec RLS activée. Il n'existe pas de schéma storage ni de fonction storage.foldername() : les policies s'écrivent sur les colonnes.

policies livrées par défautsql
-- Lecture : son propre objet, ou n'importe quel objet d'un bucket public
create policy storage_objects_select on storage_objects for select
  using (
    owner_id = auth.uid()
    or exists (select 1 from storage_buckets b
                  where b.name = storage_objects.bucket_name and b.public)
  );

-- Écriture : uniquement ses propres objets
create policy storage_objects_insert on storage_objects for insert
  with check (owner_id = auth.uid());

Pour aller plus loin#