@ultimat3/storage 1.1.0 → 2.0.0

package/src/driver-s3-fixture.ts

@@ -0,0 +1,164 @@
+// The in-memory `Bun.S3Client` stand-in the s3 driver's tests drive, and the helpers that read
+// its answers. Shared rather than copied because `driver-s3.test.ts` (reads, copies, listings,
+// credentials) and `driver-s3-put.test.ts` (everything `put()` refuses) must exercise the SAME
+// fake — two fakes drifting apart would be two providers, agreeing only by construction.
+
+import type { S3ClientLike, S3FileLike, S3ListResultLike, S3StatLike } from './driver-s3';
+import { isStorageError, objectNotFound } from './errors';
+
+/** The driver's private `DRIVER_NAME`; the fake reports failures against the same disk. */
+export const FAKE_DISK = 's3';
+
+export interface FakeObject {
+  bytes: Uint8Array;
+  type?: string | undefined;
+  etag?: string | undefined;
+  lastModified?: string | Date | undefined;
+}
+
+export interface PresignCall {
+  key: string;
+  options: {
+    method?: string | undefined;
+    expiresIn?: number | undefined;
+    type?: string | undefined;
+  };
+}
+
+export interface ListCall {
+  prefix?: string | undefined;
+  maxKeys?: number | undefined;
+  continuationToken?: string | undefined;
+}
+
+/**
+ * What Bun hands back when the SERVICE refuses: an ordinary `Error` named `S3Error`, carrying the
+ * provider's own code and status. The driver must read those structurally, because nothing in the
+ * type system says a caught value has them.
+ */
+export function s3Error(code: string, statusCode: number, key: string): Error {
+  return Object.assign(new Error(`${code}: the fake provider refused ${key}`), {
+    name: 'S3Error',
+    code,
+    statusCode,
+    path: key,
+  });
+}
+
+/** In-memory stand-in for `Bun.S3Client`, driven through `S3ClientLike` — no socket, ever. */
+export class FakeS3Client implements S3ClientLike {
+  readonly store = new Map<string, FakeObject>();
+  readonly fileCalls: string[] = [];
+  readonly presignCalls: PresignCall[] = [];
+  readonly listCalls: ListCall[] = [];
+  listResult: S3ListResultLike = { contents: [] };
+  /** A provider REFUSAL (403/503/reset) — the failure `delete()` must surface, not swallow. */
+  failDeleteFor: string | undefined;
+  /** A provider "there is nothing there" — the one failure `delete()` may call success. */
+  absentDeleteFor: string | undefined;
+  /**
+   * A refused LISTING — a denied `s3:ListBucket`, a throttle, an expired credential. There is no
+   * "absent" counterpart: a prefix with no keys is an empty page, never a rejection, so every
+   * failure `list()` can meet is one it must surface.
+   */
+  failListWith: Error | undefined;
+
+  /** Which key each handed-out `S3FileLike` stands for, so `write(sourceFile)` can read it. */
+  private readonly fileKeys = new WeakMap<object, string>();
+
+  /** The bytes behind an `S3FileLike` passed as `write`'s data, or `undefined` for raw bytes. */
+  sourceOf(data: unknown): Uint8Array | undefined {
+    if (typeof data !== 'object' || data === null) return undefined;
+    const sourceKey = this.fileKeys.get(data);
+    return sourceKey === undefined ? undefined : this.store.get(sourceKey)?.bytes;
+  }
+
+  file(key: string): S3FileLike {
+    this.fileCalls.push(key);
+    const store = this.store;
+    const client = this;
+    const handle: S3FileLike = {
+      async write(data, options) {
+        // `copy()` hands the SOURCE S3File to write(), exactly as Bun's own union allows, so the
+        // fake has to read one back out of its store rather than assume bytes.
+        const source = client.sourceOf(data);
+        const bytes =
+          source !== undefined
+            ? source
+            : data instanceof Uint8Array
+              ? data
+              : new Uint8Array(await (data as Blob).arrayBuffer());
+        store.set(key, { bytes, type: options?.type });
+        return bytes.byteLength;
+      },
+      async arrayBuffer() {
+        const entry = store.get(key);
+        // Reads the way the provider does: a GET on a key that is not there is a 404, and the
+        // driver is expected to have gated it behind exists() before ever getting here.
+        if (entry === undefined) throw objectNotFound(FAKE_DISK, key);
+        return new Uint8Array(entry.bytes).buffer;
+      },
+      async exists() {
+        return store.has(key);
+      },
+      async delete() {
+        // Shaped like the real thing: an `S3Error` is a plain Error with `name: 'S3Error'`, a
+        // provider `code` and a status. Deliberately NOT a StorageError — the driver has to
+        // classify a rejection it never authored, which is the only kind a provider hands back.
+        if (client.absentDeleteFor === key) throw s3Error('NoSuchKey', 404, key);
+        if (client.failDeleteFor === key) throw s3Error('AccessDenied', 403, key);
+        store.delete(key);
+      },
+      stream() {
+        const entry = store.get(key);
+        const bytes = entry?.bytes ?? new Uint8Array();
+        return new ReadableStream<Uint8Array>({
+          start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+          },
+        });
+      },
+      async stat(): Promise<S3StatLike> {
+        const entry = store.get(key);
+        if (entry === undefined) throw objectNotFound(FAKE_DISK, key);
+        return {
+          size: entry.bytes.byteLength,
+          type: entry.type,
+          etag: entry.etag,
+          lastModified: entry.lastModified,
+        };
+      },
+      presign(options) {
+        client.presignCalls.push({ key, options });
+        return `https://fake.example/${key}?signed`;
+      },
+    };
+    this.fileKeys.set(handle, key);
+    return handle;
+  }
+
+  async list(input: ListCall): Promise<S3ListResultLike> {
+    this.listCalls.push(input);
+    if (this.failListWith !== undefined) throw this.failListWith;
+    return this.listResult;
+  }
+}
+
+export const bytesOf = (text: string): Uint8Array => new TextEncoder().encode(text);
+export const textOf = (bytes: Uint8Array): string => new TextDecoder().decode(bytes);
+
+/** The error code a call answered with, or how it failed to answer with one. */
+export function codeOf(caught: unknown): string {
+  return isStorageError(caught) ? caught.code : `not-a-storage-error: ${String(caught)}`;
+}
+
+/** The thrown value itself, where the assertion is about its `cause`/`fix` and not just its code. */
+export async function catchError(fn: () => Promise<unknown>): Promise<unknown> {
+  try {
+    await fn();
+    return undefined;
+  } catch (error) {
+    return error;
+  }
+}

