Guia de API de upload de arquivos: arquitetura, segurança e escolha de provedor

Defina a tarefa de upload antes de escolher um widget

Um upload em produção começa antes de o primeiro byte se mover. A aplicação identifica o usuário, decide qual operação é permitida, descreve a quantidade e o tamanho de arquivos aceitáveis e cria um registro que pode sobreviver a uma aba do navegador. A transferência é apenas uma etapa. Validação, processamento, exportação, notificação e reconciliação determinam se o produto pode usar o arquivo com segurança depois.

Escreva um contrato de conclusão em termos de produto. “A requisição retornou 200” é um critério fraco; “o original e os derivados necessários estão armazenados sob este tenant, o registro do ativo indica suas versões e um callback duplicado não altera nada” é testável. Registre quais falhas os usuários podem tentar novamente, quais exigem um novo upload e quais deixam um estado visível para o operador fazer a recuperação.

Escolha um de quatro caminhos explícitos para os bytes

Na retransmissão pela aplicação, o navegador envia o arquivo ao seu servidor, e o seu servidor o encaminha ou armazena. Essa abordagem é fácil de entender e dá controle imediato à aplicação, mas cada byte consome seu tráfego de entrada, memória ou disco temporário, tempo de conexão e tráfego de saída. Ela é adequada para arquivos pequenos e pouco frequentes quando o servidor existente consegue impor limites e fazer streaming com segurança, sem armazenar corpos inteiros em buffer.

“Direto para a nuvem” é ambíguo, então nomeie o destino. O navegador pode fazer upload diretamente para o armazenamento de objetos com credenciais de curta duração, diretamente para o serviço de processamento, como a Transloadit, ou pedir ao serviço que importe a URL remota existente. O armazenamento direto minimiza os saltos quando o trabalho se resume à persistência. O processamento direto mantém os bytes dos arquivos fora do servidor da aplicação enquanto o fluxo de trabalho valida, transforma e armazena os arquivos no destino escolhido.

Projete a retomada separadamente das novas tentativas

Uma nova tentativa inicia uma operação de novo; uma transferência retomável continua um upload existente a partir de um offset de bytes confirmado pelo servidor. Com o tus, o cliente guarda a URL do upload, consulta no servidor o Upload-Offset e envia apenas os bytes restantes. Persista essa URL fora do estado transitório do componente caso a recuperação deva funcionar após uma atualização da página ou um travamento, e gere a impressão digital dos arquivos com cuidado para que o arquivo local de um usuário nunca seja associado ao recurso de upload de outro.

A retomada não torna o tempo ilimitado nem o processamento idempotente. Uma Assembly da Transloadit ainda tem oito horas, a partir da criação, para concluir o upload, e criar uma Assembly substituta pode duplicar trabalho, a menos que a aplicação reconcilie o identificador antigo. Defina como o cliente lida com pausa, tempo offline, recursos expirados, arquivos alterados, uploads abandonados e uma resposta de conclusão perdida depois que o servidor aceitou os bytes finais.

Autorize a intenção no servidor e desconfie dos bytes

O código do navegador pode conter uma Auth Key pública, mas nunca deve conter o Auth Secret da Transloadit nem credenciais de armazenamento permanentes. Autentique o usuário na sua aplicação, selecione um Template salvo no servidor e retorne parâmetros assinados de curta duração com um nonce exclusivo. Defina allow_steps_override como false quando o navegador não tiver um motivo legítimo para substituir Steps, pois, caso contrário, um grafo de Steps selecionado pelo cliente poderia alterar o comportamento de processamento ou de exportação.

Uma assinatura válida prova que o payload de parâmetros foi autorizado; ela não prova que os bytes enviados correspondem a um nome de arquivo, a uma extensão, a um tipo MIME declarado, a um tenant ou a uma política de moderação. Limite o corpo das requisições antes de qualquer trabalho custoso, inspecione as propriedades observadas dos arquivos, rejeite conteúdo não suportado, faça varreduras onde o modelo de ameaças exigir e mantenha resultados não confiáveis longe do armazenamento público até que o fluxo de trabalho atinja um estado aprovado.

Escolha onde os arquivos serão armazenados após o processamento

