Stoccaggio
API REST per progetto su storage S3 (SeaweedFS S3), trasformazioni di immagini al volo con cache derivata, URL firmati HMAC, bucket pubblici o privati, cestino e ripristino.
Un bucket, un'origine, un CDN#
Il servizio aura-storage gestisce i tuoi file binari: caricamento, download, trasformazioni di immagini, URL firmati, cestino. Espone la propria API REST sotto /v1/storage/{project_id} e si basa sullo storage S3 (SeaweedFS S3) internamente: gli strumenti S3 (rclone, boto3) non si connettono direttamente ad esso.
Gli oggetti sono organizzati in bucket. Ogni bucket ha una policy (pubblica o privata), limiti di dimensione, un TTL opzionale e un set di policy RLS che controllano chi può leggere/scrivere ciascun percorso.
I metadati risiedono nello schema del progetto: storage_buckets, storage_objects, storage_derivatives, storage_project_settings, storage_audit_log. I byte sono nella memoria S3.
Percorso → RLS → CDN → origine#
Durante una lettura, il servizio verifica l'accesso al percorso richiesto e quindi serve i byte dall'archivio. Se la query contiene parametri di trasformazione, la derivata corrispondente viene riutilizzata se esiste già, altrimenti calcolata e quindi memorizzata nella cache. In caricamento il flusso è invertito: client → servizio → storage, dopo aver scritto i limiti di controllo e bucket.
┌──── derivative cache ────┐
GET /v1/storage/{pid}/… ─▶ │ derivative cached? │
│ no ⇢ origin │
└──────────┬───────────────┘
│
┌──────────▼───────────────┐
│ aura-storage │
│ ─ access control │
│ ─ transforms │
│ ─ derivative cache │
└──────────┬───────────────┘
│
S3 storage (SeaweedFS S3)
Sei abilità native#
- API REST per progetto. Routes /v1/storage/{project_id}/… sullo storage S3 (SeaweedFS S3) — questa non è un'API S3: gli SDK S3 non si collegano ad essa.
- Si trasforma al volo. larghezza, altezza, adattamento, formato (jpeg/png/webp/gif), qualità, rotazione, capovolgimento. Ogni combinazione viene memorizzata nella cache come derivata.
- URL firmati. HMAC firma sul metodo + bucket + chiave + scadenza. TTL 3600 s per impostazione predefinita, rotazione segreta per progetto.
- Caricamento in più parti. Caricamento semplice in multipart/form-data o init/part/complete per file di grandi dimensioni.
- Cestino e ripristino. Eliminazione temporanea: /trash elenca gli oggetti eliminati, /restore/{key} li ripristina.
- Bucket pubblici o privati. Il bucket contiene la policy di accesso, i limiti di dimensione e l'elenco dei tipi MIME autorizzati.
Quattro operazioni fondamentali#
const { data, error } = await aura.storage.upload('avatars', `${user.id}/${file.name}`, file, {
contentType: file.type,
upsert: true,
})
// Senza upsert, un percorso già occupato fallisce in 409 (codice CONFLICT)
Gli URL di trasformazione sono immutabili in base ai parametri. ?width=240&format=png e ?width=240&format=webp sono due URL distinti, quindi due derivate distinte: ogni combinazione viene calcolata una sola volta, quindi riletta dalla cache delle derivate.
RLS sui percorsi degli oggetti#
I metadati dell'oggetto si trovano nella tabella storage_objects dello schema del progetto (colonne bucket_name, key, owner_id, metadata, deleted_at), con RLS abilitato. Non esiste uno schema storage né una funzione storage.foldername(): le policy sono scritte sulle colonne.
-- Leggi: oggetto proprio o qualsiasi oggetto da un bucket pubblico
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)
);
-- Scrittura: solo i tuoi oggetti
create policy storage_objects_insert on storage_objects for insert
with check (owner_id = auth.uid());