Uploads de arquivos, otimização de imagens, codificação de vídeo e seu próprio bucket S3

Separe o trabalho no momento do upload do trabalho no momento da requisição

Comece com dois fluxos em vez de um vago “pipeline de otimização”. No fluxo no momento do upload, um navegador envia um arquivo por meio do Uppy e do tus para uma Assembly da Transloadit. O Template salvo valida o arquivo observado, cria todas as saídas que precisam existir imediatamente e exporta os arquivos selecionados para o S3. A aplicação armazena o Assembly ID e a identidade durável do objeto no S3 junto ao registro do ativo.

No fluxo no momento da requisição, um navegador solicita uma URL do Smart CDN. A URL identifica um Template salvo e um caminho de entrada no S3. Em caso de ausência no cache, a Transloadit importa esse objeto, aplica o Template com as Assembly Variables permitidas e entrega um resultado por meio de /file/serve. A camada de entrega armazena a resposta em cache; uma requisição com o cache aquecido pode reutilizar o derivado sem executar a transformação novamente.

Armazene no S3 um arquivo recebido por upload sem transformá-lo

Use um Template exclusivo para upload quando a Transloadit precisar receber e exportar o arquivo aceito sem alterar seus bytes de mídia. /upload/handle recebe a entrada, e /s3/store seleciona :original. O caminho de destino usa Assembly Variables para que uploads simultâneos não sobrescrevam uns aos outros, enquanto o nome original do arquivo, seguro para uso em URLs, permanece reconhecível.

Os exemplos fazem referência a credenciais de Template e usam acl: "private" para buckets com ACLs habilitadas porque /s3/store tem public-read como valor padrão. Para o S3 Object Ownership com ACLs desabilitadas, use acl: "bucket-default" em vez disso e imponha acesso privado por meio da política do bucket. Defina bucket_region com a região real do bucket na AWS para evitar uma consulta GetBucketLocation e remova s3:GetBucketLocation da política IAM das credenciais. Confirme o acesso efetivo ao S3 separadamente da configuração do Robot.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "stored": {
      "use": ":original",
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "uploads/${unique_prefix}/${file.url_name}"
    }
  }
}

Receba, valide, otimize e exporte o upload

Use um Template de imagem salvo para restringir o que o código no navegador pode solicitar. /upload/handle recebe o arquivo, /file/filter pode rejeitar arquivos cujas propriedades detectadas não atendam à política, /image/resize cria um derivado fixo em WebP, e /image/optimize reduz o tamanho dessa saída. Em seguida, /s3/store exporta exatamente os Steps indicados pelo valor de use. Aponte-o apenas para optimized para armazenar o derivado, apenas para accepted_images para armazenar o original aceito, ou para ambos para reter ambos os objetos. preserve_meta_data é mantido intencionalmente no valor padrão true para reter metadados da imagem, como informações de direitos autorais do fotógrafo, aceitando um pequeno aumento de tamanho mesmo com a prioridade compression-ratio.

O Uppy é a camada de upload no navegador, não o limite de autorização. Deixe o plugin da Transloadit solicitar parâmetros de Assembly assinados e de curta duração ao servidor da aplicação. Mantenha allow_steps_override desabilitado quando não for permitido ao navegador substituir os Steps salvos nem selecionar outro destino. Reutilize a ACL privada e a região real do bucket na AWS definidas no exemplo exclusivo para upload. Tanto ${file.id} quanto ${unique_prefix} são exclusivos de cada arquivo exportado; este exemplo de imagem usa ${file.id}, que não contém barras, para que o segmento intermediário do caminho permaneça como componente único, gerando chaves images/${file.id}/${file.url_name} previsíveis que o Smart CDN pode referenciar, enquanto os exemplos de upload e vídeo usam ${unique_prefix} como diretório para evitar colisões. Como ${file.id} é exclusivo de cada arquivo exportado, accepted_images e optimized são resolvidos como chaves diferentes sob images/; o modelo de caminho compartilhado não causa sobrescritas, portanto registre cada chave exportada separadamente no estado da aplicação. Considere o upload concluído para o produto somente depois que a aplicação tiver reconciliado o resultado da Assembly e as chaves duráveis do S3.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^(image/jpeg|image/png|image/gif|image/webp|image/avif)$"]],
      "error_on_decline": true
    },
    "resized": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600,
      "format": "webp"
    },
    "optimized": {
      "use": "resized",
      "robot": "/image/optimize",
      "priority": "compression-ratio",
      "preserve_meta_data": true
    },
    "stored": {
      "use": ["accepted_images", "optimized"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "images/${file.id}/${file.url_name}"
    }
  }
}