Um endpoint de upload não é automaticamente um sistema de registro. Decida qual bucket ou banco de dados de ativos é dono do original, como os derivados se relacionam com ele, quais identificadores sobrevivem a renomeações e quem exclui cada cópia. A Transloadit normalmente retém resultados temporários por 24 horas, a menos que a opção “Não salvar” esteja ativada, enquanto as URLs de acesso a eles podem expirar após algumas horas. Adicione um Step de armazenamento para os arquivos que você quer manter: /transloadit/store para o Transloadit Storage (beta) ou outro Robot de exportação como /s3/store para seu próprio armazenamento. URLs temporárias se limitam à recuperação de curto prazo, não à incorporação nem à entrega repetida no produto.

Coloque a exportação dentro da Assembly quando o sucesso do fluxo de trabalho exigir tanto o processamento quanto a persistência. Um Robot de exportação pode usar credenciais de Template armazenadas para gravar os resultados no destino escolhido como parte do fluxo de trabalho. Como alternativa, faça primeiro o upload diretamente para um armazenamento próprio e acione o processamento a partir de um evento controlado. Esse caminho ganha uma cópia durável antecipada, mas adiciona orquestração e mais uma transferência até o processador.

Com o Transloadit Storage (beta), você não precisa de um bucket S3 próprio. Você também pode salvar arquivos no seu próprio provedor de armazenamento compatível. A File Library (prévia) é a interface de gestão de ativos digitais (DAM) da Transloadit para navegar visualmente, organizar, pré-visualizar e baixar arquivos no Transloadit Storage. O acesso à File Library é habilitado por Workspace; consulte-nos sobre a disponibilidade. Os exemplos de S3 deste guia demonstram a opção de trazer seu próprio armazenamento.

Decida entre construir e comprar na fronteira de propriedade

Construa o caminho de transferência quando os requisitos forem restritos e a equipe estiver preparada para assumir todo o ciclo de vida. Um pequeno formulário autenticado que transmite arquivos curtos para um único bucket existente pode não justificar outra plataforma. Ainda assim, a estimativa deve incluir parsing de multipart, backpressure, imposição de limites de tamanho, retomabilidade ou sua ausência deliberada, limpeza, controles contra abuso, observabilidade, atualizações e suporte a falhas que ocorrem fora do tempo de vida da requisição.

Um serviço gerenciado fica mais atraente à medida que o fluxo de trabalho combina redes instáveis, arquivos grandes, UX de navegador, fontes remotas, inspeção de mídia, transformação ou vários destinos de armazenamento. Comprar não elimina a responsabilidade pelas verificações de tenant, pela autorização, pelos registros de ativos, pela política de retenção e pelas regras de publicação da sua aplicação. Escolha armazenamento hospedado quando quiser que o provedor o opere, ou um design híbrido quando manter seu bucket existente for importante.

Avalie o fluxo de trabalho completo do Uppy + Transloadit. O Uppy fornece a interface de upload e se conecta à infraestrutura de upload e processamento da Transloadit. O Transloadit Storage está em beta; seus arquivos podem ser gerenciados pela File Library (prévia), com acesso à File Library habilitado por Workspace. Consulte-nos sobre a disponibilidade do Transloadit Storage e da File Library. Você também pode manter seu armazenamento atual. Sua aplicação ainda autentica usuários, persiste registros de ativos e controla a entrega. Para arquivos no Transloadit Storage, seu servidor assina URLs do Smart CDN. Você não precisa operar os servidores de upload e de processamento de mídia.

Compare provedores com testes de falha, não com contagem de recursos

Crie um quadro de avaliação a partir da carga de trabalho real do produto. Compare clientes de navegador e mobile, suporte a protocolos abertos, tamanho máximo de arquivo, comportamento de concorrência, endpoints geográficos, importações remotas, abrangência de processamento, destinos de armazenamento, isolamento de credenciais, verificação de webhooks, retenção de status, suporte e opções de saída. Marque cada recurso como obrigatório, opcional ou irrelevante antes de consultar as páginas dos fornecedores.

