Como aceitar uploads grandes que sobrevivem à queda da conexão

Uploads grandes não são requisições que falham de vez em quando. São transferências que serão interrompidas, e a verdadeira decisão se resume a saber se a interrupção vai custar ao usuário os bytes restantes ou todos eles. Todo o resto do design decorre dessa escolha.

O que mais importa

• Depois que a quantidade declarada tiver chegado, a Assembly deixa de esperar por uploads adicionais. Concilie a lista de uploads dela com os arquivos que você pretendia enviar.
• Os arquivos podem ter até 200 GB, mas, por padrão, os uploads precisam terminar em até oito horas após a criação da Assembly; o processamento tem um prazo separado.

POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=---xyz

-----xyz
Content-Disposition: form-data; name="params"

{"auth":{"key":"YOUR_KEY"},
 "template_id":"YOUR_TEMPLATE_ID"}
-----xyz
Content-Disposition: form-data;
  name="num_expected_upload_files"

2
-----xyz--

HEAD /resumable/files/136058f2ef4d HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0

HTTP/1.1 204 No Content
Upload-Offset: 3000
Upload-Length: 10000

PATCH /resumable/files/136058f2ef4d HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Content-Length: 7000
Content-Type: application/offset+octet-stream

const uppy = new Uppy().use(Transloadit, {
  waitForEncoding: true,
  assemblyOptions: async () => {
    // Your back end signs with the Auth Secret
    const res = await fetch('/api/tl-signature', { method: 'POST' })
    if (!res.ok) throw new Error('Unable to authorize the upload')
    const { params, signature } = await res.json()
    return { params, signature }
  },
})

Detalhes técnicos que vale a pena conhecer

• A Assembly é criada por um POST multipart que carrega params e num_expected_upload_files, mas nenhum conteúdo de arquivo, e a resposta inclui tus_url, expected_tus_uploads, started_tus_uploads e finished_tus_uploads.
• Uma Assembly permanece no estado ASSEMBLY_UPLOADING até que todos os uploads tus declarados tenham terminado, mesmo que alguns dos arquivos que ela já recebeu tenham sido processados.
• Cada upload tus começa com um POST para tus_url que leva assembly_url, filename e fieldname como metadados, e o servidor responde com a URL do upload no cabeçalho Location.
• Retomar consiste em uma requisição HEAD para essa URL de upload, que informa a quantidade de bytes recebidos no cabeçalho Upload-Offset, seguida de um PATCH que envia o restante exatamente a partir desse offset.
• Metadados extras enviados com um upload se tornam uma Assembly Variable em file.user_meta, que é por arquivo, ao contrário de fields, que é compartilhado por todos os arquivos da mesma Assembly.
• Por padrão, o upload é limitado a oito horas a partir da criação, e o processamento, a oito horas a partir da conclusão do upload. Um limite de processamento específico do Workspace pode alterar esse segundo prazo; ultrapassar qualquer um dos prazos retorna ASSEMBLY_EXPIRED.

Uma abordagem prática

Quando a Transloadit é útil

Use o Uppy com o plugin da Transloadit no navegador, ou qualquer cliente tus em outros ambientes, e deixe que /upload/handle receba os arquivos. Primeiro crie a Assembly com num_expected_upload_files e depois envie cada arquivo para o endereço tus_url retornado no Assembly Status.

Limite da arquitetura

A retomada de uploads recupera uma transferência interrompida, não uma transferência esquecida. Por padrão, os uploads precisam terminar em até oito horas após a criação da Assembly, e o processamento, em até oito horas após a conclusão do upload. Um limite de processamento específico do Workspace pode alterar a segunda janela. Após a expiração, a Assembly retorna ASSEMBLY_EXPIRED e os bytes já recebidos deixam de ser utilizáveis.