@pithy-sh/storage 0.1.0

package/src/object/multipart.ts

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { StorageMultipartFailedError } from "../error/errors";
+
+/**
+ * Part orchestration for a multipart upload: how many parts, how big, and how the ETags the client
+ * reports back are turned into a completion list R2 will accept.
+ *
+ * **Why multipart at all.** A single presigned PUT is capped at 5 GiB, and it is not resumable — a
+ * dropped connection at 4 GiB starts over. Multipart raises the ceiling and makes a lost client
+ * cheap: `GET /storage/:id/parts` re-lists what R2 holds and re-presigns the rest, so the client
+ * sends only what is missing. The server holds no transfer state beyond the pending row.
+ *
+ * **The defaults and the ceiling they imply.** Threshold 100 MiB, part size 64 MiB. R2 allows at
+ * most 10,000 parts, so 10,000 × 64 MiB is a documented practical ceiling of ~625 GiB per object.
+ * That is well short of R2's own 4.995 TiB object cap (and its 4.995 GiB single-part cap); an
+ * adopter storing objects larger than ~625 GiB raises `partSizeBytes` in `pithy.config.ts` and gets
+ * a proportionally higher ceiling. The trade is deliberate: a bigger default part size would make
+ * every ordinary upload retry more expensive to serve a size almost nobody stores.
+ *
+ * **The 5 MiB floor** applies to every part but the last, and is S3's rule, not ours — R2 rejects a
+ * completion whose non-final part is smaller. Enforcing it here means the failure lands at plan time
+ * with a config-shaped message, rather than after the client has spent bandwidth on every part.
+ */
+
+/** Above this many bytes an upload goes multipart. Below it, one presigned PUT is simpler and cheaper. */
+export const DEFAULT_MULTIPART_THRESHOLD_BYTES = 100 * 1024 * 1024;
+
+/** Default bytes per part. With R2's 10,000-part cap this sets the ~625 GiB practical object ceiling. */
+export const DEFAULT_PART_SIZE_BYTES = 64 * 1024 * 1024;
+
+/** S3's floor for every part but the last. R2 rejects a completion that breaks it. */
+export const MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
+
+/** R2's per-part ceiling — the same 5 GiB that caps a single-part upload. */
+export const MAX_PART_SIZE_BYTES = 5 * 1024 * 1024 * 1024;
+
+/** R2's hard cap on parts in one multipart upload. */
+export const MAX_UPLOAD_PARTS = 10_000;
+
+/** One planned part: which number it is, where it starts, and how many bytes it carries. */
+export const PartPlan = z
+  .object({
+    partNumber: z.number().int().min(1).describe("The part's 1-based index. R2 requires them contiguous from 1."),
+    offset: z.number().int().nonnegative().describe("The part's first byte offset within the whole object."),
+    length: z.number().int().positive().describe("The part's byte count. Every part but the last is `partSize`."),
+  })
+  .describe("One part of a planned multipart upload — the unit a client uploads and can re-send alone.");
+export type PartPlan = z.output<typeof PartPlan>;
+
+/** The whole plan for one object: the part size in force and every part it decomposes into. */
+export const MultipartPlan = z
+  .object({
+    partSize: z.number().int().min(MIN_PART_SIZE_BYTES).describe("Bytes per part, for every part but the last."),
+    partCount: z.number().int().min(1).describe("How many parts the object decomposes into."),
+    parts: z.array(PartPlan).min(1).describe("Every part, ascending by `partNumber`."),
+  })
+  .describe("How one object is split for a multipart upload — the plan a client uploads against.");
+export type MultipartPlan = z.output<typeof MultipartPlan>;
+
+/** One part as the client reports it back after its PUT: the number it uploaded and the ETag R2 answered with. */
+export const ReportedPart = z
+  .object({
+    partNumber: z.number().int().min(1).max(MAX_UPLOAD_PARTS).describe("The part number this ETag belongs to."),
+    etag: z.string().min(1).describe("The `ETag` response header R2 returned for that part, verbatim."),
+  })
+  .describe("One completed part, as the client reports it back — the input to completing an upload.");
+export type ReportedPart = z.output<typeof ReportedPart>;
+
+/** Whether an upload of `size` bytes should go multipart under `threshold`. */
+export function needsMultipart(size: number, threshold: number = DEFAULT_MULTIPART_THRESHOLD_BYTES): boolean {
+  return size > threshold;
+}
+
+/**
+ * Split `size` bytes into parts of `partSize`.
+ *
+ * Throws `storage/multipart_failed` when the plan cannot exist: a part size outside R2's 5 MiB–5 GiB
+ * window, or a size that needs more than 10,000 parts. Both are configuration faults surfaced at
+ * plan time — before a client has uploaded anything against a plan R2 would refuse to complete.
+ */
+export function planMultipart(size: number, partSize: number = DEFAULT_PART_SIZE_BYTES): MultipartPlan {
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new StorageMultipartFailedError({
+      message: "An upload needs a positive size.",
+      action: "Declare the file's byte count when you start the upload.",
+      detail: `multipart plan requested for size ${size}`,
+    });
+  }
+  if (!Number.isInteger(partSize) || partSize < MIN_PART_SIZE_BYTES || partSize > MAX_PART_SIZE_BYTES) {
+    throw new StorageMultipartFailedError({
+      message: "The configured part size is outside what R2 accepts.",
+      action: "Set `partSizeBytes` between 5 MiB and 5 GiB in pithy.config.ts.",
+      detail: `partSize ${partSize} is outside [${MIN_PART_SIZE_BYTES}, ${MAX_PART_SIZE_BYTES}]`,
+    });
+  }
+
+  const partCount = Math.ceil(size / partSize);
+  if (partCount > MAX_UPLOAD_PARTS) {
+    throw new StorageMultipartFailedError({
+      message: "That file is too large for the configured part size.",
+      action: `Raise \`partSizeBytes\` — R2 allows at most ${MAX_UPLOAD_PARTS} parts per upload.`,
+      detail: `size ${size} at partSize ${partSize} needs ${partCount} parts`,
+    });
+  }
+
+  const parts: PartPlan[] = [];
+  for (let index = 0; index < partCount; index += 1) {
+    const offset = index * partSize;
+    // Only the final part may be short — that is the whole content of S3's 5 MiB floor.
+    parts.push({ partNumber: index + 1, offset, length: Math.min(partSize, size - offset) });
+  }
+  return { partSize, partCount, parts };
+}
+
+/**
+ * Turn the parts a client reports into the list R2's completion call takes: validated, deduplicated,
+ * and ascending.
+ *
+ * Sorting is not cosmetic — S3 rejects an out-of-order part list, and the order concurrent PUTs
+ * finish in is not the order the parts belong in. A gap, a duplicate, or a count that disagrees with
+ * the plan is refused here rather than sent to R2, because R2's own rejection arrives as an opaque
+ * SDK fault with nothing in it a client could act on.
+ */
+export function collectParts(reported: readonly ReportedPart[], expectedCount: number): ReportedPart[] {
+  const parsed = z.array(ReportedPart).safeParse(reported);
+  if (!parsed.success) {
+    throw new StorageMultipartFailedError({
+      detail: `reported parts failed validation: ${parsed.error.issues.map((i) => i.code).join(", ")}`,
+    });
+  }
+
+  const byNumber = new Map<number, string>();
+  for (const part of parsed.data) {
+    const existing = byNumber.get(part.partNumber);
+    if (existing !== undefined && existing !== part.etag) {
+      throw new StorageMultipartFailedError({
+        message: "Part list is inconsistent.",
+        detail: `part ${part.partNumber} reported twice with different etags`,
+      });
+    }
+    byNumber.set(part.partNumber, part.etag);
+  }
+
+  if (byNumber.size !== expectedCount) {
+    throw new StorageMultipartFailedError({
+      message: "The upload is missing parts. GET /storage/<id>/parts, then re-send the parts it reports missing.",
+      detail: `expected ${expectedCount} distinct parts, got ${byNumber.size}`,
+    });
+  }
+
+  for (let partNumber = 1; partNumber <= expectedCount; partNumber += 1) {
+    if (!byNumber.has(partNumber)) {
+      throw new StorageMultipartFailedError({
+        message: "The upload is missing parts. GET /storage/<id>/parts, then re-send the parts it reports missing.",
+        detail: `part ${partNumber} was never reported`,
+      });
+    }
+  }
+
+  return [...byNumber.entries()]
+    .map(([partNumber, etag]) => ({ partNumber, etag }))
+    .sort((a, b) => a.partNumber - b.partNumber);
+}