Passe os mesmos dados de teste por cada candidato sério. Interrompa um upload grande, recarregue a página, envie um evento de conclusão duplicado, revogue credenciais de armazenamento, recuse um arquivo após o recebimento, exceda um limite e perca a resposta final. Meça a recuperação visível para o usuário, os bytes retransmitidos, o tempo até uma saída durável, as evidências para o operador e a limpeza. Um seletor de arquivos bem-acabado diz pouco sobre essas propriedades de produção.

Implemente um upload assinado com Uppy e Transloadit

No exemplo de navegador, o Uppy gerencia a seleção e a transferência tus, enquanto o plugin da Transloadit solicita parâmetros de Assembly à sua aplicação. O endpoint do servidor precisa autenticar o usuário atual antes de retornar o objeto de calcSignature. Ele deve selecionar o próprio Template em vez de aceitar Steps arbitrários ou um destino de armazenamento fornecido pelo chamador, e deve aplicar limite de taxa à autorização independentemente do tráfego de upload.

Antes de usar este exemplo, ative “Exigir uma assinatura correta” nas Configurações do Workspace, salve o Template abaixo e defina o ID dele em TRANSLOADIT_UPLOAD_TEMPLATE_ID no servidor. Armazene o acesso da AWS ao seu próprio bucket privado como credenciais de Template chamadas my_s3_credentials. A Auth Key pode chegar ao navegador; o Auth Secret e as credenciais da AWS não podem. O endpoint de assinatura precisa retornar Cache-Control: no-store para que cada operação autorizada receba parâmetros novos.

Instale @uppy/core, @uppy/dashboard e @uppy/transloadit no frontend e o SDK @transloadit/node no servidor. Monte o exemplo do navegador depois que existir um elemento como <div id="photo-upload"></div>. Implemente /api/transloadit-params no seu framework com autenticação de sessão e autorização de upload antes de chamar a função auxiliar de assinatura. Rejeite requisições não autenticadas ou não autorizadas; a função auxiliar em si não é um endpoint de autenticação.

A política de arquivos do exemplo permite uma única imagem JPEG, PNG ou WebP de até 9 MiB. A configuração maxFileSize do Uppy oferece feedback imediato sobre o tamanho do arquivo em bytes, e o filtro do lado do servidor no Template bloqueado aplica esse limite de 9 MiB por arquivo. O limite assinado auth.max_size define um limite total de 10 MiB para a requisição, incluindo os bytes da requisição inicial da Assembly e os uploads retomáveis; auth.max_number_of_files limita a Assembly a um único arquivo. Isso deixa uma margem ilustrativa de 1 MiB para os bytes adicionais da requisição. Esse volume adicional varia, portanto a rejeição pelo servidor continua sendo decisiva; a aceitação pelo navegador não garante a criação da Assembly. waitForEncoding: true aguarda a Assembly, incluindo a exportação, em vez de tratar a conclusão da transferência como a conclusão do fluxo de trabalho.

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

// Mount this once after <div id="photo-upload"></div> exists in your page.
const uppy = new Uppy({
  restrictions: {
    maxNumberOfFiles: 1,
    maxFileSize: 9 * 1024 * 1024,
    allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
  },
}).use(Dashboard, { inline: true, target: '#photo-upload' }).use(Transloadit, {
  async assemblyOptions() {
    const response = await fetch('/api/transloadit-params', {
      credentials: 'same-origin',
      cache: 'no-store',
    })
    if (!response.ok) {
      throw new Error('Could not authorize this upload')
    }
    return response.json()
  },
  waitForEncoding: true,
  retryDelays: [0, 1000, 3000, 5000, 10000],
})

uppy.on('transloadit:assembly-created', (assembly) => {
  // Associate this ID with the server-side operation before the user leaves the page.
  console.log('Assembly started:', assembly.assembly_id)
})

uppy.on('transloadit:complete', (assembly) => {
  // Record completion against the ID persisted at transloadit:assembly-created.
  console.log('Processing completed. Assembly:', assembly.assembly_id)
})

uppy.on('transloadit:assembly-error', () => {
  // Show this through the application’s accessible status UI, not raw API errors or URLs.
  console.error('Processing failed. Check the Assembly in your workspace.')
})

