@ultimat3/storage 29.3.2 → 30.0.0

package/src/driver-s3-signed.ts

@@ -1,5 +1,5 @@
 // Single responsibility: the s3 disk's SIGNED requests — the ones `Bun.S3Client` has no option for
-// (`x-amz-meta-*`, `Cache-Control`, `x-amz-object-lock-*`, `?retention`, `?legal-hold`) — built,
+// (`x-amz-meta-*`, `Cache-Control`, object lock, a ranged GET read off its own `Content-Range`) — built,
 // signed through core's one SigV4 signer and sent with `fetch`. The endpoint, the addressing style,
 // the region and the credentials are read from the SAME `S3DriverOptions` the Bun client is built
 // from, so the two transports of one disk cannot point at two buckets.
@@ -9,9 +9,11 @@ import {
   type Clock,
   ConfigInvalidError,
   EnvMissingError,
+  presignAwsUrl,
   signAwsRequest,
   systemClock,
 } from '@ultimat3/core';
+import type { SignedPart } from './signed-url';
 
 /** The slice of `fetch` this file uses; injected in tests so no socket is ever opened. */
 export type S3FetchLike = (
@@ -51,10 +53,12 @@ export interface S3Refusal {
 }
 
 export interface S3SignedRequest {
-  readonly method: 'GET' | 'PUT';
+  readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE';
   readonly key: string;
   /** A sub-resource such as `retention` — sent and signed as `?retention=`. */
   readonly subresource?: string | undefined;
+  /** Query parameters of a multipart call, signed. An empty value is sent as `uploads=`. */
+  readonly query?: Readonly<Record<string, string>> | undefined;
   readonly headers?: Readonly<Record<string, string>> | undefined;
   readonly body?: Uint8Array | undefined;
 }
@@ -122,6 +126,61 @@ export function resolveS3Target(options: S3WireOptions): S3Target {
   };
 }
 
+/**
+ * A PUT URL that signs its `content-length`, which is what `Bun.S3Client.presign` has no option for.
+ * The provider recomputes the signature from the header the browser really sent, so the only body
+ * this URL lands is one of exactly `contentLength` bytes. A browser sets that header itself.
+ */
+export async function presignBoundPut(
+  options: S3WireOptions,
+  key: string,
+  contentLength: number,
+  expiresInSeconds: number,
+  part?: SignedPart | undefined,
+): Promise<string> {
+  const url = s3ObjectUrl(options, key);
+  // A part of an open upload: S3's own UploadPart, its two parameters inside the signature.
+  if (part !== undefined) {
+    url.searchParams.set('partNumber', String(part.partNumber));
+    url.searchParams.set('uploadId', part.uploadId);
+  }
+  const presigned = await presignAwsUrl({
+    method: 'PUT',
+    url,
+    expiresInSeconds,
+    headers: { 'content-length': String(contentLength) },
+    credentials: s3Credentials(options),
+    region: signingRegion(options),
+    service: 's3',
+    clock: options.clock ?? systemClock,
+  });
+  return presigned.url;
+}
+
+/** The labels between `s3.` and `.amazonaws.com` of an AWS host: its region, or none. */
+const AWS_HOST = /(?:^|\.)s3\.(?:(.+)\.)?amazonaws\.com$/i;
+const REGION = /^[a-z0-9-]{1,64}$/;
+
+/**
+ * The region a request is signed for, as `Bun.S3Client` derives it, measured on Bun 1.4.4 so the
+ * disk's two transports sign alike: a region set wins; no endpoint is AWS's `us-east-1`; an AWS host
+ * `s3.<region>.amazonaws.com` is that region, bare `s3.amazonaws.com` is `us-east-1`; any other host
+ * is `auto` (R2, a gateway). One deviation: Bun reads `s3.dualstack.<region>` as the whole
+ * `dualstack.<region>`, which is no region, and this reads the region.
+ */
+export function signingRegion(options: S3WireOptions): string {
+  const { region, endpoint } = resolveS3Target(options);
+  if (region !== undefined) return region;
+  if (endpoint === undefined) return 'us-east-1';
+  const host = URL.canParse(endpoint) ? new URL(endpoint).hostname : '';
+  const match = AWS_HOST.exec(host);
+  if (match === null) return 'auto';
+  const named = match[1];
+  if (named === undefined) return 'us-east-1';
+  const last = named.split('.').at(-1) ?? '';
+  return REGION.test(named) ? named : REGION.test(last) ? last : 'auto';
+}
+
 /** Read lazily, at the first signed request — importing or constructing the disk reads nothing. */
 export function s3Credentials(options: S3WireOptions): AwsCredentials {
   const env = options.env ?? process.env;
@@ -153,7 +212,10 @@ export function s3ObjectUrl(options: S3WireOptions, key: string): URL {
   );
 }
 