Codifique um vídeo antes de armazená-lo no S3

Use um Template exclusivo para vídeo quando o ideal for que o objeto durável no S3 seja uma versão para reprodução, em vez do arquivo de origem enviado por upload. /video/encode lê :original e aplica uma predefinição testada. web/mp4/720p é um ponto de partida concreto em MP4 com 1280×720, não uma recomendação universal; valide as dimensões do arquivo de origem, a taxa de quadros, o áudio, as legendas, a qualidade, o suporte a dispositivos, o tempo de processamento e o custo de acordo com o contrato de reprodução do produto.

O exemplo exporta o Step encoded e deixa o arquivo de origem fora dessa operação de armazenamento. Adicione um segundo Step /s3/store quando o arquivo de origem precisar continuar disponível para recodificação com maior qualidade, auditoria ou migração. A codificação pode durar mais que uma requisição da aplicação, então reconcilie o Assembly Status ou um callback de conclusão verificado antes de considerar a chave do S3 apta para publicação.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/720p"
    },
    "stored": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "private",
      "path": "videos/${unique_prefix}/${file.url_name}"
    }
  }
}

Transforme um original do S3 sob demanda pelo Smart CDN

Uma integração com o Smart CDN ainda começa com um Template salvo. /s3/import resolve o caminho de entrada usando credenciais de Template com escopo restrito, /image/resize lê o valor de ${fields.w} fornecido pela URL e o valor de ${browser.wanted_image_format} negociado na requisição, e /file/serve seleciona a resposta. Nesse fluxo, a infraestrutura de borda do Smart CDN da Transloadit deriva um cabeçalho x-tl-image-format confiável e pré-normalizado a partir do cabeçalho Accept do cliente. O cabeçalho é definido no lado do servidor e não pode ser controlado pelo cliente; nas Instructions, os desenvolvedores referenciam apenas ${browser.wanted_image_format}, que é resolvido para o mesmo valor: avif, webp ou jpg.

Uma URL como https://my-workspace.tlcdn.com/responsive-image/images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg?w=640 fornece images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg como o ${fields.input} implícito (o caminho após o nome do Template, sem barra inicial) e 640 como ${fields.w}. Essa entrada é a chave images/${file.id}/${file.url_name} registrada do original durável em accepted_images, que /s3/import lê para o redimensionamento sob demanda. O derivado otimizado é um objeto separado, sob seu próprio prefixo ${file.id}. Como as duas saídas não compartilham um diretório, registre cada chave exportada no estado da aplicação em vez de derivar uma chave da outra ou da URL da requisição.

Mantenha o prefixo images/ completo na URL do Smart CDN; não o adicione novamente no Template. Os valores de consulta do Smart CDN chegam como strings, então a lista de larguras permitidas é comparada com os literais de string "320" e "640"; uma largura sem correspondência passa a usar 1280. Manter o mapeamento de caminhos separado da lista de transformações permitidas facilita auditar qual objeto do S3 pode ser lido e qual versão pode ser solicitada.

