Leitfaden zur File Upload API: Architektur, Sicherheit und Anbieterauswahl

Die Wahl einer Datei-Upload-API ist eine Architekturentscheidung, kein Vergleich von Widgets. Das richtige Design steuert, wohin Bytes übertragen werden, wer eine Übertragung autorisieren darf, wie unterbrochene Vorgänge fortgesetzt werden, wann eine Datei als vertrauenswürdig gilt, wo dauerhafte Kopien gespeichert sind und wie Verarbeitungsergebnisse an das Produkt zurückgegeben werden.

Worauf es besonders ankommt

• Entscheiden Sie sich für Eigenentwicklung, Zukauf oder ein hybrides Betriebsmodell, indem Sie die Anforderungen an Wiederherstellung, Sicherheit, Verarbeitung und Betrieb testen, nicht nur die Demo für den Idealfall.
• Verwenden Sie frameworkspezifische Beispiele nur, wenn deren Lebenszyklus, Serverautorisierung und Wiederherstellungsverhalten gewartet und getestet werden können.

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}"
    }
  }
}

Wissenswerte technische Details

• Bei einem Upload vom Browser an die Anwendung wird der Anwendungsserver Teil des Datenpfads. Ein Konzept mit direkter Speicherung oder direkter Verarbeitung hält die Dateibytes dagegen aus diesem Request-Handler heraus.
• Das tus-Kernprotokoll setzt einen unterbrochenen Upload fort, indem es den serverseitigen Upload-Offset mit HEAD ausliest und mit PATCH weiterüberträgt; die gesamte Datei erneut zu senden ist ein Wiederholungsversuch, keine Wiederaufnahme.
• Das Transloadit-Plugin von Uppy verwendet tus für die Dateiübertragung und kann mithilfe seiner Funktion assemblyOptions signierte Assembly-Parameter von einem Anwendungs-Backend anfordern.
• Transloadit Signature Authentication signiert die JSON-codierten Parameter auf einem vertrauenswürdigen Server mit dem Auth Secret; das Geheimnis selbst darf niemals an Browsercode gesendet werden.
• Ein gespeichertes Template, bei dem allow_steps_override auf false gesetzt ist, verhindert, dass ein nicht vertrauenswürdiger Client die zugehörigen Steps ersetzt oder durch Überschreibungen von Steps ein anderes Speicherziel auswählt.
• Ohne Export-Robot löscht Transloadit temporäre Dateien nach 24 Stunden. Ihre temporären URLs können bereits nach wenigen Stunden ablaufen und sind nur für einen begrenzten, kurzfristigen Abruf vorgesehen.
• Bei tus-Uploads an Transloadit wird die Assembly erstellt, bevor die Dateibytes eintreffen, und verbleibt in ASSEMBLY_UPLOADING, bis die deklarierten Uploads abgeschlossen sind.
• Das Zeitfenster für Uploads bei Transloadit beträgt ab der Erstellung der Assembly acht Stunden. Daher benötigt auch ein Client für fortsetzbare Uploads einen ausdrücklich vorgesehenen Ablauf für einen Neustart, wenn die Assembly abgelaufen ist.

Ein praxisnaher Ansatz

Wann Transloadit hilfreich ist

Verwenden Sie Transloadit, wenn Uploads mit tus fortsetzbar sein müssen oder wenn Sie die Browser-UX von Uppy, den Import aus Remote-Quellen, eine mehrstufige Dateiverarbeitung oder Exporte in von Ihnen kontrollierten Speicher benötigen. Die genauen Parameterverträge finden Sie in der Robot-Dokumentation zu /upload/handle, /file/filter, /image/resize und /s3/store.

Architekturgrenze

Transloadit kann Dateien empfangen, asynchrone Verarbeitungsworkflows ausführen und Ergebnisse exportieren. Ihre Anwendung bleibt jedoch für die Nutzerauthentifizierung, die Mandantenautorisierung, den dauerhaft gespeicherten Datensatz des Assets, die Veröffentlichungsrichtlinie und die Auslieferung aus dem permanenten Speicher verantwortlich.