Upload multipart: Comportamento e interfaces

Define sessões de upload retomáveis com escopo de locatário, com somas de verificação por parte, expiração, conclusão somente quando o hash corresponder e limpeza de abortos para que arquivos grandes possam ser retomados sem partes órfãs ou chaves entre locatários.

Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não há garantia de que uma implementação adotante os tenha aprovado.

Decisão

Uploads grandes criam uma sessão com uma chave de objeto com escopo de locatário, uma expiração, tamanho declarado e um digest do objeto fornecido pelo cliente. Os clientes fazem PUT de partes numeradas com somas de verificação por parte. A conclusão só tem sucesso quando as partes são contíguas, os limites em protocol.yaml são respeitados e o digest concatenado corresponde. Abortos ou expiração deletam partes para que dados incompletos não se tornem um objeto baixável. Identificadores de sessão não são utilizáveis entre locatários. A varredura de malware do objeto publicado é uma etapa relacionada após a conclusão. O download autorizado do objeto publicado é um bloqueio relacionado.

Escopo

• Ciclo de vida da sessão, limites de partes, somas de verificação, conclusão, aborto e varredor.
• Comportamento da API para uploads de arquivos grandes em um locatário.
• Layout da chave {tenant_id}/uploads/{session_id}.

Fora deste bloco

• GET por intervalo de bytes de objetos publicados.
• Varredura de vírus e política de tipo de conteúdo após publicação.
• Protocolos multipart de um fornecedor de nuvem específico além dos números do perfil.

Contrato

• Sessões existem nos estados listados em protocol.yaml; métodos fora do conjunto permitido falham fechados.
• Partes fora de min_part_bytes/max_part_bytes (exceto a última parte) são rejeitadas; max_parts é 10000 neste perfil.
• Uma parte com checksum_crc32c incorreto não é retida.
• POST_complete publica somente quando as partes são contíguas e SHA-256 corresponde a object_sha256; caso contrário, upload_checksum_mismatch e o estado retorna para aberto.
• IDs de sessão de locatário estrangeiro resolvem como not_found sem listagem de partes.
• Abortos e varredor de expiração deletam partes e impedem que a chave seja servida como objeto concluído.

Orientação para implementação

• Verificações de locatário vivem nos metadados da sessão, não são inferidas apenas pelas chaves dos objetos.
• Ecoar números de parte e somas de verificação no status. Varrer expires_at mesmo sem aborto.

Tratamento de falhas e salvaguardas

• Concluir sem correspondência de digest nunca se torna concluído. Falta de object_sha256 recusa iniciar.
• Expiração usa o relógio da store.

Verificação e operações

• Testes: expiração, soma de verificação da parte, hash do objeto, ocultação entre locatários, limpeza de aborto.
• Alerta para sessões mais antigas que session_ttl_seconds. Tamanhos do perfil não são padrões do fornecedor.

Os exemplos com aparência executável neste pacote são fixtures e contratos de aceitação. Execute python tools/validate.py a partir da raiz da coleção para verificar a estrutura e metadados do pacote; depois implemente e execute os cenários no repositório alvo.

Suposições para adoção

• Nomes e valores numéricos em example.yaml são um perfil de adoção, não padrões universais.
• A equipe adotante deve mapear atores, classes de dados, vocabulário de erros e propriedade para seu sistema.

Referências

• Nenhuma fonte normativa externa é necessária; este pacote define uma decisão do projeto.