Guía de API de subida de archivos: arquitectura, seguridad y selección de proveedores

Elegir una API de subida de archivos es una decisión de arquitectura, no una comparación de widgets. El diseño adecuado controla por dónde viajan los bytes, quién puede autorizar una transferencia, cómo se reanuda el trabajo interrumpido, cuándo un archivo pasa a ser confiable, dónde se guardan las copias persistentes y cómo regresan al producto los resultados del procesamiento.

Lo más importante

• Decide si desarrollar, comprar o adoptar un modelo híbrido probando los requisitos de recuperación, seguridad, procesamiento y operación, no solo la demostración del caso ideal.
• Usa ejemplos específicos de un framework solo cuando sea posible mantener y probar su ciclo de vida, autorización en el servidor y comportamiento de recuperación.

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

const uppy = new Uppy().use(Transloadit, {
  async assemblyOptions() {
    const response = await fetch('/api/transloadit-params', {
      credentials: 'same-origin',
    })
    if (!response.ok) {
      throw new Error('Could not authorize this upload')
    }
    return response.json()
  },
  waitForEncoding: true,
})

uppy.on('transloadit:complete', (assembly) => {
  console.log(assembly.assembly_id, assembly.results)
})

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() {
  // Call this only after the server has authenticated the request and authorized the operation.
  return transloadit.calcSignature({
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      nonce: randomUUID(),
    },
    template_id: requiredEnvironmentValue('TRANSLOADIT_UPLOAD_TEMPLATE_ID'),
  })
}

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^image/"]
      ],
      "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",
      "path": "uploads/${file.id}/${file.url_name}"
    }
  }
}

Detalles técnicos que conviene conocer

• En una subida del navegador a la aplicación, el servidor de la aplicación forma parte de la ruta de datos, mientras que un diseño directo al almacenamiento o al procesamiento mantiene los bytes del archivo fuera de ese controlador de solicitudes.
• El protocolo central de tus reanuda una transferencia leyendo del servidor el valor de Upload-Offset con HEAD y continuando con PATCH; enviar de nuevo el archivo completo es un reintento, no una reanudación.
• El plugin Transloadit de Uppy usa el protocolo tus para transferir archivos y puede solicitar parámetros firmados de Assembly a un back end de la aplicación mediante su función assemblyOptions.
• Transloadit Signature Authentication firma en un servidor de confianza los parámetros codificados en JSON mediante el Auth Secret; el secreto nunca debe enviarse al código del navegador.
• Un Template guardado con allow_steps_override establecido en false impide que un cliente no confiable sustituya sus Steps o seleccione otro destino de almacenamiento mediante sustituciones de Steps.
• Sin un Robot de exportación, Transloadit elimina los archivos temporales después de 24 horas, mientras que sus URL temporales pueden vencer después de unas horas y están destinadas únicamente a recuperaciones limitadas y de corta duración.
• En las subidas mediante el protocolo tus a Transloadit, la Assembly se crea antes de que lleguen los bytes de los archivos y permanece en ASSEMBLY_UPLOADING hasta que finalicen las subidas declaradas.
• La ventana de subida de Transloadit dura ocho horas desde la creación de la Assembly, por lo que un cliente reanudable aún necesita una ruta de reinicio deliberada cuando la Assembly haya vencido.

Un enfoque práctico

Cuándo resulta útil Transloadit

Usa Transloadit cuando las subidas requieran la reanudación del protocolo tus, la experiencia de Uppy en el navegador, la incorporación desde fuentes remotas, el procesamiento de archivos en varios pasos o exportaciones a un almacenamiento bajo tu control. Los contratos exactos de los parámetros están en la documentación de los Robots /upload/handle, /file/filter, /image/resize y /s3/store.

Límite de la arquitectura

Transloadit puede recibir archivos, ejecutar flujos de trabajo de procesamiento asíncrono y exportar resultados, pero tu aplicación sigue siendo responsable de la autenticación de usuarios, la autorización de inquilinos, el registro persistente de los recursos, la política de publicación y la entrega desde el almacenamiento permanente.