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 serviços de processamento como a Transloadit, ou pedir a algum serviço que importe URLs remotas já existentes. O armazenamento direto minimiza os saltos quando o objetivo é apenas a persistência. O processamento direto mantém a aplicação fora do caminho dos dados enquanto o fluxo de trabalho valida, transforma e exporta os arquivos para um armazenamento próprio.

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.

Separe o armazenamento durável do processamento de uploads

Um endpoint de upload não é automaticamente um sistema de registro. Decida qual bucket ou banco de dados de ativos é o dono do original, como os derivados se relacionam com ele, quais identificadores sobrevivem a renomeações e quem exclui cada cópia. A Transloadit retém resultados temporários por pelo menos 24 horas, enquanto as URLs de acesso a eles podem expirar após algumas horas. Exporte os arquivos que precisam persistir. URLs temporárias servem apenas para recuperação de curto prazo, não para incorporação nem para 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.

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 se torna 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 da aplicação: verificações de tenant, autorização, registros de ativos, retenção, publicação e tratamento de incidentes continuam sendo seus. Um design híbrido costuma funcionar melhor, com armazenamento próprio e estado de negócio em torno de uma camada gerenciada de transferência e processamento.

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 Node transloadit 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.

O exemplo permite uma única imagem JPEG, PNG ou WebP de até 10 MiB. As restrições do Uppy oferecem feedback imediato, enquanto os limites assinados auth.max_size e auth.max_number_of_files e o filtro do lado do servidor no Template aplicam a política. 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: 10 * 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'

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 o tamanho do arquivo 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}", ">", 10485760]],
      "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 para as permissões s3:ListBucket e s3:GetBucketLocation no nível do bucket; a consulta de localização é desnecessária quando a credencial de Template fornece bucket_region. 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 deste 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. Os limites do Template, de 256 MiB e de um único arquivo, são uma política de exemplo. Espelhe esses limites na opção restrictions do core do Uppy (maxFileSize, maxNumberOfFiles) para ter feedback antecipado no seletor; as verificações do lado do servidor continuam necessárias. Para este teste de vídeo, substitua a restrição exclusiva para imagens por allowedFileTypes: ["video/*"] e defina tanto o maxFileSize do navegador quanto o auth.max_size assinado como 256 * 1024 * 1024; mantenha ambos os limites de quantidade de arquivos em 1. 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 MP4 com limites definidos e exporta essa versão 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/"]],
      "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}"
    }
  }
}