Resumable / TUS

Large uploads shouldn't restart from zero when a connection drops. The package implements the tus 1.0.0 resumable protocol: bytes flow through the backend in chunks, each chunk is written immediately as a part on the target disk (native S3 multipart when available, else buffered part objects), and a session persists the offset so a HEAD tells the client exactly where to resume.

Configure

Resumable uploads are fully opt-in. Add uploads.resumable; its presence makes media.resumable available and, with routes.enabled, mounts the TUS endpoints. The session store is picked by name from a map built with the uploadSessions factory (each peer imported lazily, mirroring stores).

import { defineConfig, disks, stores, uploadSessions } from '@adonis-agora/media'

export default defineConfig({
  disk: 's3',
  disks: { s3: disks.s3({ bucket: 'my-bucket', region: 'us-east-1' }) },
  store: 'lucid',
  stores: { lucid: stores.lucid() },

  uploads: {
    resumable: {
      store: 'lucid',
      stores: {
        memory: uploadSessions.memory(),
        lucid: uploadSessions.lucid(), // durable, multi-process sessions
      },
      sessionTtlSeconds: 24 * 60 * 60, // TUS expiration; omit for never-expiring sessions
      routes: {
        enabled: true,
        prefix: '/media/uploads/tus',
        maxSize: 5 * 1024 ** 3,
        collection: 'exams', // enforce this collection's acceptsMimeTypes up front
      },
    },
  },
})

Rejecting the wrong file type early

acceptsMimeTypes belongs to a collection, and a collection is only known at attach time — so without help, TUS accepts any binary and the user discovers they sent the wrong file after uploading all 20 MB of it. In a protocol that exists for large files, that is the worst possible moment to say no.

Set routes.collection and the handler enforces that collection's whitelist at the two earliest points the protocol allows:

Later chunks are not sniffed: a signature lives at the head of a file or nowhere.

The collection config stays the single source of truth — you name the collection, never the MIME list, so the TUS gate and the attach-time check cannot drift apart.

Building the handler yourself (outside the provider's routes) works the same way — pass the registry, not a list:

new TusUploadHandler({
  manager: media.resumable,
  disk: media.storage.defaultDisk,
  basePath: '/media/uploads/tus',
  collection: 'exams',
  collections: media.collections,
})

The Lucid session store

configure publishes a migration for the TUS lucid store alongside the media migration. It creates two portable tables — media_upload_sessions (offset / length / metadata / expiry) and media_upload_parts (the per-part ETag side-index for assembling native S3 multipart) — with JSON as TEXT and timestamps as epoch-ms integers, so it runs on SQLite / Postgres / MySQL. Import the class from @adonis-agora/media/upload_sessions/lucid if you need it by hand.

uploadSessions.lucid({ connection?, table?, partsTable? }) — connection defaults to Lucid's default; table defaults to media_upload_sessions; partsTable defaults to media_upload_parts.

TUS protocol routes

With routes.enabled, these routes are mounted under routes.prefix (default /media/uploads/tus). The server implements the creation, termination and expiration extensions.

Storage errors map onto TUS status codes: offset conflict → 409, expired session → 410 Gone, unknown session → 404. The final object key defaults to uploads/<token>/<filename> (from the filename metadata field). That filename is validated as a single, safe path segment before it is used — a traversal attempt (../../etc/passwd) or an absolute path throws UnsafeFileNameError rather than being written somewhere unexpected.

media.resumable

The same engine is available programmatically. It throws ResumableUploadsNotConfiguredError unless uploads.resumable is configured; guard with media.hasResumable.

const session = await media.resumable.createUpload({
  disk: 's3',
  key: `users/${user.id}/video.mp4`,
  size: file.size,       // TUS Upload-Length (optional)
  contentType: 'video/mp4',
})

let { offset } = await media.resumable.writeChunk(session.id, 0, chunk1)
;({ offset } = await media.resumable.writeChunk(session.id, offset, chunk2))

await media.resumable.status(session.id) // { offset, size, expiresAt } — drives HEAD

const { key, disk, size } = await media.resumable.complete(session.id)
// await media.resumable.abort(session.id)

Turning a finished upload into a media record

complete() hands back a raw object on a disk. To make it a library asset, do not read the bytes back into library.attach() — that buffers the whole file and rewrites the object, exactly what a resumable upload exists to avoid. Register the object where it already is:

const record = await media.completeUploadToLibrary(session.id, {
  ownerType: 'Patient',
  ownerId: patient.id,
  collection: 'exams',
  fileName: 'exam.pdf',
  mimeType: 'application/pdf',
})

That is resumable.complete() followed by library.attachExisting({ ...input, key, disk, size }). It is opt-in: resumable.complete() stays the raw primitive for blobs that should not become library assets.

library.attachExisting() is the underlying primitive and works for any object already on a disk (a direct-S3 upload, a file written by a job, an import):

await media.library.attachExisting({
  ownerType: 'Patient',
  ownerId: patient.id,
  collection: 'exams',
  key: 'uploads/exam-1.pdf',   // already stored — never read, never rewritten
  disk: 's3',                  // else the collection's disk, else the default
  fileName: 'exam.pdf',
  mimeType: 'application/pdf',
  size: 1_048_576,             // optional — read from the object's metadata when omitted
})

Everything after storage matches attach(): acceptsMimeTypes, single: true atomic replace, ordering, eager conversions and agora:media:attach diagnostics. Missing key → MediaObjectMissingError. Pass moveIntoLayout: true to relocate the object into the library's ownerType/ownerId/collection/id/fileName layout — this uses the disk's native server-side move (disks.s3(); see S3 disk) and throws on a disk without one, rather than streaming the bytes through the app to fake it. Registering in place is the default.

media.resumable.list(filter?) returns in-progress sessions (optionally filtered by disk / keyPrefix) for an "uploads in progress" view — the Dashboard uses it. It returns an empty array, not an error, when the configured store can't enumerate.

media.resumable.listParts(id) goes one level deeper: every part recorded for one session, as { partNumber, etag }. On a multipart-capable disk that is the real S3 part manifest — what an operator needs to see why a stalled upload is stalled, and what the console's upload drill-in renders. A buffered session (a disk with no native multipart) has no parts to record and comes back empty.

Sessions emit agora:media:upload.* diagnostics events, captured by Telescope.

Custom session stores

An UploadSessionStore is a POJO implementing create / get / update / delete, plus optional addPart / listParts (only needed for multipart-capable disks) and an optional list (for the admin view). Wire it via an UploadSessionStoreFactory thunk in uploads.resumable.stores so any peer it needs is imported lazily.

Next steps

• Upload modes — single-shot proxy and direct-S3 uploads
• Direct sessions — browser→S3 multipart with a persisted, resumable session (no bytes through the app)
• React client — useMediaUpload({ mode: 'tus' })
• S3 disk — native multipart for resumable uploads