@ultimat3/storage 29.3.2 → 30.0.0

package/src/multipart.ts

@@ -0,0 +1,119 @@
+// Single responsibility: the part arithmetic of an S3 multipart upload: the protocol's two limits
+// and the part size that follows from a ceiling, plus the optional capability a disk declares for
+// an upload in parts. No wire and no disk, so any caller may ask.
+
+import type { StorageObject } from './driver';
+
+/** S3's floor on every part but the last. */
+export const MIN_PART_BYTES = 5 * 1024 * 1024;
+/** S3's count of parts in one upload. */
+export const MAX_PARTS = 10_000;
+
+/**
+ * How much is held before a part is sent. The smallest size whose 10,000 parts still cover
+ * `maxBytes`, since what is held is what this process pays for the stream.
+ */
+export const partBytesFor = (maxBytes: number): number =>
+  Math.max(MIN_PART_BYTES, Math.ceil(maxBytes / MAX_PARTS));
+
+/** S3's ceiling on one part, and so on one part URL's signed length. */
+export const MAX_PART_BYTES = 5 * 1024 * 1024 * 1024;
+
+/** One part a disk holds for an open upload: what `listParts` answers, and what a resume reads. */
+export interface UploadedPart {
+  readonly partNumber: number;
+  /** The disk's own etag of the part. S3's is quoted MD5; the local disks' is `etagOf`. */
+  readonly etag: string;
+  readonly size: number;
+}
+
+/** A part the caller asks `completeUpload` to assemble. The etag, when given, must be the stored one. */
+export interface CompletedPart {
+  readonly partNumber: number;
+  readonly etag?: string | undefined;
+}
+
+/** One upload opened and neither completed nor aborted: what `abortStaleUploads` weighs. */
+export interface MultipartSession {
+  readonly key: string;
+  readonly uploadId: string;
+  /** ABSENT when the disk did not say, as `StorageListEntry.lastModified` is — never epoch 0. */
+  readonly initiated?: Date | undefined;
+}
+
+export interface SignPartOptions {
+  /** The part's exact size, signed: the disk stores it at no other length. */
+  readonly contentLength: number;
+  readonly expiresInMs: number;
+}
+
+/**
+ * An upload in parts, on one disk. Optional on `StorageDriver`, so a third-party driver still
+ * compiles; `grantMultipart` refuses a disk without it (`X_STORAGE_MULTIPART_UNSUPPORTED`). Every
+ * method takes a key already held to the tenant by the caller in `grant-multipart.ts`.
+ */
+export interface MultipartCapability {
+  /** Opens a session and answers its id. The object's content type travels here: a part has none. */
+  create(key: string, options: { readonly contentType: string }): Promise<string>;
+  /** A URL a browser PUTs one part to. Signs nothing about whether the upload is still open. */
+  signPart(
+    key: string,
+    uploadId: string,
+    partNumber: number,
+    options: SignPartOptions,
+  ): Promise<string>;
+  /** Ascending by part number. `X_STORAGE_UPLOAD_UNKNOWN` for a session that is not open. */
+  listParts(key: string, uploadId: string): Promise<readonly UploadedPart[]>;
+  /** Assembles `parts`, already checked against `listParts`; the object exists once it returns. */
+  complete(key: string, uploadId: string, parts: readonly UploadedPart[]): Promise<StorageObject>;
+  /** Drops the session and every part. An unknown session is already in the asked-for state. */
+  abort(key: string, uploadId: string): Promise<void>;
+  /** Every open session under `prefix`, so a sweep can reclaim what nobody finished. */
+  listUploads(prefix?: string): Promise<readonly MultipartSession[]>;
+  /**
+   * Stores one part's bytes — only on a disk that signs its own part URLs (`local`, `memory`),
+   * called by the `/_storage` PUT once the URL verified. On s3 the bytes go to the bucket.
+   */
+  receivePart?(
+    key: string,
+    uploadId: string,
+    partNumber: number,
+    bytes: Uint8Array,
+  ): Promise<UploadedPart>;
+}
+
+/**
+ * The parts asked for, held to the parts stored: each asked part is stored, in ascending order,
+ * under the stored etag when one is named, and none but the last is under S3's part floor.
+ * Answers the stored parts in the asked order, which is what `complete` assembles; `problem` names
+ * the first reason it cannot.
+ */
+export function matchParts(
+  asked: readonly CompletedPart[],
+  stored: readonly UploadedPart[],
+): { readonly parts: readonly UploadedPart[] } | { readonly problem: string } {
+  if (asked.length === 0) return { problem: 'no parts were named' };
+  const byNumber = new Map(stored.map((part) => [part.partNumber, part]));
+  const parts: UploadedPart[] = [];
+  let previous = 0;
+  for (const { partNumber, etag } of asked) {
+    if (!Number.isSafeInteger(partNumber) || partNumber <= previous) {
+      return { problem: `part ${String(partNumber)} is not in ascending order after ${previous}` };
+    }
+    const held = byNumber.get(partNumber);
+    if (held === undefined) return { problem: `part ${partNumber} never arrived` };
+    if (etag !== undefined && etag !== held.etag) {
+      return { problem: `part ${partNumber}'s etag is not the one the disk stored` };
+    }
+    parts.push(held);
+    previous = partNumber;
+  }
+  // S3's EntityTooSmall, asked on every disk so the local ones cannot complete what s3 refuses.
+  const short = parts.slice(0, -1).find((part) => part.size < MIN_PART_BYTES);
+  if (short !== undefined) {
+    return {
+      problem: `part ${short.partNumber} is ${short.size}B, under the ${MIN_PART_BYTES}B every part but the last must reach`,
+    };
+  }
+  return { parts };
+}