-const XML_FIELD = (name: string): RegExp => new RegExp(`<${name}>([^<]{0,512})</${name}>`);
+// Uncapped: a key is up to 1,024 bytes and S3 escapes it (`&` is `&amp;`), so a 512-character
+// cap dropped a long key's session from `listS3Uploads` and ended its paging at a long
+// `NextKeyMarker`. `[^<]*` stops at the next tag, so the match stays linear with no cap.
+const XML_FIELD = (name: string): RegExp => new RegExp(`<${name}>([^<]*)</${name}>`);
 
 /** The first `<name>…</name>` of an S3 XML answer — the shapes read here are flat and fixed. */
 export function xmlField(xml: string, name: string): string | undefined {
@@ -189,6 +251,9 @@ export async function sendSigned(
   }
   const url = s3ObjectUrl(options, request.key);
   if (request.subresource !== undefined) url.search = `${request.subresource}=`;
+  for (const [name, value] of Object.entries(request.query ?? {})) {
+    url.searchParams.set(name, value);
+  }
   const signed = await signAwsRequest({
     method: request.method,
     url,
@@ -197,7 +262,7 @@ export async function sendSigned(
     // refuse a body that changed in flight; a read has none.
     payload: { body: request.body ?? new Uint8Array() },
     credentials: s3Credentials(options),
-    region: resolveS3Target(options).region ?? 'auto',
+    region: signingRegion(options),
     service: 's3',
     clock: options.clock ?? systemClock,
   });

package/src/driver-s3-sse.ts

@@ -0,0 +1,29 @@
+// Single responsibility: the one `put()` option the s3 disk cannot honour, refused by name with the
+// bucket-wide command that does the job instead.
+
+import { NotImplementedError, renderFixLiteral, renderFixShellArg } from '@ultimat3/core';
+import type { PutOptions } from './driver';
+
+/**
+ * Everything `put()` may be handed that this driver cannot honour, refused before a byte moves.
+ * A typed refusal at the call site is the whole point: `serverSideEncryption` exists on
+ * `PutOptions` so that "this disk cannot prove per-object encryption" is something an engineer
+ * meets while writing the call, not while answering a security review.
+ */
+export function refuseUnsupportedPut(bucket: string, putOptions?: PutOptions): void {
+  const sse = putOptions?.serverSideEncryption;
+  if (sse === undefined) return;
+  // The key id is the caller's own option, spliced into single-quoted JSON: `renderFixLiteral`
+  // escapes the `"` and `\` JSON needs, and a `'` — the one byte live inside single quotes — makes
+  // it the placeholder rather than ending the argument (plan 101 row S12).
+  const keyId = sse.kmsKeyId?.includes("'") === false ? sse.kmsKeyId : undefined;
+  const bucketArg = renderFixShellArg(bucket, "'<bucket>'");
+  throw new NotImplementedError({
+    cause:
+      'per-object server-side encryption on the s3 driver (Bun.S3Client exposes acl, storageClass and type, and nothing for x-amz-server-side-encryption) is not implemented by this driver — set it bucket-wide with the command in fix, then drop serverSideEncryption from put()',
+    fix:
+      sse.algorithm === 'aws:kms'
+        ? `aws s3api put-bucket-encryption --bucket ${bucketArg} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":${renderFixLiteral(keyId, '"<key-arn>"')}},"BucketKeyEnabled":true}]}'`
+        : `aws s3api put-bucket-encryption --bucket ${bucketArg} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"},"BucketKeyEnabled":true}]}'`,
+  });
+}

package/src/driver-s3.ts

@@ -8,16 +8,15 @@ import {
   type Clock,
   finiteCount,
   isUltimateError,
-  NotImplementedError,
   type Page,
   pageOf,
-  renderFixLiteral,
   renderFixShellArg,
   systemClock,
 } from '@ultimat3/core';
 import {
   assertListOptions,
   assertPutOptions,
+  type CopyOptions,
   DEFAULT_CONTENT_TYPE,
   type ListOptions,
   type PutOptions,
@@ -32,10 +31,17 @@ import {
   toBytes,
 } from './driver';
 import { isAbsentObject } from './driver-s3-absent';
-import { buildClient, type S3ClientLike, type S3ListResultLike } from './driver-s3-client';
+import { buildClient, dated, type S3ClientLike, type S3ListResultLike } from './driver-s3-client';
+import { signedCopy } from './driver-s3-copy';
 import { needsSignedPut, readObjectLock, signedPut } from './driver-s3-lock';
+import { s3Multipart } from './driver-s3-multipart-session';
+import { s3SignedUrl } from './driver-s3-presign';
+import { putS3Stream } from './driver-s3-put-stream';
+import { readS3Range } from './driver-s3-range';
 import { regionMismatch } from './driver-s3-region';
+import { settleLostPut } from './driver-s3-settle';
 import type { S3FetchLike } from './driver-s3-signed';
+import { refuseUnsupportedPut } from './driver-s3-sse';
 import {
   checksumMismatch,
   deleteFailed,
@@ -46,9 +52,17 @@ import {
   putFailed,
   readFailed,
 } from './errors';
+import { objectChanged } from './errors-promote';
 import { assertObjectLockOptions, type ObjectLock } from './object-lock';
 import { assertSafeKey } from './path';
-import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
+import { assertPutStream, type PutStreamOptions } from './put-stream';
+import {
+  assertGetOptions,
+  assertStreamRange,
+  type ByteRange,
+  type GetOptions,
+  streamedRange,
+} from './range';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
 const DRIVER_NAME = 's3';
@@ -90,44 +104,13 @@ export interface S3DriverOptions {
    */
   readonly maxPutBytes?: number | undefined;
   /**
-   * Ceiling on ONE `get()`, because `get()` buffers the whole object — and on this disk nothing
-   * bounds what a presigned PUT stored (`SignedUrlOptions.maxBytes`). Defaults to `maxPutBytes`;
-   * an object past it is read with `stream()`.
+   * Ceiling on ONE `get()`, because `get()` buffers the whole object — and a URL signed with no
+   * `contentLength` bounds nothing it stored. Defaults to `maxPutBytes`; an object past it is read
+   * with `stream()`.
    */
   readonly maxGetBytes?: number | undefined;
 }
 
-/**
- * A missing `LastModified` is ABSENT, never `new Date(0)`: epoch 0 is older than every window, so
- * `sweepOrphans` deleted an upload on the strength of a field the provider never sent.
- */
-const dated = (value: string | Date | undefined): { readonly lastModified?: Date } =>
-  value === undefined ? {} : { lastModified: value instanceof Date ? value : new Date(value) };
-
-/**
- * Everything `put()` may be handed that this driver cannot honour, refused before a byte moves.
- * A typed refusal at the call site is the whole point: `serverSideEncryption` exists on
- * `PutOptions` so that "this disk cannot prove per-object encryption" is something an engineer
- * meets while writing the call, not while answering a security review.
- */
-function refuseUnsupportedPut(bucket: string, putOptions?: PutOptions): void {
-  const sse = putOptions?.serverSideEncryption;
-  if (sse === undefined) return;
-  // The key id is the caller's own option, spliced into single-quoted JSON: `renderFixLiteral`
-  // escapes the `"` and `\` JSON needs, and a `'` — the one byte live inside single quotes — makes
-  // it the placeholder rather than ending the argument (plan 101 row S12).
-  const keyId = sse.kmsKeyId?.includes("'") === false ? sse.kmsKeyId : undefined;
-  const bucketArg = renderFixShellArg(bucket, "'<bucket>'");
-  throw new NotImplementedError({
-    cause:
-      'per-object server-side encryption on the s3 driver (Bun.S3Client exposes acl, storageClass and type, and nothing for x-amz-server-side-encryption) is not implemented by this driver — set it bucket-wide with the command in fix, then drop serverSideEncryption from put()',
-    fix:
-      sse.algorithm === 'aws:kms'
-        ? `aws s3api put-bucket-encryption --bucket ${bucketArg} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":${renderFixLiteral(keyId, '"<key-arn>"')}},"BucketKeyEnabled":true}]}'`
-        : `aws s3api put-bucket-encryption --bucket ${bucketArg} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"},"BucketKeyEnabled":true}]}'`,
-  });
-}
-
 export function s3Driver(options: S3DriverOptions): StorageDriver {
   // `=== undefined`, never `??`: `??` coalesces on `null` too, so an explicitly blanked key in a
   // decoded JSON config took the default instead of the refusal `finiteCount` is here to raise.
@@ -214,7 +197,12 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     };
   };
 
-  return {
+  /** The HEAD a lost write's answer is settled against, and the `.catch` of a single PUT. */
+  const statOf = async (key: string) => ((await present(key)) ? statObject(key) : undefined);
+  const lostPut = (key: string, bytes: Uint8Array, attributes: PutOptions | undefined) =>
+    settleLostPut(statOf, { driver: DRIVER_NAME, key, bytes, attributes }, refusedWrite(key));
+
+  const disk: StorageDriver = {
     name: DRIVER_NAME,
     registerAs(name: string): void {
       diskName = name;
@@ -238,7 +226,9 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       if (putOptions !== undefined && needsSignedPut(putOptions)) {
         // Off the Bun client only for what it cannot send: `S3File.write` takes a type, an ACL and
         // a storage class and no header. One request either way — never a PUT then a second call.
-        const refusal = await signedPut(options, safe, bytes, putOptions).catch(refusedWrite(safe));
+        const refusal = await signedPut(options, safe, bytes, putOptions).catch(
+          lostPut(safe, bytes, putOptions),
+        );
         if (refusal !== undefined) refusedWrite(safe)(refusal);
         // Stored — the PUT succeeded with them — so reported, as the local disk reports its own.
         return {
@@ -252,17 +242,66 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       await conn()
         .file(safe)
         .write(bytes, { type: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE })
-        .catch(refusedWrite(safe));
+        .catch(lostPut(safe, bytes, putOptions));
       return statObject(safe);
     },
 
+    async putStream(
+      key: string,
+      body: ReadableStream<Uint8Array>,
+      streamOptions: PutStreamOptions,
+    ): Promise<StorageObject> {
+      const safe = assertSafeKey(key);
+      const maxBytes = assertPutStream(DRIVER_NAME, body, streamOptions);
+      await putS3Stream(options, {
+        key: safe,
+        body,
+        options: streamOptions,
+        maxBytes,
+        driver: DRIVER_NAME,
+        refused: refusedWrite(safe),
+        stat: statOf,
+      }).catch(refusedWrite(safe));
+      return {
+        ...(await statObject(safe)),
+        ...(streamOptions.cacheControl === undefined
+          ? {}
+          : { cacheControl: streamOptions.cacheControl }),
+        ...(streamOptions.metadata === undefined
+          ? {}
+          : { metadata: { ...streamOptions.metadata } }),
+      };
+    },
+
     async stat(key: string): Promise<StorageObject | undefined> {
       const safe = assertSafeKey(key);
       return (await present(safe)) ? statObject(safe) : undefined;
     },
 
-    async get(key: string): Promise<StorageRead> {
+    async get(key: string, getOptions?: GetOptions): Promise<StorageRead> {
       const safe = assertSafeKey(key);
+      assertGetOptions(DRIVER_NAME, getOptions);
+      const range = getOptions?.range;
+      // ONE signed GET, bytes and description from the same response (`driver-s3-range.ts`).
+      if (range !== undefined) {
+        return readS3Range(options, safe, range, {
+          driver: DRIVER_NAME,
+          maxGetBytes,
+          refused: (key, refusal) => refusedRead(key)(refusal),
+          sizeOf: async (key) => {
+            if (!(await present(key))) throw objectNotFound(diskName, key);
+            return (await statObject(key)).size;
+          },
+          unreadable: (key, why) => {
+            throw readFailed(
+              DRIVER_NAME,
+              key,
+              why,
+              `aws s3api get-object --bucket ${renderFixShellArg(options.bucket, "'<bucket>'")} --key ${renderFixShellArg(key, "'<key>'")} --range bytes=0-0 /dev/null   # what the provider answers a ranged GET`,
+            );
+          },
+        });
+      }
       const file = conn().file(safe);
       if (!(await present(safe))) throw objectNotFound(diskName, safe);
       // The HEAD comes FIRST, and it is the whole point: a client PUT straight into the bucket is
@@ -281,6 +320,20 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       return file.stream();
     },
 
+    async streamRange(key: string, range: ByteRange): Promise<ReadableStream<Uint8Array>> {
+      const safe = assertSafeKey(key);
+      assertStreamRange(DRIVER_NAME, range);
+      if (!(await present(safe))) throw objectNotFound(diskName, safe);
+      // The HEAD first: past the end, Bun's slice raises from inside the stream, after a caller has
+      // already answered 206. Refused here it is still a status.
+      const { size } = await statObject(safe);
+      const [first, last] = streamedRange(DRIVER_NAME, safe, range, size);
+      return conn()
+        .file(safe)
+        .slice(first, last + 1)
+        .stream();
+    },
+
     /**
      * Bytes from one key to another without a round trip through this process. Bun exposes no
      * `CopyObject`, so the source `S3File` is handed to `write()` — Bun's own union accepts one —
@@ -288,9 +341,20 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
      * win available today: promoting a 500MB attachment used to be `get()` + `put()`, a full GB
      * resident in the pod. A true server-side copy needs a Bun API that does not exist in 1.3.
      */
-    async copy(from: string, to: string): Promise<StorageObject> {
+    async copy(from: string, to: string, copyOptions?: CopyOptions): Promise<StorageObject> {
       const source = assertSafeKey(from);
       const destination = assertSafeKey(to);
+      // Bun's `write` takes no condition, so a revision-bound copy is the signed CopyObject.
+      if (copyOptions?.ifMatch !== undefined) {
+        const refusal = await signedCopy(options, source, destination, copyOptions.ifMatch).catch(
+          refusedWrite(destination),
+        );
+        if (refusal?.statusCode === 404) throw objectNotFound(diskName, source);
+        if (refusal?.statusCode === 412)
+          throw objectChanged(source, copyOptions.ifMatch, 'another');
+        if (refusal !== undefined) refusedWrite(destination)(refusal);
+        return statObject(destination);
+      }
       const file = conn().file(source);
       if (!(await present(source))) throw objectNotFound(diskName, source);
       const stat = await file.stat().catch(refusedRead(source));
@@ -397,29 +461,13 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       );
     },
 
-    /**
-     * Provider presigning. The signature covers method, expiry and content type but NOT
-     * `maxBytes` — S3 has no header for it, so size stays a server-side policy check.
-     */
+    /** Both presigners, one rule: `driver-s3-presign.ts`. */
     async signedUrl(key: string, urlOptions?: SignedUrlOptions): Promise<string> {
-      // Screened with the SAME function `buildSignedUrl` applies on the local disk — one
-      // finite-bound path for both presigners, never a private copy per package: `Math.ceil(NaN /
-      // 1000)` is `NaN`, so `X-Amz-Expires=NaN` went to AWS and the app got a 403 on a link it
-      // believed it had just minted. `=== undefined` rather than `??`, so an explicit `null` is
-      // refused instead of silently taking the default.
-      const expiresInMs = finiteCount(
-        'the s3 driver',
-        'expiresInMs',
-        urlOptions?.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : urlOptions.expiresInMs,
-        1,
-      );
-      return conn()
-        .file(assertSafeKey(key))
-        .presign({
-          method: urlOptions?.method ?? 'GET',
-          expiresIn: Math.ceil(expiresInMs / 1000),
-          ...(urlOptions?.contentType === undefined ? {} : { type: urlOptions.contentType }),
-        });
+      return s3SignedUrl(options, (safe) => conn().file(safe), key, urlOptions);
     },
   };
+  // Attached in place: the capability presigns and stats through the disk it belongs to.
+  return Object.assign(disk, {
+    multipart: s3Multipart({ wire: options, driver: disk, refusedWrite }),
+  });
 }

package/src/driver.ts

@@ -5,9 +5,13 @@
 
 import type { Clock, Page } from '@ultimat3/core';
 import { assert } from '@ultimat3/core';
+import { pumpBounded } from './byte-pump';
 import { putTooLarge } from './errors';
+import type { MultipartCapability } from './multipart';
 import type { ObjectLock, ObjectLockOptions } from './object-lock';
-import type { SignedUrlVerification } from './signed-url';
+import type { PutStreamOptions } from './put-stream';
+import type { ByteRange, GetOptions } from './range';
+import type { SignedPart, SignedUrlVerification } from './signed-url';
 
 export type StorageBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
 
@@ -81,8 +85,15 @@ export interface ListOptions {
 }
 
 export interface StorageRead {
+  /** The WHOLE object's description — `size` is the object's, never the range's. */
   readonly object: StorageObject;
   readonly bytes: Uint8Array;
+  /**
+   * The bytes served, both inclusive, after the clamp — present exactly when `range` was asked.
+   * A third-party driver that ignored the option answers none, and that absence is how a caller
+   * tells a slice from the whole object rather than trusting `bytes.byteLength`.
+   */
+  readonly range?: ByteRange | undefined;
 }
 
 export type SignedUrlMethod = 'GET' | 'PUT';
@@ -91,18 +102,30 @@ export interface SignedUrlOptions {
   readonly method?: SignedUrlMethod | undefined;
   readonly expiresInMs?: number | undefined;
   /**
-   * Ceiling on a `PUT`, and **the one option whose enforcement is the driver's, not the caller's**.
-   *
-   * `localDriver` signs it into the URL, so `acceptSignedUpload` refuses a client that widens it.
-   * `s3Driver` CANNOT: S3 has no request header for a size and Bun's `presign` covers method,
-   * expiry and content type only — so the client PUTs straight into the bucket and nothing between
-   * the grant and the object enforces this number. It is not refused there, because `grantUpload`
-   * supplies it on every grant and refusing would break every s3 upload an app mints; the ceiling
-   * a bucket-backed disk actually gets is a bucket rule or a post-upload check on `object.size`.
-   * `driver-parity.test.ts` pins both halves so neither moves alone.
+   * Ceiling on a `PUT`. `localDriver` signs it into the URL, so `acceptSignedUpload` refuses a client
+   * that widens it. A provider's URL has no ceiling to sign, so `s3Driver` refuses it without
+   * `contentLength` (`X_STORAGE_UPLOAD_SIZE_UNDECLARED`) rather than mint a URL that ignores it.
    */
   readonly maxBytes?: number | undefined;
+  /**
+   * The exact size of a `PUT`, inside the signature. On `s3Driver` the URL then signs
+   * `content-length`, so the provider refuses any other length, a chunked body with none included
+   * (403 `SignatureDoesNotMatch`). The local disks hold it as a ceiling (`x-max`): they count what
+   * arrives, so a shorter body passes there and not on s3. `driver-parity.test.ts` pins both.
+   */
+  readonly contentLength?: number | undefined;
   readonly contentType?: string | undefined;
+  /**
+   * A part of an open upload, inside the signature: the URL then writes that part and nothing else.
+   * Only a disk whose `multipart.receivePart` stores parts signs one; `s3Driver` refuses it, since
+   * its parts are signed by `multipart.signPart` against the provider.
+   */
+  readonly part?: SignedPart | undefined;
+}
+
+export interface CopyOptions {
+  /** The source's `etag` as this disk reported it. */
+  readonly ifMatch?: string | undefined;
 }
 
 export interface StorageDriver {
@@ -125,6 +148,16 @@ export interface StorageDriver {
    */
   registerAs?(diskName: string): void;
   put(key: string, body: StorageBody, options?: PutOptions): Promise<StorageObject>;
+  /**
+   * A body of any length, without buffering it: counted against the call's required `maxBytes`, and
+   * past it the write is abandoned with the key as it was (`X_STORAGE_TOO_LARGE`). Takes no
+   * `checksum`, retention or legal hold, which need the bytes before the object exists.
+   */
+  putStream(
+    key: string,
+    stream: ReadableStream<Uint8Array>,
+    options: PutStreamOptions,
+  ): Promise<StorageObject>;
   /**
    * What a read would say about the object, WITHOUT its bytes — `undefined` when nothing is there.
    * `promoteAttachment` decides on `stat().size`, because a presigned PUT lands on the disk
@@ -134,17 +167,26 @@ export interface StorageDriver {
   stat(key: string): Promise<StorageObject | undefined>;
   /**
    * The whole object, BUFFERED — so bounded: an object over the driver's `maxGetBytes` is
-   * `X_STORAGE_TOO_LARGE`, exactly as `put()` refuses a body over `maxPutBytes`. Past it, `stream()`.
+   * `X_STORAGE_TOO_LARGE`, exactly as `put()` refuses a body over `maxPutBytes`. Past it, `stream()`
+   * — or `{ range: [first, last] }`, which reads only those bytes (inclusive) and is bounded by
+   * the range's length: s3 sends `Range:`, the local disk slices the file, memory slices its copy.
    */
-  get(key: string): Promise<StorageRead>;
+  get(key: string, options?: GetOptions): Promise<StorageRead>;
   /** Bytes without buffering — the only safe path for anything over a few MB. */
   stream(key: string): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * The bytes `[first, last]` (inclusive, clamped, as `get`'s range) with none before them read, so
+   * a seek late in a film costs its window. `X_STORAGE_RANGE_UNSATISFIABLE` past the end. A method and
+   * not an option on `stream`, which a third-party driver would ignore and serve the wrong bytes.
+   */
+  streamRange(key: string, range: ByteRange): Promise<ReadableStream<Uint8Array>>;
   /**
    * Bytes from one key to another without them passing through this process. Idempotent in the
    * destination and non-destructive in the source: the caller deletes the source afterwards if
-   * it wanted a move. `X_STORAGE_NOT_FOUND` when `from` is absent.
+   * it wanted a move. `X_STORAGE_NOT_FOUND` when `from` is absent. `ifMatch` copies only that
+   * revision: any other is `X_STORAGE_OBJECT_CHANGED` and writes nothing.
    */
-  copy(from: string, to: string): Promise<StorageObject>;
+  copy(from: string, to: string, options?: CopyOptions): Promise<StorageObject>;
   /**
    * Deleting an ABSENT key is not an error. Anything else is: a denied `s3:DeleteObject`, a
    * throttle, an expired credential and a read-only mount all raise `X_STORAGE_DELETE_FAILED`,
@@ -183,6 +225,12 @@ export interface StorageDriver {
    * provider and never reaches this path, and a third-party driver that implements neither is
    * refused by name (`X_STORAGE_URL_UNVERIFIABLE`) rather than reported as a bad signature.
    */
+  /**
+   * An upload in parts: resumable, and past S3's 5 GiB single-PUT ceiling. Optional, so a
+   * third-party driver still compiles; `grantMultipart` refuses a disk without it
+   * (`X_STORAGE_MULTIPART_UNSUPPORTED`). Every shipped disk has one.
+   */
+  readonly multipart?: MultipartCapability | undefined;
   verifySigned?(input: {
     readonly url: string;
     /** Overrides the driver's own, so a test's frozen clock still governs expiry. */
@@ -241,6 +289,36 @@ export function assertPutOptions(driver: string, options: PutOptions | undefined
   );
 }
 
+/**
+ * The number a signed URL holds, screened on every disk: `contentLength` when there is one, since it
+ * is the tighter fact, and a `contentLength` past `maxBytes` or on anything but a `PUT` is a call
+ * that contradicts itself.
+ */
+export function signedByteBound(
+  driver: string,
+  options: SignedUrlOptions | undefined,
+): number | undefined {
+  const length = options?.contentLength;
+  if (length === undefined) return options?.maxBytes;
+  const maxBytes = options?.maxBytes;
+  assert(
+    Number.isSafeInteger(length) && length >= 0,
+    `signedUrl() on the ${driver} disk was given a contentLength that is not a whole byte count`,
+    "signedUrl(key, { method: 'PUT', contentLength: file.size })",
+  );
+  assert(
+    options?.method === 'PUT',
+    `signedUrl() on the ${driver} disk was given a contentLength on a read, which has no body to bind`,
+    "signedUrl(key, { method: 'PUT', contentLength: file.size })",
+  );
+  assert(
+    maxBytes === undefined || length <= maxBytes,
+    `signedUrl() on the ${driver} disk was given a contentLength of ${length}B past its maxBytes of ${String(maxBytes)}B`,
+    "signedUrl(key, { method: 'PUT', contentLength: file.size })   # at or under maxBytes",
+  );
+  return length;
+}
+
 /** A `prefix` or a `cursor` that is not a string reached `startsWith` and `<=` as whatever it was. */
 export function assertListOptions(options: ListOptions | undefined): void {
   for (const name of ['prefix', 'cursor'] as const) {
@@ -299,31 +377,13 @@ async function readBounded(
   body: ReadableStream<Uint8Array>,
   limit: ByteLimit,
 ): Promise<Uint8Array> {
-  const reader = body.getReader();
   const chunks: Uint8Array[] = [];
-  let total = 0;
-  try {
-    for (;;) {
-      const next = await reader.read();
-      if (next.done) break;
-      total += next.value.byteLength;
-      if (total > limit.maxBytes) {
-        throw putTooLarge(limit.driver, limit.key, total, limit.maxBytes);
-      }
-      chunks.push(next.value);
-    }
-  } finally {
-    // Cancel rather than merely release: a refused body must stop arriving, not keep filling a
-    // socket buffer nobody will read. Already-closed streams answer this with a no-op.
-    await reader.cancel().catch(() => undefined);
-  }
-  const bytes = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return bytes;
+  const { driver, key, maxBytes } = limit;
+  const refuse = (total: number): Error => putTooLarge(driver, key, total, maxBytes);
+  await pumpBounded(body, { driver, maxBytes, refuse }, (chunk) => {
+    chunks.push(chunk);
+  });
+  return new Uint8Array(Bun.concatArrayBuffers(chunks));
 }
 
 /** base64 SHA-256 — the wire form for `PutOptions.checksum` and `ValidatedUpload.checksum`. */

package/src/errors-multipart.ts

@@ -0,0 +1,35 @@
+// The refusals of an upload in parts. Registered with the rest of the package's codes in
+// `errors.ts`; each `fix:` names the call that goes next, with the key and upload id screened.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+const keyArg = (key: string): string => renderFixLiteral(key, "'<key>'");
+const idArg = (uploadId: string): string => renderFixLiteral(uploadId, "'<uploadId>'");
+
+/** A disk whose driver declares no `multipart`: a third-party driver, most likely. */
+export const multipartUnsupported = (disk: string, key: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_MULTIPART_UNSUPPORTED',
+    cause: `the ${disk} disk's driver declares no multipart capability, so "${key}" cannot be uploaded in parts`,
+    fix: 'grantUpload({ disk, orgId, request })   # one PUT; or implement StorageDriver.multipart on the driver',
+    meta: { disk, key },
+  });
+
+/** No open session by that id for that key: never opened, completed, or aborted. */
+export const uploadUnknown = (disk: string, key: string, uploadId: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_UPLOAD_UNKNOWN',
+    cause: `no upload ${idArg(uploadId)} is open for "${key}" on the ${disk} disk: it was never opened there, or it was already completed or aborted`,
+    fix: 'grantMultipart({ disk, orgId, request })   # a new session, then send every part under its uploadId',
+    meta: { disk, key, uploadId },
+  });
+
+/** The parts a Complete named do not match what the disk holds. */
+export const partsInvalid = (key: string, uploadId: string, problem: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_PARTS_INVALID',
+    cause: `the parts named to complete "${key}" do not match the parts stored: ${problem}`,
+    fix: `await listParts({ disk, orgId, key: ${keyArg(key)}, uploadId: ${idArg(uploadId)} })   # what landed; resend the missing part, then completeUpload again`,
+    meta: { key, uploadId, problem },
+  });