Não interpole nenhum valor irrestrito de caminho, largura, qualidade ou formato só porque ele pode chegar como campo. Restrinja a credencial do S3 a um prefixo previsto, faça a aplicação confiável consultar a chave exportada no registro do ativo e assine uma URL que contenha exatamente essa chave. O fluxo executado no momento da requisição seleciona este Template salvo por meio da URL do Smart CDN, em vez de aceitar Assembly Instructions enviadas pelo navegador, por isso este exemplo não usa a configuração allow_steps_override do momento do upload. Use a região real do bucket da AWS, como no exemplo somente de upload. Valide ou mapeie os valores de transformação no Template. Consultas simples como ${fields.input} são gratuitas, enquanto comparações, operações aritméticas e ternários são avaliação dinâmica complexa: os ternários de largura e formato deste exemplo invocam /script/run e são cobrados sempre que ainda não houver um resultado em cache. A expressão de formato mapeia o valor alternativo jpg para null, de modo que requisições sem preferência por um formato moderno mantêm o formato original, em vez de perder transparência ou animação com uma recodificação desnecessária. Consulte a entrada ${browser.wanted_image_format} na referência de Assembly Variables. Meça a primeira transformação sem cache separadamente da entrega posterior em cache.

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "path": "${fields.input}"
    },
    "resized": {
      "use": "imported",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": "${fields.w === '320' ? 320 : fields.w === '640' ? 640 : 1280}",
      "format": "${browser.wanted_image_format === 'jpg' ? null : browser.wanted_image_format}"
    },
    "served": {
      "use": "resized",
      "robot": "/file/serve",
      "cache_duration": 604800
    }
  }
}

Decida o que armazenar permanentemente e o que gerar sob demanda

Manter um original no S3 oferece uma fonte estável para reprocessamento, mas não exige armazenar cada versão responsiva. Exporte as saídas canônicas de que o produto precisa independentemente de um cache: um master aprovado, uma imagem de anúncio de marketplace, um ativo de impressão ou um derivado imutável de lançamento. Deixe o Smart CDN criar variantes de apresentação limitadas cujas dimensões dependem do dispositivo ou do layout que faz a requisição.

Por outro lado, não dependa apenas de um caminho sob demanda quando a primeira requisição não puder tolerar a latência de processamento, quando um editor precisar aprovar os pixels exatos ou quando sistemas posteriores exigirem um objeto durável antes da publicação. Nesse caso, crie e exporte o derivado na Assembly do momento do upload. A mesma aplicação pode usar ambas as abordagens para classes de saída diferentes sem mudar o proprietário durável da fonte.

Proteja a aplicação, o bucket e a superfície de transformação

Crie credenciais de Template separadas e com privilégio mínimo quando as exportações de upload e as importações do Smart CDN precisarem de ações ou prefixos diferentes da AWS. Mantenha as chaves brutas da AWS, o Auth Secret da Transloadit e Instructions irrestritas fora dos bundles do navegador. O servidor da aplicação deve autorizar o usuário, selecionar o Template e emitir apenas os parâmetros de upload de curta duração ou a URL assinada do Smart CDN adequados para esse ativo.

Um upload bem-sucedido ou uma assinatura válida não equivale a uma aprovação para publicação. Valide o tipo MIME detectado e o tamanho na Assembly, associe callbacks de forma idempotente ao tenant e à Assembly esperados e exponha um resultado somente depois que o objeto durável e o registro da aplicação estiverem de acordo. No Smart CDN, planeje em conjunto o versionamento da fonte, a expiração da URL, o tempo de vida do cache e a exclusão, para que a substituição de uma chave do S3 não deixe ativo um endereço de derivado não intencional.

Compare com um pipeline nativo da AWS

Um design nativo pode fazer upload por meio de uma URL pré-assinada do S3, reagir a eventos de criação de objetos, processar com Lambda ou outro serviço de computação, armazenar derivados e entregá-los por meio de uma CDN. Essa pode ser uma ótima escolha quando a carga de trabalho fica dentro dos limites de runtime suportados e a equipe quer operar por conta própria autorização, novas tentativas, filas, codecs, concorrência, observabilidade e recuperação de falhas.

Compare caminhos de produção completos, e não apenas um redimensionamento bem-sucedido. Teste uploads interrompidos, fontes grandes, imagens malformadas, orientação e cor, eventos duplicados, exportações parciais, picos de concorrência, transformações a frio, invalidação de cache, latência regional e exclusão. Inclua o tempo de engenharia e de operações junto com as cobranças de upload, processamento, armazenamento, requisições e tráfego de saída. A escolha relevante é quais responsabilidades operacionais a equipe quer assumir.