package/src/object/store.ts

@@ -0,0 +1,371 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { R2Bucket, R2Conditional, R2Object, R2Range, ReadableStream } from "@cloudflare/workers-types";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import { z } from "zod";
+import { type R2StorageCredentials, r2CredentialsRegistry, STORAGE_R2_SECRET } from "../secret/registry";
+import { r2Presigned } from "./cloudflare";
+import type { ReportedPart } from "./multipart";
+
+/**
+ * `ObjectStore` — the object-plane seam, and the one piece of this package that is reusable outside it.
+ *
+ * **The load-bearing constraint: this module imports no D1, no routes, and no storage config.** It is
+ * constructed over an injected bucket binding and a *named* credential secret, which is exactly what
+ * lets `@pithy-sh/media` import it, point it at `MEDIA_BUCKET` under `media-r2-credentials`, and
+ * inherit none of storage's tables, routes, or opaque-key policy. Adding `@pithy-sh/storage` to media
+ * must not mount storage's routes or create `pithy_storage_objects`; keeping this file free of those
+ * imports is what guarantees it.
+ *
+ * It is **mechanism only**. It takes an explicit key and moves bytes. Key policy lives in `key.ts` and
+ * in the handlers: storage derives `obj/<uuid>`, media passes `media/<type>/<id>`, and neither knows
+ * the other's scheme.
+ *
+ * **Bindings inside the Worker, S3 outside it** (CLAUDE.md §Cloudflare access). Reads, head, list and
+ * delete go through the `R2Bucket` binding — no credentials, no round trip, and a body that streams.
+ * Presigned URLs, the multipart lifecycle, and server-side copy have no binding equivalent that keeps
+ * bytes out of the Worker, so they go over the S3 protocol through `@pithy-sh/cloudflare`. The seam
+ * hides which is which; only `object/cloudflare.ts` touches the manager.
+ *
+ * Every response crossing the seam is Zod-validated, so an unexpected shape fails loudly at the
+ * boundary rather than surfacing as `undefined` three layers up.
+ */
+
+/** An object's metadata, as either a HEAD or a GET reports it. */
+export const ObjectMetadata = z
+  .object({
+    key: z.string().min(1).describe("The R2 object key. Opaque to the caller — policy lives in `key.ts`."),
+    size: z.number().int().nonnegative().describe("The whole object's size in bytes, not the served range's."),
+    etag: z
+      .string()
+      .min(1)
+      .describe("R2's entity tag for this object version, unquoted. Quote it before it becomes an `ETag` header."),
+    contentType: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("The stored `Content-Type`. Absent when the object was written without one."),
+    contentDisposition: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "The stored `Content-Disposition`, when one was written. Recorded, not honored — the serve path derives its own, because this string is whatever the uploader sent.",
+      ),
+    uploaded: z.date().describe("When R2 wrote this object version."),
+    checksumSha256: z
+      .string()
+      .regex(/^[0-9a-f]{64}$/)
+      .optional()
+      .describe("Lowercase hex SHA-256, when R2 holds one. Absent unless the upload supplied or requested it."),
+  })
+  .describe("One object's metadata — everything a serve path needs without transferring the body.");
+export type ObjectMetadata = z.output<typeof ObjectMetadata>;
+
+/** Which bytes of an object to read. Mirrors R2's own range shapes; exactly one form is meaningful. */
+export const ObjectRange = z
+  .object({
+    offset: z.number().int().nonnegative().optional().describe("First byte to read, from the start of the object."),
+    length: z.number().int().positive().optional().describe("How many bytes to read from `offset`."),
+    suffix: z.number().int().positive().optional().describe("Read this many bytes from the *end* — `bytes=-N`."),
+  })
+  .describe("A byte range to read, as an HTTP `Range` header maps onto R2.");
+export type ObjectRange = z.output<typeof ObjectRange>;
+
+/** Preconditions a read must satisfy, so a conditional request can answer 304 without moving bytes. */
+export const ObjectConditions = z
+  .object({
+    etagMatches: z.string().min(1).optional().describe("Read only if the object's etag equals this (`If-Match`)."),
+    etagDoesNotMatch: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("Read only if the object's etag differs (`If-None-Match`) — the 304 path."),
+    uploadedBefore: z
+      .date()
+      .optional()
+      .describe("Read only if the object was written before this (`If-Unmodified-Since`)."),
+    uploadedAfter: z
+      .date()
+      .optional()
+      .describe("Read only if the object was written after this (`If-Modified-Since`)."),
+  })
+  .describe("Conditional-read preconditions. R2 returns metadata with no body when one fails.");
+export type ObjectConditions = z.output<typeof ObjectConditions>;
+
+/** One page of a bucket listing — the sweep's view, distinct from the D1 listing an owner sees. */
+export const ObjectListing = z
+  .object({
+    objects: z.array(ObjectMetadata).describe("This page's objects, in R2's lexicographic key order."),
+    cursor: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("Continuation cursor for the next page. Absent means this page was the last."),
+  })
+  .describe("One page of a bucket listing. Pagination is caller-driven — pass `cursor` back to advance.");
+export type ObjectListing = z.output<typeof ObjectListing>;
+
+/** One part already stored against an in-flight multipart upload — what makes an upload resumable. */
+export const UploadedPart = z
+  .object({
+    partNumber: z.number().int().min(1).describe("The part's 1-based index within the upload."),
+    etag: z.string().min(1).describe("The part's entity tag, verbatim. Pass it back unchanged to complete."),
+    size: z.number().int().nonnegative().describe("The part's size in bytes, as R2 stored it."),
+  })
+  .describe("One uploaded part — the unit a resumed upload skips re-sending.");
+export type UploadedPart = z.output<typeof UploadedPart>;
+
+/** How long a presigned URL stays valid. */
+export interface PresignOptions {
+  /** Lifetime in seconds. Defaults to one hour — long enough for a large part, short enough to leak little. */
+  expiresIn?: number;
+}
+
+/** Presign options for one part, which may additionally pin its exact byte count. */
+export interface PresignPartOptions extends PresignOptions {
+  /** Exact byte count the client must send. Omitted by default; see `presignPart`. */
+  contentLength?: number;
+}
+
+/** What to read, and under what preconditions. */
+export interface GetOptions {
+  /** Serve only this byte range (206). */
+  range?: ObjectRange;
+  /** Serve only if these preconditions hold; otherwise the result carries metadata and no body (304). */
+  onlyIf?: ObjectConditions;
+}
+
+/** Which slice of the bucket to list. */
+export interface ListOptions {
+  /** Only keys starting with this prefix. Omitted lists the whole bucket. */
+  prefix?: string;
+  /** Continuation cursor from a previous page. */
+  cursor?: string;
+  /** Page size. R2 caps this at 1,000. */
+  limit?: number;
+}
+
+/** An object read: its metadata, its bytes, and the range R2 actually served. */
+export interface ObjectBody {
+  /** The whole object's metadata — `size` is the object's, not the range's. */
+  metadata: ObjectMetadata;
+  /** The bytes, streamed. `null` when a precondition failed, which is the 304 signal. */
+  body: ReadableStream | null;
+  /** The byte range R2 served, when a range was asked for. `null` means the whole object. */
+  range: { offset: number; length: number } | null;
+}
+
+/**
+ * The S3-protocol half of the seam: everything the R2 binding cannot do without pulling bytes through
+ * the Worker. Declared here as a structural port so `store.ts` never imports `@pithy-sh/cloudflare`,
+ * and so a test can drive the store with no SDK and no network.
+ */
+export interface PresignedObjects {
+  /**
+   * Presign a PUT for one whole object. The length is signed, so the client must send exactly that many
+   * bytes. The type is **not** — S3 presigning marks `content-type` unsignable — so it is a hint the
+   * completion reconciles against what R2 actually stored.
+   */
+  presignPut(key: string, contentType: string, contentLength: number, options?: PresignOptions): Promise<string>;
+  /** Presign a GET for one object. */
+  presignGet(key: string, options?: PresignOptions): Promise<string>;
+  /** Open a multipart upload; returns the `uploadId` every later step is addressed by. */
+  createMultipartUpload(key: string, contentType: string): Promise<string>;
+  /** Presign a PUT for one part — the only multipart step a client ever touches. */
+  presignUploadPart(key: string, uploadId: string, partNumber: number, options?: PresignPartOptions): Promise<string>;
+  /** Assemble the uploaded parts into one object. */
+  completeMultipartUpload(key: string, uploadId: string, parts: readonly ReportedPart[]): Promise<void>;
+  /** Discard an in-flight upload and its stored parts. Idempotent. */
+  abortMultipartUpload(key: string, uploadId: string): Promise<void>;
+  /** List the parts already stored against an in-flight upload, ascending. */
+  listParts(key: string, uploadId: string): Promise<UploadedPart[]>;
+  /** Copy an object within the bucket, server-side — the bytes never leave R2. */
+  copyObject(sourceKey: string, destinationKey: string): Promise<void>;
+}
+
+/** The object plane: presigned transfer, the multipart lifecycle, and binding-backed reads. */
+export interface ObjectStore {
+  /** Presign a PUT the client uploads a whole object to. Bytes never proxy through the Worker. */
+  presignPut(key: string, contentType: string, contentLength: number, options?: PresignOptions): Promise<string>;
+  /** Presign a GET — the escape hatch for serving without a Worker in the byte path. */
+  presignGet(key: string, options?: PresignOptions): Promise<string>;
+  /** Open a multipart upload. Persist the returned `uploadId`: it is the handle a resume needs. */
+  initMultipart(key: string, contentType: string): Promise<string>;
+  /**
+   * Presign a PUT for one part. `contentLength` is **not** signed by default: the final part's length
+   * differs from every other, so signing it would mean knowing the total size at mint time. R2 enforces
+   * the 5 MiB floor and 5 GiB ceiling itself, and the object's real size is confirmed at completion.
+   */
+  presignPart(key: string, uploadId: string, partNumber: number, options?: PresignPartOptions): Promise<string>;
+  /** Assemble the reported parts into one object. Order and completeness are checked before R2 sees them. */
+  completeMultipart(key: string, uploadId: string, parts: readonly ReportedPart[]): Promise<void>;
+  /** Abort an in-flight upload. Idempotent, so a sweep or a retried teardown can re-run. */
+  abortMultipart(key: string, uploadId: string): Promise<void>;
+  /** The parts already stored against an in-flight upload — what a resuming client asks for. */
+  listParts(key: string, uploadId: string): Promise<UploadedPart[]>;
+  /** Read an object through the binding, honoring a range and conditional preconditions. `null` when absent. */
+  get(key: string, options?: GetOptions): Promise<ObjectBody | null>;
+  /** Read an object's metadata without its body. `null` when absent — a missing object is an answer. */
+  head(key: string): Promise<ObjectMetadata | null>;
+  /** One page of bucket keys. The orphan sweep's view; an owner's file list comes from D1. */
+  list(options?: ListOptions): Promise<ObjectListing>;
+  /** Server-side copy within the bucket. */
+  copy(sourceKey: string, destinationKey: string): Promise<void>;
+  /** Delete one object. Idempotent by protocol. */
+  delete(key: string): Promise<void>;
+}
+
+/** How to build an object store. */
+export interface ObjectStoreOptions {
+  /** The R2 bucket binding — `STORAGE_BUCKET` for storage, `MEDIA_BUCKET` for media. */
+  bucket: R2Bucket;
+  /**
+   * The env the credential secret resolves against. Only ever handed to `sharedSecretsStore`; no
+   * binding on it is read directly (CLAUDE.md §Secrets).
+   */
+  env: SecretsStoreEnv;
+  /**
+   * The registry name the R2 credential bundle is stored under. Whatever name is passed, the *same*
+   * capability must have declared it with `r2CredentialsRegistry(name)` — a name no capability
+   * declared is absent from the aggregated registry and throws on first use.
+   */
+  secretName?: string;
+  /**
+   * Test seam: build the S3 port from resolved credentials. Defaults to the real R2 adapter. Overriding
+   * it is how a test drives the store with no SDK, no credentials, and no network.
+   */
+  presigned?: (credentials: R2StorageCredentials) => PresignedObjects;
+}
+
+/** Map our range shape onto R2's — the binding's union admits exactly one of these three forms. */
+function toR2Range(range: ObjectRange | undefined): R2Range | undefined {
+  if (!range) return undefined;
+  if (range.suffix !== undefined) return { suffix: range.suffix };
+  if (range.offset !== undefined && range.length !== undefined) return { offset: range.offset, length: range.length };
+  if (range.offset !== undefined) return { offset: range.offset };
+  if (range.length !== undefined) return { length: range.length };
+  return undefined;
+}
+
+/** Lowercase hex for a checksum R2 hands back as raw bytes. */
+function toHex(buffer: ArrayBuffer): string {
+  return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Validate an `R2Object` into {@link ObjectMetadata} — the one place binding shapes cross the seam. */
+function toMetadata(object: R2Object): ObjectMetadata {
+  return ObjectMetadata.parse({
+    key: object.key,
+    size: object.size,
+    etag: object.etag,
+    contentType: object.httpMetadata?.contentType,
+    contentDisposition: object.httpMetadata?.contentDisposition,
+    uploaded: object.uploaded,
+    checksumSha256: object.checksums?.sha256 ? toHex(object.checksums.sha256) : undefined,
+  });
+}
+
+/**
+ * Build an object store over a bucket binding and a named credential secret.
+ *
+ * Credentials resolve **lazily, once**: a read-only worker that never presigns never touches the
+ * secrets store, and a worker that presigns twice resolves once. The promise itself is memoized, so
+ * two concurrent presigns share one resolution rather than racing two.
+ */
+export function objectStore(options: ObjectStoreOptions): ObjectStore {
+  const secretName = options.secretName ?? STORAGE_R2_SECRET;
+  const build = options.presigned ?? r2Presigned;
+  const bucket = options.bucket;
+  let presignedPromise: Promise<PresignedObjects> | null = null;
+
+  function presigned(): Promise<PresignedObjects> {
+    if (!presignedPromise) {
+      presignedPromise = (async () => {
+        const registry = r2CredentialsRegistry(secretName);
+        const store = await sharedSecretsStore(options.env, registry);
+        return build(store.get(secretName));
+      })();
+    }
+    return presignedPromise;
+  }
+
+  return {
+    async presignPut(key, contentType, contentLength, presignOptions) {
+      return (await presigned()).presignPut(key, contentType, contentLength, presignOptions);
+    },
+
+    async presignGet(key, presignOptions) {
+      return (await presigned()).presignGet(key, presignOptions);
+    },
+
+    async initMultipart(key, contentType) {
+      return (await presigned()).createMultipartUpload(key, contentType);
+    },
+
+    async presignPart(key, uploadId, partNumber, presignOptions) {
+      return (await presigned()).presignUploadPart(key, uploadId, partNumber, presignOptions);
+    },
+
+    async completeMultipart(key, uploadId, parts) {
+      await (await presigned()).completeMultipartUpload(key, uploadId, parts);
+    },
+
+    async abortMultipart(key, uploadId) {
+      await (await presigned()).abortMultipartUpload(key, uploadId);
+    },
+
+    async listParts(key, uploadId) {
+      return (await presigned()).listParts(key, uploadId);
+    },
+
+    async get(key, getOptions) {
+      const conditions = getOptions?.onlyIf;
+      const object = await bucket.get(key, {
+        range: toR2Range(getOptions?.range),
+        onlyIf: conditions ? (conditions as R2Conditional) : undefined,
+      });
+      if (!object) return null;
+      // A failed precondition yields an `R2Object` with no `body` — that absence *is* the 304 signal,
+      // so it is surfaced as a null body rather than swallowed as a miss.
+      const body = "body" in object ? object.body : null;
+      // R2 reports a range on *every* read, including a whole-object one. Only echo it when a range was
+      // asked for, so `range: null` keeps meaning "the whole object" and a serve path can key `206` off it.
+      const served = getOptions?.range && object.range ? object.range : undefined;
+      const offset = served && "offset" in served ? (served.offset ?? 0) : 0;
+      const length = served && "length" in served ? (served.length ?? 0) : 0;
+      return {
+        metadata: toMetadata(object),
+        body,
+        range: served ? { offset, length } : null,
+      };
+    },
+
+    async head(key) {
+      const object = await bucket.head(key);
+      return object ? toMetadata(object) : null;
+    },
+
+    async list(listOptions) {
+      const page = await bucket.list({
+        prefix: listOptions?.prefix,
+        cursor: listOptions?.cursor,
+        limit: listOptions?.limit,
+      });
+      return ObjectListing.parse({
+        objects: page.objects.map(toMetadata),
+        cursor: page.truncated ? page.cursor : undefined,
+      });
+    },
+
+    async copy(sourceKey, destinationKey) {
+      await (await presigned()).copyObject(sourceKey, destinationKey);
+    },
+
+    async delete(key) {
+      await bucket.delete(key);
+    },
+  };
+}