Armazenamento
API REST por projeto em armazenamento S3 (SeaweedFS S3), transformações de imagem dinâmicas com cache derivado, URLs assinados HMAC, buckets públicos ou privados, lixo e restauração.
Um bucket, uma origem, um CDN#
O aura-storage service gerencia seus arquivos binários: upload, download, transformações de imagem, URLs assinados, lixo. Ele expõe o seu próprio API REST sob /v1/storage/{project_id} e depende do armazenamento S3 (SeaweedFS S3) internamente - as ferramentas S3 (rclone, boto3) não se conectam a ele diretamente.
Os objetos são organizados em buckets. Cada bucket tem uma política (pública ou privada), limites de tamanho, um TTL opcional e um conjunto de políticas RLS que controlam quem pode ler/gravar cada caminho.
Os metadados residem no esquema do projeto: storage_buckets, storage_objects, storage_derivatives, storage_project_settings, storage_audit_log. Os bytes estão no armazenamento S3.
Caminho → RLS → CDN → origem#
Durante uma leitura, o serviço verifica o acesso ao caminho solicitado e, em seguida, fornece os bytes do armazenamento. Se a consulta transportar parâmetros de transformação, a derivada correspondente será reutilizada se já existir; caso contrário, será calculada e armazenada em cache. No upload, o fluxo é invertido: cliente → serviço → armazenamento, após escrever o controle e os limites do bucket.
┌──── derivative cache ────┐
GET /v1/storage/{pid}/… ─▶ │ derivative cached? │
│ no ⇢ origin │
└──────────┬───────────────┘
│
┌──────────▼───────────────┐
│ aura-storage │
│ ─ access control │
│ ─ transforms │
│ ─ derivative cache │
└──────────┬───────────────┘
│
S3 storage (SeaweedFS S3)
Seis habilidades nativas#
- API REST por projeto. Rotas /v1/storage/{project_id}/… no armazenamento S3 (SeaweedFS S3) — esta não é uma API S3: SDKs S3 não se conectam a ela.
- Transforma-se instantaneamente. largura, altura, ajuste, formato (jpeg/png/webp/gif), qualidade, girar, inverter. Cada combinação é armazenada em cache como uma derivada.
- URLs assinados. HMAC assinatura no método + bucket + chave + expiração. TTL 3600 s por padrão, rotação secreta por projeto.
- Multipart upload. Upload simples em multipart/form-data ou init/part/complete para arquivos grandes.
- Lixo e restauração. Exclusão suave: /trash lista objetos excluídos, /restore/{key} os restaura.
- Buckets públicos ou privados. O bucket contém a política de acesso, limites de tamanho e a lista de tipos MIME autorizados.
Quatro operações básicas#
const { data, error } = await aura.storage.upload('avatars', `${user.id}/${file.name}`, file, {
contentType: file.type,
upsert: true,
})
// Sem upsert, um caminho já ocupado falha em 409 (código CONFLICT)
URLs de transformação são imutáveis por parâmetros. ?width=240&format=png e ?width=240&format=webp são duas URLs distintas, portanto, duas derivadas distintas: cada combinação é calculada apenas uma vez e depois relida no cache de derivadas.
RLS em caminhos de objetos#
Os metadados do objeto residem na tabela storage_objects do esquema do projeto (colunas bucket_name, key, owner_id, metadata, deleted_at), com RLS ativado. Não há esquema storage nem função storage.foldername(): as políticas são escritas nas colunas.
-- Leitura: objeto próprio ou qualquer objeto de um bucket público
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)
);
-- Escrita: apenas seus próprios objetos
create policy storage_objects_insert on storage_objects for insert
with check (owner_id = auth.uid());