uppy.on('upload-error', () => {
  // Transloadit API signature rejections and Assembly errors also reach this event.
  // Failures thrown by assemblyOptions() use Uppy’s general error event instead.
  // Deduplicate application notices.
  console.error('The upload workflow failed. Check its status before retrying.')
})

import { randomUUID } from 'node:crypto'
import { Transloadit } from '@transloadit/node'

function requiredEnvironmentValue(name: string): string {
  const value = process.env[name]
  if (value == null) throw new Error(`Missing environment variable: ${name}`)
  return value
}

const transloadit = new Transloadit({
  authKey: requiredEnvironmentValue('TRANSLOADIT_KEY'),
  authSecret: requiredEnvironmentValue('TRANSLOADIT_SECRET'),
})

export function createAuthorizedUploadParameters(): { params: string; signature: string } {
  // Call this only after the server has authenticated the request and authorized the operation.
  const params = {
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      max_size: 10 * 1024 * 1024,
      max_number_of_files: 1,
    },
    nonce: randomUUID(),
    template_id: requiredEnvironmentValue('TRANSLOADIT_UPLOAD_TEMPLATE_ID'),
  }
  return transloadit.calcSignature(params)
}

Conecte recebimento, validação, processamento e exportação

Uma única Assembly conecta o caminho completo: upload autenticado com Uppy → validação com /file/filter → processamento com /image/resize → exportação com /s3/store para um bucket pertencente ao cliente. O Template salvo dela fornece o fluxo de trabalho, e cada dependência use determina quais arquivos chegam ao próximo Step. O Uppy fornece a experiência de upload; é a Transloadit, e não o seu servidor de aplicação, que executa o fluxo de trabalho gerenciado.

O filtro verifica o tipo MIME detectado e rejeita arquivos maiores que 9 MiB e, em seguida, passa apenas as imagens aceitas para os Steps de pré-visualização e exportação. error_on_decline: true transforma uma rejeição em um erro da Assembly. As verificações de MIME e de tamanho não são varredura de malware nem moderação de conteúdo; adicione esses Steps antes do processamento e da exportação quando sua política exigir.

