Uploads & multipart

Small files are easy — multipart/form-data, one request, done. Large files are where upload code earns its keep: a 500 MB video shouldn't restart from zero because a phone changed cell towers, and it shouldn't necessarily stream every byte through your Node event loop either. media does both shapes, and the choice is always yours to override.

The two paths

proxy — bytes flow through your NestJS backend in chunks via a real tus 1.0.0 server. The upload is resumable: a dropped connection continues from the last acknowledged offset instead of starting over. Works on any disk (even local), and because the bytes pass through you, it's where you'd virus-scan, watermark, or transform on the way in.

direct — the backend only orchestrates; the browser uploads chunks straight to the storage backend using presigned S3 multipart. Your server never sees the bytes, so it never becomes the bandwidth bottleneck. This is the right default at scale, but it requires a disk that can presign.

uploadMode: choosing per upload

resolveUploadMode decides, reading the driver's capabilities:

type UploadMode = 'auto' | 'proxy' | 'direct';

• auto (default) → direct when the driver is presign/multipart-capable (S3), otherwise proxy (local). The sensible default for most apps: scale where you can, proxy where you can't.
• proxy → always allowed; every driver can accept bytes through put.
• direct → throws on a driver that can't presign, rather than silently degrading.

Resolution is most-specific-wins:

per-call  ▸  per-disk  ▸  global  ▸  auto

Resumable (tus) server

Enable the proxy path by giving the module an upload session store, and mount the tus controller with the tus option:

import { InMemoryUploadSessionStore } from '@dudousxd/nestjs-media-testing';

MediaModule.forRoot({
  default: 'local',
  disks: { local },
  uploadSessions: new InMemoryUploadSessionStore(), // or your own UploadSessionStore
  uploadTmpPrefix: '.uploads',                       // where in-progress chunks live (default)
  tus: { disk: 'local', basePath: '/media/uploads', maxSize: 100 * 1024 * 1024 },
});

import express from 'express';
app.use('/media/uploads', express.raw({ type: 'application/offset+octet-stream', limit: '50mb' }));

import { uploadMedia } from '@dudousxd/nestjs-media-client';

const { location } = await uploadMedia(file, {
  filename: file.name,
  contentType: file.type,
  basePath: '/media/uploads',
  onProgress: (sent, total) => setPct(sent / total),
});

What the server does

On POST it creates a session (reading Upload-Length and Upload-Metadata), on PATCH it appends a chunk at the declared Upload-Offset (returning the new offset, or 409 on mismatch, 415 on the wrong content type), and when the offset reaches the declared length it assembles the parts into the final object automatically. HEAD reports the current offset so a client can resume; DELETE aborts and cleans up.

The engine underneath

Both the HTTP handler and the browser client sit on top of ResumableUploadManager (framework-agnostic):

const session = await media.uploads.createUpload({ disk: 's3', key: 'videos/clip.bin', size });
await media.uploads.writeChunk(session.id, 0, chunkA);   // → { offset }
await media.uploads.writeChunk(session.id, offset, chunkB);
const { key } = await media.uploads.complete(session.id); // assembles + cleans up parts
// media.uploads.status(id) to resume; media.uploads.abort(id) to cancel

Each chunk is written immediately as a part on the target disk (under uploadTmpPrefix), so resuming needs no in-memory buffering and a half-finished upload survives a process restart. complete concatenates the parts into the final object and removes them. Reach media.uploads directly when you want to drive uploads from your own protocol or a non-HTTP transport.

Direct (presigned multipart) server

The direct path inverts the data flow: the browser PUTs each part straight to S3 against a presigned URL, and your backend only orchestrates — it never sees a byte. Enable it with the direct option (it needs a presign/multipart-capable disk, i.e. S3):

MediaModule.forRoot({
  default: 's3',
  disks: { s3 },
  direct: {
    disk: 's3',
    partSize: 8 * 1024 * 1024, // optional, default 8 MiB
  },
});

This mounts MediaDirectUploadController at media/uploads/direct and provides DirectUploadManager as media.directUploads. The lifecycle is four calls:

initiate takes { key, contentType?, size?, partSize?, disk? }. When size is known it returns ceil(size / partSize) presigned part URLs up front; otherwise it returns a single URL and you mint the rest on demand via the parts endpoint. Presigned URLs expire after presignExpirySeconds (default 3600). No raw-body parser is needed — the bytes never touch Nest.

The engine underneath

Both the controller and any custom transport sit on DirectUploadManager (framework-agnostic, also reachable as media.directUploads):

const { uploadId, parts, partSize } = await media.directUploads.createUpload({
  disk: 's3', key: 'videos/clip.mp4', contentType: 'video/mp4', size,
}); // parts: [{ partNumber, url }, …]

// browser PUTs each part to its url, collects the returned ETag, then:
await media.directUploads.completeUpload({
  key: 'videos/clip.mp4', uploadId,
  parts: [{ partNumber: 1, etag: '"abc…"' }, /* … */],
});
// media.directUploads.abortUpload({ key, uploadId }) to cancel

createUpload throws UnsupportedOperationError if the target disk can't presign multipart — so forcing direct fails loudly rather than silently degrading.