Large Files

A single PUT has a ceiling. S3 rejects one above 5 GB, mobile networks drop long transfers, and a failure at 90% costs you the whole file. Multipart splits the file into parts that upload independently, in parallel, each retried on its own — and once a part has landed, it stays landed.

Nothing changes at the call site

Multipart is on by default for files at or above 100 MiB, and it does not change the API. The same code handles a 2 MB avatar and a 4 GB video:

const { uploadFiles, files, progress } = upload.videoUpload();

files holds the same S3UploadedFile objects with the same progress, uploadSpeed and eta, moving through the same status transitions. A file that went up in six hundred parts is indistinguishable from one that went up in a single PUT — deliberately, so that adding multipart cannot regress a UI that was built before it existed.

What the server needs

Nothing, in most cases. The multipart endpoints live on the same handler you already mounted, and session tokens are signed with a provider credential the server already holds — there is no new secret to configure or rotate.

Two provider-side settings do need attention, and both fail in ways that are hard to diagnose from the error alone.

[
  {
    "AllowedOrigins": ["https://your-app.com"],
    "AllowedMethods": ["GET", "PUT", "POST", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"]
  }
]

{
  "Rules": [
    {
      "ID": "abort-incomplete-multipart-uploads",
      "Status": "Enabled",
      "Filter": { "Prefix": "" },
      "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 }
    }
  ]
}

Tuning

const { uploadFiles } = upload.videoUpload({
  multipart: {
    threshold: 50 * 1024 * 1024, // split above 50 MB (default 100 MiB)
    partSize: 10 * 1024 * 1024, // 10 MB parts (default 5 MiB)
    concurrency: 6, // parts in flight (default 4)
    maxAttempts: 5, // attempts per part (default 3)
  },
});

enabled: false is an opt-out from multipart as an optimisation. A file above the 5 GiB single-PUT ceiling still splits, because at that size a single PUT is not a legal request — honouring the opt-out there would turn it into a rejected upload rather than a slower one.

Limits you cannot tune past

Part size is clamped to what every supported provider accepts, whatever you ask for: at least 5 MiB for any part but the last, at most 5 GiB, and at most 10,000 parts per object. A part size too small for the file is raised automatically so the part count stays legal — a 500 GB file cannot use 5 MiB parts, and pushduck adjusts rather than failing at part 10,001.

Every part is the same size except the final one. That is stricter than S3 requires and is deliberate: Cloudflare R2 rejects an upload whose non-final parts differ in size, so uniform parts are the only sizing that works everywhere.

Resuming an interrupted upload

By default, an interrupted upload restarts. Pass a store and it continues from the parts that already landed:

import { createWebStore } from "pushduck/client";

const { uploadFiles } = upload.videoUpload({
  multipart: { store: createWebStore() },
});

import AsyncStorage from "@react-native-async-storage/async-storage";
import type { UploadStore } from "pushduck/react-native";

const store: UploadStore = {
  async get(fingerprint) {
    const raw = await AsyncStorage.getItem(`upload:${fingerprint}`);
    return raw ? JSON.parse(raw) : undefined;
  },
  async set(record) {
    await AsyncStorage.setItem(
      `upload:${record.fingerprint}`,
      JSON.stringify(record)
    );
  },
  async delete(fingerprint) {
    await AsyncStorage.removeItem(`upload:${fingerprint}`);
  },
};

What resume does and does not survive

In-memory is the default, so resume survives a network drop within the same page or app session but not a reload. createWebStore() and an AsyncStorage implementation both survive the process dying.

Large files from React Native

React Native needs one extra piece. A picker gives you a file:// URI, and the portable way to turn that into bytes is fetch(uri).blob() — which reads the entire file into memory before the first part is sent. For the case multipart exists to serve, a 500 MB video, the OS kills the app first.

Supply a reader instead and only the parts in flight are resident:

import * as FileSystem from "expo-file-system";
import { createRangeChunkReader, decodeBase64 } from "pushduck/react-native";

const { uploadFiles } = useUploadRoute<AppRouter>("videoUpload", {
  multipart: {
    createChunkReader: (input, meta) =>
      "uri" in input
        ? createRangeChunkReader({
            size: meta.size,
            readRange: async (start, end) =>
              decodeBase64(
                await FileSystem.readAsStringAsync(input.uri, {
                  encoding: FileSystem.EncodingType.Base64,
                  position: start,
                  length: end - start,
                })
              ),
          })
        : undefined,
  },
});

Returning undefined falls back to the default, so the same factory handles URI assets and web File objects — one code path for a shared React Native and web codebase.

decodeBase64 is exported because every React Native file API that reads a byte range returns base64, and neither shortcut is portable: Buffer needs a polyfill, and atob only reached Hermes in React Native 0.74.

Troubleshooting

"The storage response did not expose an ETag" — the bucket's CORS configuration is missing "ExposeHeaders": ["ETag"]. See above.

InvalidPart on completion — parts were uploaded against a session that no longer matches. Almost always a stale resume record against a provider that has expired the session; it resolves on the next attempt.

Uploads are slower than a single PUT — for files near the threshold this is expected. Multipart costs three extra round trips, which is a poor trade below ~50 MB. Raise threshold.

An upload restarts from zero after a network drop — no store is configured. Resume is opt-in; see above.

Abandoned parts accumulating in the bucket — add the lifecycle rule. This is required on AWS, which never expires them.