Multipart uploads

Upload large objects safely

Multipart uploads coordinate large object parts, reservations, completion, and cleanup.

The lifecycle binds every provider part to one authorized logical upload and verifies final bytes before quota is consumed.

Use it when objects exceed the chosen single-upload threshold or need resumable part transfer.

Requirements for Multipart uploads

• Prerequisite — A configured storage bucket and an authenticated user authorized by project RLS.
• Prerequisite — A client capable of slicing bytes and retaining returned part metadata.
• Required value — Object key, total size, content type, upload ID, unique part numbers 1–10,000, part sizes, and completion list.
• Required value — A retry policy that preserves upload and part identity.

Lifecycle

• Part numbers must be unique integers from 1 to 10,000.
• Every part is bound to the logical upload and authorization context.
• Completion verifies committed bytes and final checksum before consuming quota.
• Abort abandoned uploads; developer cleanup retries expired reservations.

const upload = await ffdb.storage.createMultipart(
  "videos", key, { sizeBytes: file.size, contentType: file.type },
);

const part = await ffdb.storage.uploadPart(
  upload, 1, firstChunk,
  { sizeBytes: firstChunk.size, contentType: file.type },
);

await ffdb.storage.completeMultipart(upload, [part], {
  sizeBytes: file.size,
  contentType: file.type,
});

Multipart uploads workflow

• 1. Initiate the logical multipart upload with final metadata.
• 2. Upload each numbered part through its short-lived authorization.
• 3. Record the returned part result exactly once.
• 4. Complete with the ordered unique part list and final metadata.
• 5. Abort or clean up abandoned uploads.

Verify multipart uploads

FFDB verifies committed bytes and checksum, finalizes metadata, and consumes the correct quota once.

Troubleshoot multipart uploads

• A part URL expires — request a new authorization for the same logical part.
• Completion reports a size/checksum mismatch — do not retry with altered metadata; reconcile parts or abort.

Continue from Multipart uploads

• Test interrupted upload recovery.
• Monitor cleanup of expired reservations.