package/src/put-stream.ts

@@ -0,0 +1,52 @@
+// Single responsibility: what `putStream` may be handed, and the limit it pumps under. The pump itself
+// is `byte-pump.ts`, which `put()` reads through too.
+
+import { assert, describeValue, finiteCount } from '@ultimat3/core';
+import type { PumpLimit } from './byte-pump';
+import { assertPutOptions } from './driver';
+import { streamTooLarge } from './errors-stream';
+
+export interface PutStreamOptions {
+  /**
+   * Required: a stream's length is the sender's until it is counted. Past it the write is abandoned
+   * (`X_STORAGE_TOO_LARGE`) and the key is as it was. Replaces the disk's `maxPutBytes`, which bounds
+   * what `put()` buffers, and nothing here is buffered past one s3 part.
+   */
+  readonly maxBytes: number;
+  readonly contentType?: string | undefined;
+  readonly cacheControl?: string | undefined;
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+}
+
+/** `put()` options that need the bytes before the object exists. The type omits them too. */
+const NEEDS_THE_BYTES = ['checksum', 'retention', 'legalHold', 'serverSideEncryption'] as const;
+
+/** Everything judged before a chunk is read. Answers the screened `maxBytes`. */
+export function assertPutStream(
+  driver: string,
+  body: ReadableStream<Uint8Array>,
+  options: PutStreamOptions,
+): number {
+  assert(
+    body instanceof ReadableStream,
+    `putStream() on the ${driver} disk was given a body that is not a ReadableStream (${describeValue(body)})`,
+    'await disk.putStream(key, request.body, { maxBytes })   # a Uint8Array or a Blob goes through disk.put(key, bytes)',
+  );
+  const asked = (options ?? {}) as unknown as Readonly<Record<string, unknown>>;
+  for (const name of NEEDS_THE_BYTES) {
+    assert(
+      asked[name] === undefined,
+      `putStream() on the ${driver} disk was given ${name}, which needs the whole body before the object exists`,
+      `await disk.put(key, bytes, { ${name} })   # buffered, so bounded by the disk's maxPutBytes`,
+    );
+  }
+  assertPutOptions(driver, options);
+  return finiteCount(`putStream() on the ${driver} disk`, 'maxBytes', options?.maxBytes, 1);
+}
+
+/** The limit `putStream` pumps under: its own `maxBytes`, and the refusal that names it. */
+export const streamLimit = (driver: string, key: string, maxBytes: number): PumpLimit => ({
+  driver,
+  maxBytes,
+  refuse: (total) => streamTooLarge(driver, key, total, maxBytes),
+});

package/src/range.ts