Use um bucket S3 privado com Block Public Access ativado e credenciais de Template com escopo adequado. acl: "bucket-default" omite uma ACL de objeto e depende da política de acesso do bucket; isso não torna privado um bucket público. A exportação armazena o original aceito e uma pré-visualização limitada a 1600 × 1600 pixels, em caminhos específicos da Assembly e do arquivo. Nenhuma das exportações lê diretamente de :original sem filtragem.

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^image/(jpeg|png|webp)$"]
      ],
      "declines": [["${file.size}", ">", 9437184]],
      "error_on_decline": true
    },
    "preview": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600
    },
    "exported": {
      "use": ["accepted_images", "preview"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "acl": "bucket-default",
      "path": "uploads/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}

Teste um vídeo grande, do upload interrompido à exportação privada

Para um fluxo de trabalho de vídeo, crie uma credencial de Template chamada large-upload-output usando credenciais IAM cuja permissão s3:PutObject esteja limitada ao prefixo privado upload-tests/. Siga a configuração de IAM do /s3/store, incluindo s3:AbortMultipartUpload para o prefixo de saída. Informe o bucket_region real nas credenciais de Template para evitar uma consulta de localização; credenciais usadas apenas para exportação não precisam de s3:ListBucket nem de s3:GetBucketLocation nessa configuração. Substitua YOUR_AUTH_KEY pela Auth Key do Workspace (não pelo Auth Secret dele), salve o Template abaixo e exija Signature Authentication nesse Template. Use um bucket privado com Block Public Access ativado e Object Ownership definido como Bucket owner enforced. A configuração acl: "bucket-default" omite uma ACL de objeto; o acesso continua controlado pelas políticas do seu bucket e do IAM. Para o teste, defina o TRANSLOADIT_UPLOAD_TEMPLATE_ID do endpoint de assinatura autenticado como o ID do Template de vídeo salvo. Reutilize a integração com o Uppy acima com um arquivo selecionado pelo usuário e uma única instância do Uppy. Esta política ilustrativa permite exatamente um vídeo de até 254 MiB de bytes de arquivo dentro do orçamento agregado de requisição de 256 MiB do Template. auth.max_size inclui os bytes da requisição inicial da Assembly mais os uploads retomáveis. O filtro confiável do Template rejeita arquivos maiores que 254 MiB, deixando 2 MiB de margem ilustrativa para a sobrecarga da requisição. Neste teste de vídeo, substitua a restrição exclusiva para imagens por allowedFileTypes: ["video/*"], defina maxFileSize: 254 * 1024 * 1024 na opção restrictions do core do Uppy e defina o auth.max_size assinado como 256 * 1024 * 1024; mantenha ambos os limites de quantidade de arquivos em 1 (maxNumberOfFiles e auth.max_number_of_files). A sobrecarga da requisição varia, então a rejeição pelo servidor continua sendo a decisão definitiva; a aceitação pelo navegador não garante a criação da Assembly. Verifique os limites de upload e os formatos de origem suportados do seu Workspace antes de testar. O Template detecta uma família MIME de vídeo, cria uma versão codificada em MP4 com limites definidos e exporta essa versão codificada e o original aceito. Esta não é uma política completa contra malware nem de segurança de conteúdo.

A conclusão da transferência não é a linha de chegada. Com waitForEncoding: true, o navegador aguarda o processamento, mas sua aplicação ainda precisa de um Assembly ID armazenado de forma durável e de notificações verificadas ou de uma consulta ao Assembly Status caso a aba desapareça. Uma falha na exportação não deve marcar o ativo como pronto. Confirme ASSEMBLY_COMPLETED, a versão exigida e ambos os objetos privados no S3; compare o checksum do original exportado com o da entrada antes de registrar o sucesso. Esses objetos privados não são automaticamente URLs públicas de reprodução.

Faça três execuções de controle online e três execuções interrompidas com o mesmo vídeo de 100–200 MiB de sua propriedade. Registre os bytes exatos do arquivo e o SHA-256, a duração e os codecs, as versões do navegador e dos pacotes, o Template, a região, o plano e a configuração de rede. No Chrome DevTools, aplique um perfil de limitação personalizado e registre as configurações dele, mude para Offline quando o upload estiver perto de 25%, por 10 segundos, e restaure o perfil sem recarregar a página. Em falhas de rede reportadas enquanto o navegador está offline e ainda restam tentativas, o plugin tus do Uppy instalado pausa a fila até um evento online. Cada repetição ainda consome uma tentativa; o progresso do upload pode redefinir o contador. A soma de retryDelays não é um limite de tempo offline. Verifique se uma requisição HEAD informa o Upload-Offset salvo e se as requisições PATCH seguintes continuam o mesmo recurso tus. Isso exercita uma interrupção emulada do navegador, não um failover de servidor nem todas as condições de rede.

Meça do início do upload até a primeira Assembly concluída com objetos exportados verificados, não apenas até o último byte enviado. Registre também o tempo da reconexão até a conclusão, os bytes retransmitidos quando for possível observá-los, as falhas, as Assemblies duplicadas e a contagem bruta de execuções. Este é um procedimento de teste reproduzível, não um resultado de benchmark publicado. Novas tentativas limitadas podem se esgotar com falhas repetidas de requisição, o prazo de upload de oito horas da Assembly continua valendo, e este exemplo em memória não restaura o estado depois de recarregar a página ou fechar a aba. Teste separadamente o cancelamento, a autorização expirada, os arquivos acima do limite e as credenciais de exportação revogadas. Consulte a API de upload retomável para a transição para o protocolo e a demonstração de vídeo e S3 EN (English) para um exemplo de processamento e exportação pública.

{
  "allow_steps_override": false,
  "auth": {
    "key": "YOUR_AUTH_KEY",
    "max_size": 268435456,
    "max_number_of_files": 1
  },
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_video": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^video/"]],
      "declines": [["${file.size}", ">", 266338304]],
      "error_on_decline": true
    },
    "rendition": {
      "use": "accepted_video",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/360p",
      "width": 640,
      "height": 360,
      "resize_strategy": "fit",
      "result": true
    },
    "exported": {
      "use": ["accepted_video", "rendition"],
      "robot": "/s3/store",
      "credentials": "large-upload-output",
      "acl": "bucket-default",
      "path": "upload-tests/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}