Logo

Apêndice: Estruturas de Dados Mínimas (Manifesto/Parte/Estado)

Este apêndice fornece recomendações mínimas de estrutura de dados para “fragmentação paralela + transferência recuperável + novas tentativas idempotentes”. O objetivo é permitir simultaneidade de alto rendimento e recuperação confiável após falhas, sem transações complexas.

Princípios gerais

  • Objetos grandes versus estado pequeno: pedaços/manifesto são objetos grandes armazenados no armazenamento de objetos; state é pequeno e armazenado em um armazenamento de estado.
  • Chaves únicas e idempotência: um pedaço DEVE ser endereçável exclusivamente por (transferId, fileId, chunkIndex) para retransmissões idempotentes.
  • Recoverability: O estado DEVE expressar o “conjunto concluído” para que a recuperação possa pular as partes concluídas.
  • Nenhum vazamento sensível: chaves e estado de objeto DEVEM evitar a incorporação de campos confidenciais, como e-mail ou nomes de arquivos originais (se estes são criptografados depende de sua política de privacidade).

A.1 Campos mínimos do manifesto

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

  • manifestVersion: DEVE. Usado para atualizações de compatibilidade (por exemplo, 1).
  • transferId: DEVE. Identificador exclusivo da sessão de transferência.
  • criado em / expira em: DEVE. Para manipulação do ciclo de vida e dicas de interface do usuário.
  • policy: DEVE. Um resumo da política (limites de contagem de downloads, exigência de senha, se o compartilhamento antes de concluir é permitido, etc.).
  • arquivos[]: DEVE. Descrição da lista de arquivos (em tamanhos mínimos de arquivo e intervalos de blocos).
  • chunking: DEVE. Inclui chunkSize e como chunkCount é calculado ou chunkCount por arquivo.
  • objectKeyRule: DEVE. Derive chaves de objeto de (transferId, fileId, chunkIndex) ou forneça uma tabela de mapeamento explícita.

A.1.1 Campos mínimos de arquivos[]

  • fileId: DEVE. Identificador exclusivo de arquivo (não use nome de arquivo como chave exclusiva).
  • size: DEVE. Tamanho em bytes.
  • mime: MAIO. Para sugestões de exibição e download.
  • name: MAIO. Se você deseja conhecimento zero estrito/vazamento mínimo, omita name ou armazene um nome criptografado.
  • chunkCount: DEVE. Contagem de blocos para este arquivo.
  • chunkOffset: MAIO. Se vários arquivos compartilharem um global chunkIndex, é necessário um deslocamento; caso contrário, pode ser omitido.

A.1.2 Campos de integridade e verificação (opcional, mas recomendado)

  • pedaçoHashes[]: DEVE. Verificação por bloco (um ou uma combinação de hash/comprimento/etag).
  • fileHash: MAIO. Soma de verificação de arquivo inteiro (verifique após o download).
  • ciphertextLength: MAIO. Verificações de consistência de comprimento em nível de texto cifrado (não é necessário texto simples).

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

  • Endereçamento exclusivo: um pedaço DEVE ser endereçável exclusivamente por (transferId, fileId, chunkIndex).
  • Upload idempotente: reenviar o mesmo pedaço NÃO DEVE quebrar o estado final (pode sobrescrever ou ser rejeitado, mas o comportamento deve ser consistente).
  • Metadados mínimos: o servidor PODE registrar apenas comprimento do texto cifrado, tempo de gravação, etag/versão, etc., para observabilidade e solução de problemas.

A.2.1 Regra de chave de objeto (exemplo)

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

Restrição: as chaves do objeto DEVEM suportar a limpeza em massa por transferId prefixo; chaves de objeto DEVEM evitar transportar informações comerciais confidenciais.

A.3 Registros estaduais: campos mínimos

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

  • transferId：DEVE。
  • status: DEVE. Valores sugeridos: UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: DEVE. Conjunto de pedaços concluído; DEVE ser compactado com um bitmap/conjunto de intervalo.
  • uploadedBytes: DEVE. Para exibição de progresso e verificações de cota (podem ser derivadas de pedaços, mas mantê-lo é mais rápido).
  • downloadCount: MAIO. Se você impor limites de contagem de downloads, eles deverão ser registrados e atualizados atomicamente (os detalhes dependem do seu armazenamento).
  • expiresAt: DEVE. Para aplicação de expiração e limpeza de plano de fundo.

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

Para transferências recuperáveis, o servidor DEVE ser capaz de retornar:

  • Status da transferência (UPLOADING/READY/DELETED/EXPIRED)
  • uploadedSet (conjunto de blocos concluído)
  • Resumo da política (por exemplo, acima da cota, expirado, se o upload contínuo é permitido)

Observação: limite versus whitepaper de segurança e privacidade

  • Este apêndice descreve apenas as “estruturas e restrições” necessárias para transferência/armazenamento.
  • Para campos de criptografia, como o material da chave é transportado/derivado e comportamento de fechamento em caso de falhas de autenticação, consulte o documento técnico sobre segurança e privacidade.