@@ -0,0 +1,102 @@
+// Single responsibility: what `get(key, { range })` may ask for and what it is answered with — the
+// screen of the tuple for every disk, and for memory and local the clamp, the 416 and the ceiling
+// (which bounds the BYTES ASKED FOR, not the object). s3 learns the size from its one GET's answer
+// and applies the same three rules there (`driver-s3-range.ts`), with the same refusals.
+
+import { assert } from '@ultimat3/core';
+import { rangeTooLarge, rangeUnsatisfiable } from './errors-range';
+import { streamRangeUnsatisfiable } from './errors-stream';
+
+/**
+ * The first and the last byte, BOTH INCLUSIVE — HTTP's `Range: bytes=first-last` and S3's, so a
+ * route copies a parsed header straight in and a `Content-Range` is read straight back out.
+ * `[0, 99]` is the first hundred bytes; `[0, 0]` is one.
+ */
+export type ByteRange = readonly [first: number, last: number];
+
+export interface GetOptions {
+  /**
+   * Read only these bytes. The last byte is clamped to the object (`[0, 1e12]` on a 10-byte object
+   * answers `[0, 9]`), as HTTP clamps it; a first byte at or past the end is
+   * `X_STORAGE_RANGE_UNSATISFIABLE`, which is a 416. `maxGetBytes` bounds the RANGE'S length, so a
+   * page of a large object is readable where `get()` of the whole would be refused.
+   *
+   * Meaningless on a SEALED object: `seal()`'s `x1` envelope is one AES-GCM ciphertext whose tag
+   * authenticates every byte, so a slice of it neither opens nor means anything. Range-read plain
+   * objects; page a sealed one by sealing each page as its own object.
+   */
+  readonly range?: ByteRange | undefined;
+}
+
+const isOffset = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/**
+ * The tuple's SHAPE, before the disk is asked anything: two whole, non-negative offsets in order.
+ * Core's `assert` (`X_INVARIANT`), because a backwards or fractional range is the calling code's
+ * defect — no object makes it valid — while a first byte past the end depends on the object and
+ * is the coded, caller-facing refusal below.
+ */
+export function assertGetOptions(driver: string, options: GetOptions | undefined): void {
+  const range = options?.range;
+  if (range === undefined) return;
+  assertRange(driver, 'get()', 'get(key, { range: ', ' })', range);
+}
+
+/** The same screen for `streamRange`, naming the call that was made. */
+export function assertStreamRange(driver: string, range: ByteRange): void {
+  assertRange(driver, 'streamRange()', 'streamRange(key, ', ')', range);
+}
+
+function assertRange(
+  driver: string,
+  call: string,
+  open: string,
+  close: string,
+  range: ByteRange,
+): void {
+  const [first, last] = Array.isArray(range) ? range : [];
+  assert(
+    Array.isArray(range) && range.length === 2 && isOffset(first) && isOffset(last),
+    `${call} on the ${driver} disk was given a range that is not two whole, non-negative byte offsets`,
+    `${open}[first, last]${close} — inclusive offsets: [0, 99] reads the first 100 bytes`,
+  );
+  assert(
+    first <= last,
+    `${call} on the ${driver} disk was given the range [${first}, ${last}], whose first byte is past its last`,
+    `${open}[${last}, ${first}]${close} — first before last, both inclusive`,
+  );
+}
+
+/**
+ * The window `streamRange` serves: clamped as `servedRange` clamps. No ceiling, because nothing is
+ * buffered: the bytes asked for are the bytes pulled, and they flow at the reader's pace.
+ */
+export function streamedRange(
+  disk: string,
+  key: string,
+  range: ByteRange,
+  size: number,
+): ByteRange {
+  const [first, wanted] = range;
+  if (first >= size) throw streamRangeUnsatisfiable(disk, key, range, size);
+  return [first, Math.min(wanted, size - 1)];
+}
+
+/**
+ * The range a disk SERVES for an object of `size` bytes — clamped, refused, or over the ceiling.
+ * Called with the object's own measured size, before a byte is read, by every driver.
+ */
+export function servedRange(
+  disk: string,
+  key: string,
+  range: ByteRange,
+  size: number,
+  maxGetBytes: number,
+): ByteRange {
+  const [first, wanted] = range;
+  if (first >= size) throw rangeUnsatisfiable(disk, key, range, size);
+  const last = Math.min(wanted, size - 1);
+  if (last - first + 1 > maxGetBytes) throw rangeTooLarge(disk, key, [first, last], maxGetBytes);
+  return [first, last];
+}

