Comment accepter des téléversements volumineux qui résistent aux coupures de connexion

Un téléversement volumineux n’est pas une requête qui échoue occasionnellement. C’est un transfert qui sera interrompu, et la seule véritable décision est de savoir si, après une interruption, l’utilisateur devra transférer les octets restants ou la totalité des octets. Tout le reste de la conception découle de ce choix.

L’essentiel

• Dès que le nombre déclaré de fichiers est reçu, l’Assembly n’attend plus de téléversements supplémentaires. Comparez sa liste de téléversements aux fichiers que vous comptiez envoyer pour vérifier leur concordance.
• Les fichiers peuvent atteindre 200 GB, mais les téléversements doivent se terminer dans les huit heures suivant la création de l’Assembly par défaut ; le traitement a un délai distinct.

POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=---xyz

-----xyz
Content-Disposition: form-data; name="params"

{"auth":{"key":"YOUR_KEY"},
 "template_id":"YOUR_TEMPLATE_ID"}
-----xyz
Content-Disposition: form-data;
  name="num_expected_upload_files"

2
-----xyz--

HEAD /resumable/files/136058f2ef4d HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0

HTTP/1.1 204 No Content
Upload-Offset: 3000
Upload-Length: 10000

PATCH /resumable/files/136058f2ef4d HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Content-Length: 7000
Content-Type: application/offset+octet-stream

const uppy = new Uppy().use(Transloadit, {
  waitForEncoding: true,
  assemblyOptions: async () => {
    // Your back end signs with the Auth Secret
    const res = await fetch('/api/tl-signature', { method: 'POST' })
    if (!res.ok) throw new Error('Unable to authorize the upload')
    const { params, signature } = await res.json()
    return { params, signature }
  },
})

Détails techniques à connaître

• L’Assembly est créée par une requête POST multipart contenant params et num_expected_upload_files, mais aucun contenu de fichier, et la réponse inclut tus_url, expected_tus_uploads, started_tus_uploads et finished_tus_uploads.
• Une Assembly reste dans l’état ASSEMBLY_UPLOADING jusqu’à la fin de chaque téléversement tus déclaré, même si certains fichiers qu’elle a déjà reçus ont été traités.
• Chaque téléversement tus commence par une requête POST vers tus_url contenant assembly_url, filename et fieldname comme métadonnées, et le serveur renvoie l’URL de téléversement dans l’en-tête Location.
• La reprise consiste en une requête HEAD vers cette URL de téléversement, dont la réponse indique le nombre d’octets reçus dans l’en-tête Upload-Offset, suivie d’une requête PATCH qui envoie le reste à partir de cette position exacte.
• Les métadonnées supplémentaires envoyées avec un téléversement deviennent une Assembly Variable sous file.user_meta, propre à chaque fichier, contrairement à fields, partagé par tous les fichiers d’une même Assembly.
• Par défaut, le téléversement est limité à huit heures à compter de la création, et le traitement à huit heures à compter de la fin du téléversement. Une limite de traitement propre au Workspace peut modifier cette seconde échéance ; le dépassement de l’une ou l’autre échéance renvoie ASSEMBLY_EXPIRED.

Une approche pratique

Quand Transloadit est utile

Utilisez Uppy avec le plugin Transloadit dans le navigateur, ou n’importe quel client tus ailleurs, et laissez /upload/handle recevoir les fichiers. Créez en premier l’Assembly avec num_expected_upload_files, puis envoyez chaque fichier à l’adresse tus_url renvoyée dans l’Assembly Status.

Périmètre architectural

La reprise permet de poursuivre un transfert interrompu, pas un transfert oublié. Par défaut, les téléversements doivent se terminer dans les huit heures suivant la création de l’Assembly, et le traitement dans les huit heures suivant la fin du téléversement. Une limite de traitement propre au Workspace peut modifier ce second délai. Après expiration, l’Assembly renvoie ASSEMBLY_EXPIRED et les octets déjà reçus ne sont plus utilisables.