Logo

Apêndice: Estruturas de dados mínimas (manifest/chunk/estado)

Este apêndice apresenta recomendações mínimas de estruturas de dados para “fragmentação paralela + transferência retomável + novas tentativas idempotentes”. O objetivo é permitir concorrência de alta vazão e recuperação confiável após falhas, sem transações complexas.

Princípios gerais

  • Objetos grandes versus estado pequeno: os chunks e o manifest são objetos grandes armazenados no armazenamento de objetos; o estado é pequeno e fica em um armazenamento de estado.
  • Chaves únicas e idempotência: um chunk DEVE ser endereçável de forma única por (transferId, fileId, chunkIndex), para permitir retransmissões idempotentes.
  • Recuperabilidade: o estado DEVE expressar o “conjunto concluído”, para que a recuperação possa pular as partes já concluídas.
  • Sem vazamento de dados sensíveis: as chaves de objeto e o estado DEVERIAM evitar embutir campos sensíveis, como e-mail ou nomes de arquivo originais (se esses campos são criptografados depende da sua política de privacidade).

A.1 Campos mínimos do manifest

O manifest é o “ponto de entrada único” do receptor para o download e a remontagem. Recomendações mínimas:

  • manifestVersion: DEVE. Usado em atualizações de compatibilidade (por exemplo, 1).
  • transferId: DEVE. Identificador único da sessão de transferência.
  • createdAt / expiresAt: DEVERIA. Para o tratamento do ciclo de vida e dicas na interface.
  • policy: DEVERIA. Um resumo da política (limites de contagem de downloads, exigência de senha, se é permitido compartilhar antes da conclusão etc.).
  • files[]: DEVE. Descrição da lista de arquivos (no mínimo os tamanhos dos arquivos e os intervalos de chunks).
  • chunking: DEVE. Inclui o chunkSize e como o chunkCount é calculado, ou o chunkCount de cada arquivo.
  • objectKeyRule: DEVE. Derivar as chaves de objeto a partir de (transferId, fileId, chunkIndex) ou fornecer uma tabela de mapeamento explícita.

A.1.1 Campos mínimos de files[]

  • fileId: DEVE. Identificador único do arquivo (não use o nome do arquivo como chave única).
  • size: DEVE. Tamanho em bytes.
  • mime: PODE. Para exibição e sugestões de download.
  • name: PODE. Se você quiser conhecimento zero estrito / vazamento mínimo, omita name ou armazene um nome criptografado.
  • chunkCount: DEVE. Quantidade de chunks deste arquivo.
  • chunkOffset: PODE. Se vários arquivos compartilham um chunkIndex global, é necessário um deslocamento; caso contrário, pode ser omitido.

A.1.2 Campos de integridade e verificação (opcionais, mas recomendados)

  • chunkHashes[]: DEVERIA. Verificação por chunk (um ou uma combinação de hash/tamanho/etag).
  • fileHash: PODE. Checksum do arquivo inteiro (verificar após o download).
  • ciphertextLength: PODE. Verificações de consistência de tamanho no nível do texto cifrado (sem precisar do texto simples).

A.2 Objetos de chunk: restrições mínimas

  • Endereçamento único: um chunk DEVE ser endereçável de forma única por (transferId, fileId, chunkIndex).
  • Upload idempotente: reenviar o mesmo chunk NÃO DEVE corromper o estado final (ele pode sobrescrever ou ser rejeitado, mas o comportamento deve ser consistente).
  • Metadados mínimos: o servidor PODE registrar apenas o tamanho do texto cifrado, o horário de gravação, o etag/versão etc., para observabilidade e diagnóstico de problemas.

A.2.1 Regra de chave de objeto (exemplo)

  • /transfers/{transferId}/chunks/{fileId}/{chunkIndex}
  • /transfers/{transferId}/manifest

Restrição: as chaves de objeto DEVEM permitir a limpeza em massa pelo prefixo transferId; as chaves de objeto DEVERIAM evitar carregar informações de negócio sensíveis.

A.3 Registros de estado: campos mínimos

O estado responde a “progresso e recuperação de upload/download”. Deve ser pequeno e rápido de ler e gravar.

  • transferId: DEVE.
  • status: DEVE. Valores sugeridos: UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: DEVE. Conjunto de chunks concluídos; DEVERIA ser comprimido com um bitmap / conjunto de intervalos.
  • uploadedBytes: DEVERIA. Para exibir o progresso e verificar cotas (pode ser derivado dos chunks, mas mantê-lo é mais rápido).
  • downloadCount: PODE. Se você impõe limites de contagem de downloads, ele precisa ser registrado e atualizado de forma atômica (os detalhes dependem do seu armazenamento).
  • expiresAt: DEVERIA. Para aplicar a expiração e a limpeza em segundo plano.

A.3.1 Saída mínima de uma API de recuperação

Para transferências retomáveis, o servidor DEVERIA ser capaz de retornar:

  • Status da transferência (UPLOADING/READY/DELETED/EXPIRED)
  • uploadedSet (conjunto de chunks concluídos)
  • Resumo da política (por exemplo, acima da cota, expirada, se é permitido continuar o upload)

Observação: limite em relação ao whitepaper de segurança e privacidade

  • Este apêndice descreve apenas as “estruturas e restrições” necessárias para a transferência e o armazenamento.
  • Para os campos de criptografia, a forma como o material de chaves é transportado/derivado e o comportamento de falha fechada em caso de falhas de autenticação, consulte o whitepaper de segurança e privacidade.