Passo a passo de um serviço de upload de arquivos: tickets de envio direto ao storage, varredura assíncrona e cotas

Objetivo

Permitir que os clientes enviem arquivos diretamente para o object storage, manter os servidores de aplicação fora do caminho dos bytes e só admitir um arquivo no produto depois de ele ter sido verificado e contabilizado na cota.

Pré-requisitos

Um object storage que emita URLs de upload assinadas e com prazo de validade, um scanner que rode como job, uma cota por proprietário e as regras de validação já existentes para tipos e nomes.

Passos

1. Restrições: os servidores de aplicação nunca fazem proxy dos bytes; um arquivo fica invisível até ser verificado; uploads abandonados não podem reter cota nem armazenamento para sempre.
2. Componentes: uma API de upload que emite tickets; um bucket com os prefixos incoming/ e ready/ (ou dois buckets); um endpoint de conclusão ou um consumidor de eventos do storage; um worker de varredura; um ledger de cotas; e um caminho de entrega com URLs de download assinadas de curta duração.
3. Fluxo: o cliente solicita um ticket informando o tamanho e o tipo declarados; a API verifica a cota, reserva o tamanho declarado, registra o ticket e devolve uma URL PUT assinada para uma única chave de objeto, com expiração de poucos minutos. A documentação do S3 descreve as URLs pré-assinadas como limitadas pelas permissões da identidade que as criou, portanto a identidade que assina deve poder escrever apenas em incoming/. Depois do envio, o cliente chama o endpoint de conclusão (complete); o serviço lê o tamanho e o tipo reais no storage, rejeita divergências e enfileira uma varredura. O worker move o objeto para ready/ ou o apaga, e registra o motivo.
4. Modelo de dados: upload(id, owner, status: ticketed|uploaded|scanning|ready|rejected|expired, declared_bytes, actual_bytes, content_type, storage_key, ticket_expires_at, created_at); quota(owner, limit_bytes, used_bytes, reserved_bytes), atualizada na mesma transação de cada mudança de status.
5. Modos de falha: tickets nunca concluídos (um job de expiração libera a reserva; uma regra de ciclo de vida apaga objetos antigos em incoming/, e o S3 documenta a ação de ciclo de vida AbortIncompleteMultipartUpload para uploads multipart não finalizados); dois uploads disputando e ultrapassando a cota (reservar com lock de linha); fila de varredura acumulada deixando arquivos em scanning (mostrar o status e alertar sobre a idade da fila); arquivo compartilhado antes de a varredura terminar (servir apenas a partir de ready/); objeto armazenado cuja chamada de conclusão se perdeu (aceitar uma conclusão tardia e reconciliar com as listagens do storage).
6. Medir: tempo entre o ticket e o estado ready, proporção de tickets expirados, idade da fila de varredura, motivos de rejeição, requisições negadas por cota e objetos órfãos encontrados pela reconciliação.
7. Não são prioridade: multipart retomável para arquivos pequenos, derivados de imagem, deduplicação por hash, criptografia no lado do cliente e pastas.

Resultado esperado

Os bytes fluem do cliente para o storage; o serviço lida apenas com metadados, e cada objeto armazenado corresponde a uma linha cujo status explica por que ele existe.

Limites e base de verificação

Design proposto, sem medições. A validação de nomes e tipos é tratada no artigo existente sobre upload. Se um PUT assinado consegue limitar o tamanho do objeto depende do produto de storage, e é por isso que o tamanho é verificado após o upload.