package/src/driver-s3.ts

@@ -3,7 +3,7 @@
 // The client is built lazily on first use so importing this module never opens a socket, and
 // credentials arrive as env var NAMES: a literal key in app.config.ts is a key in git.
 
-import { ConfigInvalidError, EnvMissingError } from '@ultimat3/core';
+import { ConfigInvalidError, EnvMissingError, stringField } from '@ultimat3/core';
 import {
   DEFAULT_CONTENT_TYPE,
   DEFAULT_LIST_LIMIT,
@@ -13,19 +13,28 @@ import {
   type SignedUrlOptions,
   type StorageBody,
   type StorageDriver,
+  type StorageListEntry,
   type StorageObject,
   type StorageRead,
   sha256Base64,
   toBytes,
 } from './driver';
-import { checksumMismatch, objectNotFound, storageNotImplemented } from './errors';
+import {
+  checksumMismatch,
+  deleteFailed,
+  listFailed,
+  objectNotFound,
+  storageNotImplemented,
+} from './errors';
 import { assertSafeKey } from './path';
+import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
 const DRIVER_NAME = 's3';
 
 /** Structural view of `Bun.S3Client` — typing it here keeps `bun-types` out of the contract. */
 export interface S3FileLike {
-  write(data: Uint8Array | Blob, options?: { type?: string }): Promise<number>;
+  /** `S3FileLike` is in the union because Bun's own `write` takes an `S3File` — that is `copy`. */
+  write(data: Uint8Array | Blob | S3FileLike, options?: { type?: string }): Promise<number>;
   arrayBuffer(): Promise<ArrayBuffer>;
   exists(): Promise<boolean>;
   delete(): Promise<void>;
@@ -79,6 +88,13 @@ export interface S3DriverOptions {
   readonly env?: Readonly<Record<string, string | undefined>> | undefined;
   /** Injected in tests; production constructs `Bun.S3Client`. */
   readonly client?: S3ClientLike | undefined;
+  /**
+   * Ceiling on ONE server-side `put()`, because `put()` buffers the whole body. Defaults to the
+   * upload policy's ceiling — the same number for the same fact. Raise it for a disk that really
+   * does write large objects from the server; a user upload belongs on `grantUpload` instead,
+   * and S3's single-PUT limit is 5GB regardless of what this says.
+   */
+  readonly maxPutBytes?: number | undefined;
 }
 
 interface S3ClientConstructor {
@@ -137,7 +153,63 @@ function buildClient(options: S3DriverOptions): S3ClientLike {
 const toDate = (value: string | Date | undefined): Date =>
   value === undefined ? new Date(0) : value instanceof Date ? value : new Date(value);
 
+/** One numeric field off a value that may fight being read — `stringField`'s missing twin. */
+function numberField(value: unknown, key: string): number | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    const held = (value as Record<string, unknown>)[key];
+    return typeof held === 'number' ? held : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The provider codes that mean "there is nothing at that key", and nothing wider. */
+const ABSENT_OBJECT_CODES: ReadonlySet<string> = new Set(['NoSuchKey', 'NotFound', 'ENOENT']);
+
+/**
+ * The ONE delete failure the contract calls success. `AccessDenied`, `SlowDown`, an expired
+ * credential and a reset connection are none of them, and the previous `.catch(() => undefined)`
+ * reported all four as deleted — which is how an erasure sweep certifies data it never removed.
+ *
+ * Read structurally: an `S3Error` is `name: 'S3Error'` with a `code` the service returned, and
+ * every field of a value this process did not build is a getter that can throw.
+ */
+function isAbsentObject(error: unknown): boolean {
+  const code = stringField(error, 'code');
+  if (code !== undefined && ABSENT_OBJECT_CODES.has(code)) return true;
+  return numberField(error, 'statusCode') === 404 || numberField(error, 'status') === 404;
+}
+
+/**
+ * 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, key: string, putOptions?: PutOptions): void {
+  if (putOptions?.metadata !== undefined || putOptions?.cacheControl !== undefined) {
+    const uri = `s3://${bucket}/${key}`;
+    throw storageNotImplemented(
+      'user metadata and cache-control on the s3 driver (Bun exposes no header hook yet)',
+      `drop metadata/cacheControl from put(), or set them out of band: ` +
+        `aws s3 cp ${uri} ${uri} --metadata-directive REPLACE`,
+    );
+  }
+  const sse = putOptions?.serverSideEncryption;
+  if (sse === undefined) return;
+  const rule =
+    sse.algorithm === 'aws:kms'
+      ? `{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":"${sse.kmsKeyId ?? '<key-arn>'}"}`
+      : '{"SSEAlgorithm":"AES256"}';
+  throw storageNotImplemented(
+    'per-object server-side encryption on the s3 driver (Bun.S3Client exposes acl, storageClass and type, and nothing for x-amz-server-side-encryption)',
+    `set it bucket-wide, then drop serverSideEncryption from put(): aws s3api put-bucket-encryption --bucket ${bucket} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":${rule},"BucketKeyEnabled":true}]}'`,
+  );
+}
+
 export function s3Driver(options: S3DriverOptions): StorageDriver {
+  const maxPutBytes = options.maxPutBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
   let client: S3ClientLike | undefined;
   const conn = (): S3ClientLike => {
     client ??= buildClient(options);
@@ -160,17 +232,12 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
 
     async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
       const safe = assertSafeKey(key);
-      if (putOptions?.metadata !== undefined || putOptions?.cacheControl !== undefined) {
-        const uri = `s3://${options.bucket}/${safe}`;
-        throw storageNotImplemented(
-          'user metadata and cache-control on the s3 driver (Bun exposes no header hook yet)',
-          `drop metadata/cacheControl from put(), or set them out of band: ` +
-            `aws s3 cp ${uri} ${uri} --metadata-directive REPLACE`,
-        );
-      }
-      // Buffered on purpose: size and checksum must be known before the object exists.
-      // Multipart streaming upload is a later optimisation, not a correctness change.
-      const bytes = await toBytes(body);
+      refuseUnsupportedPut(options.bucket, safe, putOptions);
+      // Buffered on purpose: size and checksum must be known before the object exists — so this
+      // path is for objects that FIT IN MEMORY, and `maxPutBytes` is what makes that a contract
+      // rather than a hope. User uploads never come through here: they go direct to the bucket
+      // via `grantUpload`, which is the architecture, not a later optimisation.
+      const bytes = await toBytes(body, { driver: DRIVER_NAME, key: safe, maxBytes: maxPutBytes });
       const claimed = putOptions?.checksum;
       if (claimed !== undefined) {
         const actual = sha256Base64(bytes);
@@ -197,11 +264,40 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       return file.stream();
     },
 
-    async delete(key: string): Promise<void> {
+    /**
+     * 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 —
+     * and the bytes move inside Bun rather than through the app's heap. That is the half of the
+     * 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> {
+      const source = assertSafeKey(from);
+      const destination = assertSafeKey(to);
+      const file = conn().file(source);
+      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, source);
+      const stat = await file.stat();
       await conn()
-        .file(assertSafeKey(key))
-        .delete()
-        .catch(() => undefined);
+        .file(destination)
+        .write(file, { type: stat.type ?? DEFAULT_CONTENT_TYPE });
+      return statObject(destination);
+    },
+
+    async delete(key: string): Promise<void> {
+      const safe = assertSafeKey(key);
+      try {
+        await conn().file(safe).delete();
+      } catch (error) {
+        // Idempotent means an ABSENT key, and nothing else. AWS answers DELETE on a missing key
+        // with 204, so this branch is for the providers that do not.
+        if (isAbsentObject(error)) return;
+        throw deleteFailed(
+          DRIVER_NAME,
+          safe,
+          error,
+          `grant s3:DeleteObject on this prefix to the app's role, then reproduce with the provider's own words: aws s3api delete-object --bucket ${options.bucket} --key ${safe}`,
+        );
+      }
     },
 
     async exists(key: string): Promise<boolean> {
@@ -209,18 +305,39 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     },
 
     async list(listOptions?: ListOptions): Promise<ListPage> {
-      const result = await conn().list({
-        maxKeys: listOptions?.limit ?? DEFAULT_LIST_LIMIT,
-        ...(listOptions?.prefix === undefined ? {} : { prefix: listOptions.prefix }),
-        ...(listOptions?.cursor === undefined ? {} : { continuationToken: listOptions.cursor }),
-      });
-      const objects: StorageObject[] = [];
+      const prefix = listOptions?.prefix ?? '';
+      // `conn()` OUTSIDE the try: a missing credential or an absent `Bun.S3Client` is this disk
+      // misconfigured, and it already answers with its own code and its own fix.
+      const client = conn();
+      let result: S3ListResultLike;
+      try {
+        result = await client.list({
+          maxKeys: listOptions?.limit ?? DEFAULT_LIST_LIMIT,
+          ...(listOptions?.prefix === undefined ? {} : { prefix: listOptions.prefix }),
+          ...(listOptions?.cursor === undefined ? {} : { continuationToken: listOptions.cursor }),
+        });
+      } catch (error) {
+        // A bare `S3Error` used to escape here, uncoded: no `X_*`, no `fix`, no `--json` shape, and
+        // `@ultimat3/http`'s error map has nothing to turn it into but a 500. A denied
+        // `s3:ListBucket` is the commonest one and reads to an operator as an app crash.
+        throw listFailed(
+          DRIVER_NAME,
+          prefix,
+          error,
+          `grant s3:ListBucket on this bucket to the app's role, then reproduce with the provider's own words: aws s3api list-objects-v2 --bucket ${options.bucket}${prefix === '' ? '' : ` --prefix ${prefix}`}`,
+        );
+      }
+      const objects: StorageListEntry[] = [];
       for (const entry of result.contents ?? []) {
         if (entry.key === undefined) continue;
+        // No `contentType`. ListObjectsV2 does not return one, and reading it for real would
+        // cost one HeadObject per listed row — which is what `list()` exists to avoid. It used
+        // to report `application/octet-stream`, indistinguishable from an object that really is
+        // one, while the local driver reported the truth from its sidecar: a caller filtering a
+        // listing by content type got everything on `local` and nothing on `s3`. Absent now.
         objects.push({
           key: entry.key,
           size: entry.size ?? 0,
-          contentType: DEFAULT_CONTENT_TYPE,
           etag: entry.eTag ?? '',
           lastModified: toDate(entry.lastModified),
         });

package/src/driver.ts

@@ -1,15 +1,48 @@
 // Single responsibility: the driver contract every disk implements, plus the byte helpers all
-// drivers share (body normalisation, SHA-256 etag/checksum). Bytes never travel as strings —
-// a base64 round trip through JSON is how a "small" upload becomes a 33%-larger OOM.
+// drivers share (BOUNDED body normalisation, SHA-256 etag/checksum). Bytes never travel as
+// strings — a base64 round trip through JSON is how a "small" upload becomes a 33%-larger OOM —
+// and never unbounded, which is the same failure with the sender choosing the size.
+
+import { putTooLarge } from './errors';
 
 export type StorageBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
 
-export interface StorageObject {
+/**
+ * One row of a listing — everything a listing can HONESTLY know. `contentType` is optional here
+ * and required on `StorageObject` below, because S3's `ListObjectsV2` does not return one: the
+ * s3 driver used to fill in `application/octet-stream`, the local driver read the real value out
+ * of its sidecar, and a caller filtering a listing by content type therefore got every object on
+ * `local` and none on `s3`. Absent now means "this listing cannot know" — `get()` can.
+ */
+export interface StorageListEntry {
   readonly key: string;
   readonly size: number;
-  readonly contentType: string;
+  /** Absent means the driver's listing does not carry it. Never a fabricated default. */
+  readonly contentType?: string | undefined;
   readonly etag: string;
   readonly lastModified: Date;
+  /** Present only when the driver actually stored what `put()` was handed — never invented. */
+  readonly cacheControl?: string | undefined;
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+}
+
+/** A single object the driver has actually looked at, so the content type is known. */
+export interface StorageObject extends StorageListEntry {
+  readonly contentType: string;
+}
+
+/**
+ * Encryption at rest, per object. Declared so the gap is visible at the type level: an engineer
+ * asked "can you prove which key encrypted this object?" must meet the answer at the call site,
+ * not by reading the driver. NO driver honours it yet — `Bun.S3Client` exposes `acl`,
+ * `storageClass` and `type` and nothing for `x-amz-server-side-encryption*`, and a POSIX file is
+ * not encrypted at all — so both drivers refuse a `put()` carrying one (`X_NOT_IMPLEMENTED`) with
+ * the out-of-band bucket-default command in the `fix`. A typed refusal beats a silent absence.
+ */
+export interface ServerSideEncryption {
+  readonly algorithm: 'AES256' | 'aws:kms';
+  /** The customer-managed key. Only meaningful with `aws:kms`. */
+  readonly kmsKeyId?: string | undefined;
 }
 
 export interface PutOptions {
@@ -18,6 +51,8 @@ export interface PutOptions {
   readonly metadata?: Readonly<Record<string, string>> | undefined;
   /** base64 SHA-256 of the body. Supplied means verified: a mismatch is a rejected write. */
   readonly checksum?: string | undefined;
+  /** Refused by every shipped driver — see `ServerSideEncryption`. */
+  readonly serverSideEncryption?: ServerSideEncryption | undefined;
 }
 
 export interface ListOptions {
@@ -28,7 +63,7 @@ export interface ListOptions {
 }
 
 export interface ListPage {
-  readonly objects: readonly StorageObject[];
+  readonly objects: readonly StorageListEntry[];
   readonly truncated: boolean;
   /** Absent when `truncated` is false. */
   readonly cursor?: string | undefined;
@@ -44,7 +79,17 @@ export type SignedUrlMethod = 'GET' | 'PUT';
 export interface SignedUrlOptions {
   readonly method?: SignedUrlMethod | undefined;
   readonly expiresInMs?: number | undefined;
-  /** Constrains a `PUT`: the signature covers it, so a client cannot widen it. */
+  /**
+   * 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.
+   */
   readonly maxBytes?: number | undefined;
   readonly contentType?: string | undefined;
 }
@@ -56,7 +101,17 @@ export interface StorageDriver {
   get(key: string): Promise<StorageRead>;
   /** Bytes without buffering — the only safe path for anything over a few MB. */
   stream(key: string): Promise<ReadableStream<Uint8Array>>;
-  /** Idempotent: deleting an absent key is not an error. */
+  /**
+   * 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.
+   */
+  copy(from: string, to: string): 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`,
+   * because a caller that cannot tell "gone" from "refused" reports data erased that is not.
+   */
   delete(key: string): Promise<void>;
   exists(key: string): Promise<boolean>;
   list(options?: ListOptions): Promise<ListPage>;
@@ -66,10 +121,70 @@ export interface StorageDriver {
 export const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
 export const DEFAULT_LIST_LIMIT = 1000;
 
-export async function toBytes(body: StorageBody): Promise<Uint8Array> {
-  if (body instanceof Uint8Array) return body;
-  if (body instanceof Blob) return new Uint8Array(await body.arrayBuffer());
-  return new Uint8Array(await new Response(body).arrayBuffer());
+/** What `toBytes` needs to refuse a body: the ceiling, and the key to name in the refusal. */
+export interface ByteLimit {
+  readonly driver: string;
+  readonly key: string;
+  readonly maxBytes: number;
+}
+
+/**
+ * Body → bytes, refusing past the ceiling BEFORE the whole body is resident.
+ *
+ * The bound is not an optimisation. `put()` buffers, so without one the heap grows by whatever a
+ * route piped into it: a 4GB request body on a pod with a 768Mi limit is an OOM kill, and the
+ * caller sees a dropped connection rather than a refusal. A `Uint8Array` and a `Blob` already
+ * know their length, so they are refused without a copy; a stream is read a chunk at a time and
+ * cancelled the moment the running total passes the ceiling, so at most one chunk past the limit
+ * is ever held. The server-side `put()` path is for objects that FIT IN MEMORY — user uploads go
+ * direct to the disk through `grantUpload`, which is the architecture, not the optimisation.
+ */
+export async function toBytes(body: StorageBody, limit: ByteLimit): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) {
+    if (body.byteLength > limit.maxBytes) {
+      throw putTooLarge(limit.driver, limit.key, body.byteLength, limit.maxBytes);
+    }
+    return body;
+  }
+  if (body instanceof Blob) {
+    if (body.size > limit.maxBytes) {
+      throw putTooLarge(limit.driver, limit.key, body.size, limit.maxBytes);
+    }
+    return new Uint8Array(await body.arrayBuffer());
+  }
+  return readBounded(body, limit);
+}
+
+/** The stream half of `toBytes`: the only shape whose length is unknown until it is read. */
+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;
 }
 
 /** base64 SHA-256 — the wire form for `PutOptions.checksum` and `ValidatedUpload.checksum`. */