O que permite retomar o envio
O envio retomável é uma forma de transferir um arquivo em etapas que podem continuar após uma interrupção. O servidor conserva a parte aceita e informa ao cliente de onde prosseguir. Isso evita retransmitir o arquivo inteiro quando a conexão cai.
O tus é um protocolo para esse tipo de upload. Nele, o cliente consulta o endereço do envio com uma requisição HEAD e recebe a posição em bytes no cabeçalho Upload-Offset. A requisição PATCH seguinte leva o restante a partir dessa posição, mesmo que o contador local indique uma quantidade maior já transmitida.
Como interpretar a posição em bytes
Num exemplo didático, um arquivo tem 100 bytes e a consulta retorna Upload-Offset: 70. Esse valor indica que os primeiros 70 bytes foram aceitos. O cliente envia os 30 restantes num PATCH com a mesma posição inicial. Uma resposta bem-sucedida informa o novo valor, 100, que coincide com o tamanho do arquivo.
Se o cliente tentar continuar da posição 80 quando o servidor estiver na 70, o tus exige a resposta 409 Conflict sem alterar o recurso. Você precisa consultar novamente a posição, pois repetir a tentativa com o mesmo número mantém a divergência.
Até quando a retomada funciona
A retomada exige que o upload parcial ainda exista. Um serviço com a extensão de expiração pode removê-lo após o prazo indicado em Upload-Expires. A conclusão do transporte também é diferente da aceitação do arquivo pela aplicação, que pode precisar verificar seu formato e seu conteúdo.
Dúvidas frequentes
Perguntas frequentes sobre envio retomável
- Como o cliente descobre de onde retomar no tus?
- Uma requisição HEAD ao endereço do upload retorna a posição atual no cabeçalho Upload-Offset. O contador local de bytes enviados não confirma quanto o servidor aceitou.
- O que acontece quando as posições não coincidem?
- O servidor responde com 409 Conflict e mantém o recurso sem alteração. O cliente precisa consultar a posição atual para preparar uma nova tentativa.
- Um upload parcial pode expirar?
- Sim. A extensão de expiração do tus informa o prazo em Upload-Expires. Se o servidor já removeu o recurso, o cliente precisa iniciar outro upload.
Para continuar
Recursos relacionados
Documentação
tus: protocolo de envio retomável
Especificação do tus 1.0.0, com a consulta de posição, a continuação do upload e a extensão de expiração.
Abrir recursoSite de referência
Dev Side Studio: desenvolvimento colaborativo
Sessão ao vivo para você investigar falhas de upload no editor e no terminal com orientação técnica.
Abrir recursoAplicação na formação
Vibe Coding: Do Zero ao MVP
Ao desenvolver um upload, você precisa conferir a retomada após uma queda de conexão e o tratamento do arquivo recebido.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.