package/src/signed-url.ts

@@ -4,7 +4,7 @@
 // a 2GB executable. Verification never throws and never short-circuits on expiry before the
 // signature, so a forged URL can never learn "the signature was fine, just late".
 
-import { type Clock, finiteCount, systemClock, timingSafeEqual } from '@ultimat3/core';
+import { assert, type Clock, finiteCount, systemClock, timingSafeEqual } from '@ultimat3/core';
 import type { SignedUrlMethod } from './driver';
 import { assertSafeKey, isSafeKey } from './path';
 
@@ -31,8 +31,20 @@ export const SIGNED_URL_PARAMS = {
   maxBytes: 'x-max',
   contentType: 'x-ct',
   signature: 'x-sig',
+  uploadId: 'x-upload',
+  partNumber: 'x-part',
 } as const;
 
+/** The session and part a part URL writes into — inside the signature, so neither can be edited. */
+export interface SignedPart {
+  readonly uploadId: string;
+  readonly partNumber: number;
+}
+
+/** `MAX_PARTS` restated as the parse's bound: `multipart.ts` imports this module's types. */
+const MAX_SIGNED_PART = 10_000;
+const SIGNED_UPLOAD_ID = /^[A-Za-z0-9._~-]{1,128}$/;
+
 export interface SignedUrlConstraints {
   readonly key: string;
   readonly method: SignedUrlMethod;
@@ -40,6 +52,8 @@ export interface SignedUrlConstraints {
   readonly expiresAt: number;
   readonly maxBytes: number | undefined;
   readonly contentType: string | undefined;
+  /** Present on a part URL only: a single PUT and a part are two capabilities, never one. */
+  readonly part?: SignedPart | undefined;
 }
 
 export interface SignedUrlInput {
@@ -50,6 +64,8 @@ export interface SignedUrlInput {
   readonly expiresInMs?: number | undefined;
   readonly maxBytes?: number | undefined;
   readonly contentType?: string | undefined;
+  /** Mint a part URL of an open upload (`MultipartCapability.signPart` on the local disks). */
+  readonly part?: SignedPart | undefined;
   readonly baseUrl?: string | undefined;
   readonly clock?: Clock | undefined;
 }
@@ -92,14 +108,19 @@ export function signedUrlBasePath(baseUrl: string): string {
  * origin is deliberately outside it: the verifying route is handed a path.
  */
 export function canonicalRequest(constraints: SignedUrlConstraints, basePath: string): string {
+  const part = constraints.part;
+  // A part signs under its own version line, so no single-PUT string can ever read as a part's:
+  // the two domains share no canonical form, and a single URL's bytes are what they always were.
+  const tail = part === undefined ? [] : [part.uploadId, String(part.partNumber)];
   return [
-    SIGNED_URL_VERSION,
+    part === undefined ? SIGNED_URL_VERSION : `${SIGNED_URL_VERSION}-part`,
     basePath,
     constraints.method,
     constraints.key,
     String(constraints.expiresAt),
     constraints.maxBytes === undefined ? '' : String(constraints.maxBytes),
     constraints.contentType ?? '',
+    ...tail,
   ].join('\n');
 }
 
@@ -163,6 +184,7 @@ export async function buildSignedUrl(input: SignedUrlInput): Promise<string> {
     // one while `acceptSignedUpload`'s `unconstrained` refusal (which tests `undefined`) stayed
     // silent. One spelling for "no content type", here and at the parse below.
     contentType: input.contentType === '' ? undefined : input.contentType,
+    ...(input.part === undefined ? {} : { part: assertSignedPart(input.part) }),
   };
   const params = new URLSearchParams();
   params.set(SIGNED_URL_PARAMS.method, constraints.method);
@@ -173,6 +195,10 @@ export async function buildSignedUrl(input: SignedUrlInput): Promise<string> {
   if (constraints.contentType !== undefined) {
     params.set(SIGNED_URL_PARAMS.contentType, constraints.contentType);
   }
+  if (constraints.part !== undefined) {
+    params.set(SIGNED_URL_PARAMS.uploadId, constraints.part.uploadId);
+    params.set(SIGNED_URL_PARAMS.partNumber, String(constraints.part.partNumber));
+  }
   const base = trimBase(input.baseUrl ?? DEFAULT_SIGNED_URL_BASE);
   params.set(
     SIGNED_URL_PARAMS.signature,
@@ -232,15 +258,46 @@ function parseConstraints(url: URL, base: string): SignedUrlConstraints | Signed
   // An EMPTY `x-ct` is malformed, never "no content type": absent and empty share one canonical
   // string, so accepting it let `&x-ct=` be appended to a URL signed with none and still verify.
   if (rawContentType === '') return 'malformed';
+  const part = parsePart(url);
+  if (part === 'malformed') return part;
   return {
     key,
     method,
     expiresAt,
     maxBytes,
     contentType: rawContentType ?? undefined,
+    ...(part === undefined ? {} : { part }),
   };
 }
 
+const isSignedPart = (part: SignedPart): boolean =>
+  SIGNED_UPLOAD_ID.test(part.uploadId) &&
+  Number.isSafeInteger(part.partNumber) &&
+  part.partNumber >= 1 &&
+  part.partNumber <= MAX_SIGNED_PART;
+
+/** The mint's screen: a part this module could not parse back is a URL dead on arrival. */
+function assertSignedPart(part: SignedPart): SignedPart {
+  assert(
+    isSignedPart(part),
+    `buildSignedUrl was handed a part that is not an upload id and a part number 1..${MAX_SIGNED_PART}`,
+    "buildSignedUrl({ secret, key, method: 'PUT', part: { uploadId: crypto.randomUUID(), partNumber: 1 } })",
+  );
+  return { uploadId: part.uploadId, partNumber: part.partNumber };
+}
+
+/** Both parameters or neither; one alone is a URL this module never minted. */
+function parsePart(url: URL): SignedPart | 'malformed' | undefined {
+  const uploadId = url.searchParams.get(SIGNED_URL_PARAMS.uploadId);
+  const rawNumber = url.searchParams.get(SIGNED_URL_PARAMS.partNumber);
+  if (uploadId === null && rawNumber === null) return undefined;
+  if (uploadId === null || rawNumber === null || !/^[1-9][0-9]{0,4}$/.test(rawNumber)) {
+    return 'malformed';
+  }
+  const part = { uploadId, partNumber: Number(rawNumber) };
+  return isSignedPart(part) ? part : 'malformed';
+}
+
 export async function verifySignedUrl(input: VerifySignedUrlInput): Promise<SignedUrlVerification> {
   let url: URL;
   try {

package/src/subject-target.ts

@@ -0,0 +1,82 @@
+// `storageSubjectTarget(disk, keysOf)`: the subject's stored objects as a subject target a
+// `defineSubject({ targets })` lists — structural, so `@ultimat3/jobs` imports nothing from here.
+// Which keys are the person's is the app's (`keysOf`); the export lists each object, the erase
+// deletes them. A key the app does not name is not found: there is no listing by owner.
+
+import type { StorageDriver } from './driver';
+
+/** The subject as a target is handed it: the key asked for, and the subject's row read fresh. */
+export interface StorageSubjectRef {
+  readonly key: string;
+  readonly row: Readonly<Record<string, unknown>>;
+}
+
+export interface StorageSubjectTargetOptions {
+  /** The step key and export folder. Default `storage`. Unique among one subject's targets. */
+  readonly name?: string;
+}
+
+type Cell = string | number | boolean | null;
+
+export interface StorageSubjectTarget {
+  readonly name: string;
+  readonly columns: readonly string[];
+  exportPage(
+    subject: StorageSubjectRef,
+    cursor: string | null,
+    size: number,
+  ): Promise<{
+    readonly rows: readonly Readonly<Record<string, Cell>>[];
+    readonly cursor: string | null;
+  }>;
+  erase(subject: StorageSubjectRef, size: number): Promise<number>;
+}
+
+export const STORAGE_SUBJECT_COLUMNS = ['key', 'size', 'contentType', 'lastModified'] as const;
+
+/**
+ * `disk` is a THUNK, read per call, as an export's sink is: a subject is declared at import and
+ * the app's disks exist after `defineStorage()`.
+ */
+export function storageSubjectTarget(
+  disk: () => StorageDriver,
+  /** The person's keys — a list the app builds, or lists from a prefix it owns. */
+  keysOf: (subject: StorageSubjectRef) => readonly string[] | Promise<readonly string[]>,
+  options: StorageSubjectTargetOptions = {},
+): StorageSubjectTarget {
+  return {
+    name: options.name ?? 'storage',
+    columns: STORAGE_SUBJECT_COLUMNS,
+    async exportPage(subject, cursor, size) {
+      const keys = await keysOf(subject);
+      const start = cursor === null ? 0 : Number(cursor);
+      const page = keys.slice(start, start + size);
+      const rows: Record<string, Cell>[] = [];
+      for (const key of page) {
+        const found = await disk().stat(key);
+        if (found === undefined) continue;
+        rows.push({
+          key,
+          size: found.size,
+          contentType: found.contentType,
+          // An instant, UTC, its zone in the string — never formatted for a locale here. Absent
+          // when the provider sent none, and never invented.
+          lastModified: found.lastModified?.toISOString() ?? null,
+        });
+      }
+      const next = start + page.length;
+      return { rows, cursor: next < keys.length ? String(next) : null };
+    },
+    async erase(subject, size) {
+      // Only what still exists counts, so a replayed batch answers short and the loop ends.
+      let removed = 0;
+      for (const key of await keysOf(subject)) {
+        if (removed >= size) break;
+        if (!(await disk().exists(key))) continue;
+        await disk().delete(key);
+        removed += 1;
+      }
+      return removed;
+    },
+  };
+}

package/src/upload-client-multipart.ts

@@ -0,0 +1,156 @@
+// Single responsibility: the browser half of an upload in parts — grant (or resume), PUT each part
+// at its own signed URL with bounded concurrency and core's retry, then complete. Browser-safe as
+// `upload-client.ts` is: no `Bun.*`, no `node:`, no driver import, and every network call is either
+// the app's typed action or the one `SignedPut` seam.
+
+import { finiteCount, retry } from '@ultimat3/core';
+import { uploadFailed } from './errors';
+import type { UploadRequest } from './grant';
+import type { MultipartGrant } from './grant-multipart';
+import type { CompletedPart, UploadedPart } from './multipart';
+import type { SignedPut, UploadProgress, UploadSource } from './upload-client';
+
+/** One open session, as each of the app's calls names it. */
+export interface UploadSessionRef {
+  readonly key: string;
+  readonly uploadId: string;
+}
+
+/**
+ * The app's typed action calls, each wrapping one server function of `grant-multipart.ts` under the
+ * app's own policy — the reason `grant` is the app's in `uploadFile`.
+ */
+export interface MultipartUploadClient {
+  readonly grant: (request: UploadRequest) => Promise<MultipartGrant>;
+  readonly signPart: (
+    input: UploadSessionRef & { readonly partNumber: number; readonly size: number },
+  ) => Promise<string>;
+  readonly listParts: (input: UploadSessionRef) => Promise<readonly UploadedPart[]>;
+  /** Etags are read on the server (`completeUpload`), so no bucket CORS has to expose `ETag`. */
+  readonly complete: (
+    input: UploadSessionRef & { readonly parts: readonly CompletedPart[] },
+  ) => Promise<unknown>;
+  /** Called when the caller's `signal` aborts: a cancelled upload leaves no parts billing. */
+  readonly abort: (input: UploadSessionRef) => Promise<unknown>;
+  /** At or under this, one PUT as before. Default 64 MiB. */
+  readonly partThresholdBytes?: number | undefined;
+  /**
+   * A grant from an earlier, interrupted call for the same file: its parts are listed first and only
+   * the missing ones are sent. Persisting it is the caller's — this file keeps no browser storage.
+   */
+  readonly resume?: MultipartGrant | undefined;
+  /** Handed the grant before any part moves, so the caller can persist it for `resume`. */
+  readonly onGrant?: ((grant: MultipartGrant) => void) | undefined;
+  /** Test seam for the retry waits. Defaults to a timer. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+
+export const DEFAULT_PART_THRESHOLD_BYTES = 64 * 1024 * 1024;
+/** Parts in flight at once: enough to fill a phone's uplink, few enough to keep its memory. */
+export const PART_CONCURRENCY = 4;
+const PART_RETRY = { attempts: 4, base: 500, max: 8_000, jitter: 'full' } as const;
+
+export const partThresholdOf = (client: MultipartUploadClient): number =>
+  finiteCount(
+    'uploadFile',
+    'multipart.partThresholdBytes',
+    client.partThresholdBytes === undefined
+      ? DEFAULT_PART_THRESHOLD_BYTES
+      : client.partThresholdBytes,
+    1,
+  );
+
+export interface MultipartUploadInput {
+  readonly file: UploadSource;
+  readonly client: MultipartUploadClient;
+  readonly put: SignedPut;
+  readonly onProgress?: ((progress: UploadProgress) => void) | undefined;
+  readonly signal?: AbortSignal | undefined;
+}
+
+/** A grant for this file, or the resumed one; a resume for another size is a different file. */
+async function sessionFor(input: MultipartUploadInput): Promise<MultipartGrant> {
+  const { file, client } = input;
+  const resumed = client.resume;
+  if (resumed !== undefined && resumed.size === file.size) return resumed;
+  const grant = await client.grant({
+    filename: file.name,
+    contentType: file.type,
+    size: file.size,
+  });
+  client.onGrant?.(grant);
+  return grant;
+}
+
+/** Send every part not yet on the disk, then complete. Answers the grant the object landed under. */
+export async function uploadInParts(input: MultipartUploadInput): Promise<MultipartGrant> {
+  const { file, client, put, signal } = input;
+  const grant = await sessionFor(input);
+  const session = { key: grant.key, uploadId: grant.uploadId };
+  const total = file.size;
+  const count = Math.ceil(total / grant.partBytes);
+  const landed = client.resume === grant ? await client.listParts(session) : [];
+  const have = new Set(
+    landed
+      .filter(
+        (part) =>
+          part.size === Math.min(grant.partBytes, total - (part.partNumber - 1) * grant.partBytes),
+      )
+      .map((part) => part.partNumber),
+  );
+  let confirmed = landed
+    .filter((part) => have.has(part.partNumber))
+    .reduce((sum, part) => sum + part.size, 0);
+  input.onProgress?.({ loaded: confirmed, total, ratio: total > 0 ? confirmed / total : 0 });
+
+  const missing: number[] = [];
+  for (let number = 1; number <= count; number += 1) if (!have.has(number)) missing.push(number);
+
+  const cancelled = () => uploadFailed(grant.key, 0, 'the upload was aborted');
+  // A rejected wait ends core's retry loop with that error: a cancelled upload stops retrying.
+  const waitUnlessAborted = (ms: number): Promise<void> =>
+    signal?.aborted === true
+      ? Promise.reject(cancelled())
+      : (client.sleep ?? ((wait) => new Promise<void>((done) => setTimeout(done, wait))))(ms);
+
+  const sendPart = async (partNumber: number): Promise<void> => {
+    const start = (partNumber - 1) * grant.partBytes;
+    const body = file.slice(start, Math.min(start + grant.partBytes, total));
+    await retry(
+      async () => {
+        const url = await client.signPart({ ...session, partNumber, size: body.size });
+        await put({
+          url,
+          contentType: grant.contentType,
+          body,
+          ...(signal === undefined ? {} : { signal }),
+        });
+      },
+      PART_RETRY,
+      { sleep: waitUnlessAborted },
+    );
+    confirmed += body.size;
+    input.onProgress?.({ loaded: confirmed, total, ratio: total > 0 ? confirmed / total : 0 });
+  };
+
+  const worker = async (): Promise<void> => {
+    for (let next = missing.shift(); next !== undefined; next = missing.shift()) {
+      if (signal?.aborted === true) return;
+      await sendPart(next);
+    }
+  };
+  try {
+    await Promise.all(Array.from({ length: Math.min(PART_CONCURRENCY, missing.length) }, worker));
+    if (signal?.aborted === true) throw cancelled();
+  } catch (error) {
+    // Cancelled is abandoned: the parts are dropped now rather than billing until a sweep. Any
+    // other failure keeps the session open, so the same grant passed as `resume` sends only what
+    // is missing. A refused abort is the sweep's to reclaim (`abortStaleUploads`), and the
+    // caller hears the failure that stopped the upload, not the clean-up's.
+    if (signal?.aborted === true) await client.abort(session).catch(() => undefined);
+    throw error;
+  }
+  const parts = Array.from({ length: count }, (_, at) => ({ partNumber: at + 1 }));
+  await client.complete({ ...session, parts });
+  return grant;
+}