Arquivos

Envie, organize e recupere arquivos da organização.

Cada arquivo no Siglata pertence a uma organização. Os arquivos permanecem na organização quando seus membros mudam. A arquitetura de armazenamento incorpora pré-reservas de upload, particionamento fixo em partes de 8 MiB, operações atômicas de metadados e um ciclo de vida automatizado de recuperação na lixeira por 30 dias.

Arquitetura da Cota de Armazenamento

Cada organização inicia com uma cota de armazenamento base de 10 GiB (10.737.418.240 bytes).

O Siglata monitora o armazenamento por meio de um livro-razão transacional atômico que distingue entre dados retidos e capacidade pré-alocada de upload:

┌────────────────────────────────────────────────────────────────────────┐
│                   Cota Total da Organização (10 GiB)                   │
├──────────────────────────────────────┬──────────────────┬──────────────┤
│             Bytes Usados             │ Bytes Reservados │    Espaço    │
│  (Arquivos Ativos + Lixeira 30 Dias) │(Uploads Ativos)  │ Livre Dispon.│
└──────────────────────────────────────┴──────────────────┴──────────────┘

• limitBytes: Capacidade total de armazenamento alocada para a organização (10.737.418.240 bytes).
• usedBytes: Armazenamento retido, somando tanto arquivos ativos quanto arquivos na lixeira. Mover um item para a lixeira não libera a cota imediatamente; os bytes permanecem contabilizados até que o período de recuperação de 30 dias expire e a limpeza purgue os dados.
• reservedBytes: Armazenamento bloqueado por uploads em partes em andamento. Ao iniciar um upload, o Siglata pré-aloca o tamanho total declarado do arquivo para evitar que uploads concorrentes colidam ou ultrapassem os limites da organização.
• Espaço Disponível: Calculado em tempo real como limitBytes - usedBytes - reservedBytes.

Particionamento em Partes e Reservas de Upload

Para suportar arquivos volumosos com alta confiabilidade de transferência mesmo em conexões instáveis, o Siglata utiliza um pipeline com blocos fixos de 8 MiB:

O Ciclo de Vida do Upload

1. upload_begin ──> Checa Cota ──> Pré-aloca reservedBytes ──> Retorna ID e URL do Upload
        │
        ▼
2. PUT /parts/{n} ──> Envia Blocos de 8 MiB (Paralelo ou Sequencial) ──> Registra receivedParts
        │
        ▼
3. upload_complete ──> Valida Contagem ──> Converte reservedBytes em usedBytes ──> Arquivo Ativo
        │
        └── (Se Abortado) ──> upload_cancel ──> Exclui Blocos ──> Libera reservedBytes

1. Reserva de Upload (upload_begin):

   • O cliente fornece um requestId exclusivo (UUID), name, mediaType e size.
   • O Siglata valida se size <= (limitBytes - usedBytes - reservedBytes).
   • Os bytes declarados são adicionados atomicamente a reservedBytes, e uma sessão de upload é criada com prazo de expiração.
   • O servidor retorna o identificador do upload e as instruções de transferência com o modelo de URL HTTP PUT.

2. Transmissão das Partes (PUT /v1/mcp/uploads/{uploadId}/parts/{partNumber}):

   • O cliente envia partes numeradas sequencialmente de 1 a N (até 10.000).
   • Cada parte deve ter exatamente 8.388.608 bytes, com exceção da parte final, que envia os bytes restantes declarados.
   • As partes podem ser enviadas em paralelo. O servidor valida o tamanho de cada bloco e registra a chegada no manifesto do upload.

3. Finalização e Ativação (upload_complete):

   • Quando todas as partes forem recebidas, o cliente invoca upload_complete.
   • O servidor confirma que todas as partes de 1 a N foram registradas e que o tamanho total coincide com a reserva.
   • O registro do upload transiciona para completed, o arquivo é marcado como active e a capacidade reservada é transferida de reservedBytes para usedBytes.
   • Essa operação é totalmente idempotente: repetir upload_complete com o mesmo ID retorna o arquivo ativo com segurança.

4. Cancelamento e Expiração (upload_cancel):

   • Se o upload for cancelado pelo usuário ou cliente, upload_cancel aciona a exclusão dos blocos armazenados e libera imediatamente os reservedBytes.
   • Se o cliente desconectar inesperadamente, o reconciliador em segundo plano detecta sessões de upload expiradas, cancela a reserva e limpa os blocos órfãos.

Ciclo de Vida de 30 Dias na Lixeira e Recuperação

O Siglata adota um modelo de retenção com foco na segurança dos dados para proteger equipes contra exclusões acidentais:

Mover para a Lixeira (file_trash)

Quando um membro exclui um arquivo ativo:

• O estado do arquivo transiciona de active para trash.
• A data e hora da exclusão são registradas (trashed_at = clock_timestamp()).
• O prazo limite de recuperação é estabelecido para exatamente 30 dias no futuro:

  recover_until = clock_timestamp() + interval '30 days'

• O arquivo deixa de aparecer na listagem padrão, mas passa a ser exibido na lixeira (files_list com state: "trash").
• Contabilização na Cota: Os bytes do arquivo continuam sendo cobrados do usedBytes da organização. Isso assegura que os dados permaneçam preservados e que a restauração futura nunca falhe por esgotamento de cota.

Restaurar Arquivos (file_restore)

Caso um arquivo tenha sido excluído por engano:

• Qualquer membro com permissão files:write pode chamar file_restore a qualquer momento antes de recover_until.
• O arquivo retorna atomicamente ao status active, limpando trashed_at e recover_until.
• Como os bytes do arquivo já estavam contabilizados em usedBytes durante a permanência na lixeira, a restauração não consome cota adicional.

Limpeza Permanente Automatizada

• Após o encerramento do prazo de 30 dias (recover_until <= clock_timestamp()), a restauração é desabilitada permanentemente.
• O reconciliador em segundo plano do Siglata busca os itens expirados na lixeira em lotes:

  SELECT id FROM files_object
  WHERE state = 'trash' AND recover_until <= clock_timestamp()

• O processo marca o objeto para purga, remove os dados binários do armazenamento e limpa o registro correspondente no banco de dados.
• Somente após a confirmação da exclusão física os bytes são subtraídos do usedBytes da organização, liberando espaço para novos envios.

Operações de Metadados

Renomear Arquivo (file_rename)

A renomeação de um arquivo no Siglata altera apenas o atributo name no registro do banco de dados. Como os objetos são endereçados por UUIDs imutáveis, a renomeação é uma operação instantânea de custo zero, sem cópia de dados ou recálculo de cota.

Downloads Autenticados em Fluxo (file_download)

Membros autorizados podem baixar arquivos diretamente pelo endpoint de download autenticado (GET /v1/mcp/files/{fileId}/download). O endpoint valida a associação ativa do chamador na organização em tempo real antes de iniciar o fluxo de bytes, garantindo que ex-membros não acessem os ativos da organização.

Pastas e Controle de Acesso

Arquivos podem residir em pastas aninhadas, e cada arquivo e pasta carrega um atributo visibility:

• org (padrão): Todo membro da organização pode ler e gravar o objeto, sujeito aos seus escopos OAuth. Isso preserva o comportamento de todos os arquivos criados antes da existência de pastas.
• restricted: Somente o criador do objeto, membros owner/admin da organização e membros com concessão explícita podem acessar o objeto.

Uma pasta restrita restringe toda a sua subárvore: para ler ou gravar um objeto, o chamador precisa satisfazer cada pasta restrita na cadeia de ancestrais. Uma concessão em uma pasta se estende aos seus descendentes irrestritos, enquanto um objeto restrito dentro de uma pasta compartilhada ainda exige sua própria concessão.

• Operações negadas falham com o código de erro forbidden; objetos restritos que um membro não pode ler também são omitidos dos resultados de files_list e folders_list.
• grant_create e grant_revoke são limitados ao criador do objeto e a administradores da organização. Para alterar o nível ou o beneficiário de uma concessão, revogue e depois crie (não há operação de substituição separada).
• file_set_visibility e folder_set_visibility exigem acesso de escrita ao objeto; não alteram concessões existentes.
• file_move e upload_begin em uma pasta requerem acesso de escrita à pasta de destino.
• Mover uma pasta para a lixeira não move seu conteúdo; quando uma pasta na lixeira ultrapassa o prazo de recuperação, ela é excluída e seus filhos voltam para a raiz da organização.