partial-content 1.0.0

package/src/r2.ts

@@ -0,0 +1,232 @@
+/**
+ * Cloudflare R2 native ObjectStore adapter for partial-content.
+ *
+ * Uses Cloudflare's native R2 bindings (`R2Bucket`) directly, without the
+ * AWS SDK. This eliminates the ~50-package `@aws-sdk/client-s3` dependency
+ * and its cold-start overhead in Workers.
+ *
+ * For S3-compatible access to R2 (e.g. from Node.js outside Workers),
+ * use `partial-content/s3` instead.
+ *
+ * @example
+ * ```typescript
+ * import { r2Store } from "partial-content/r2";
+ * import { serveObject } from "partial-content/hono";
+ *
+ * // In a Cloudflare Worker with R2 binding:
+ * app.get("/files/:key", serveObject(
+ *   r2Store({ bucket: env.MY_BUCKET }),
+ *   { key: (c) => c.req.param("key") },
+ * ));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import {
+  isOpenEndedRange,
+  guardStreamLength,
+  ObjectNotFoundError,
+  ObjectChangedError,
+  type ObjectStore,
+  type ObjectMetadata,
+  type ObjectStream,
+  type ParsedRange,
+} from "./index.js";
+
+// Re-export for convenience
+export { ObjectNotFoundError, ObjectChangedError };
+
+// ─── R2 Types ───────────────────────────────────────────────────────────────
+
+/**
+ * Minimal R2Bucket interface from Cloudflare Workers types.
+ *
+ * Declared locally to avoid a dependency on `@cloudflare/workers-types`.
+ * The shapes match the runtime behavior; type-checking is the caller's
+ * responsibility (their Worker project imports the full types).
+ */
+interface R2Bucket {
+  head(key: string): Promise<R2Object | null>;
+  /**
+   * With `onlyIf`, a failed precondition resolves to a body-less `R2Object`
+   * (not null, not an error) -- callers must check for `body`.
+   */
+  get(key: string, options?: R2GetOptions): Promise<R2Object | R2ObjectBody | null>;
+}
+
+interface R2Object {
+  key: string;
+  size: number;
+  etag: string;
+  uploaded: Date;
+  checksums: R2Checksums;
+  httpMetadata?: R2HttpMetadata;
+}
+
+interface R2ObjectBody extends R2Object {
+  body: ReadableStream<Uint8Array>;
+  range: R2Range;
+}
+
+interface R2Range {
+  offset: number;
+  length: number;
+}
+
+interface R2GetOptions {
+  // `length` is optional in the real R2 binding: offset alone reads to the
+  // end of the object (the open-ended fast-path form).
+  range?: { offset: number; length?: number };
+  onlyIf?: { etagMatches?: string };
+}
+
+interface R2Checksums {
+  sha256?: ArrayBuffer;
+}
+
+interface R2HttpMetadata {
+  contentType?: string;
+}
+
+// ─── Options ────────────────────────────────────────────────────────────────
+
+export interface R2StoreOptions {
+  /** The R2 bucket binding from the Worker environment. */
+  bucket: R2Bucket;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Convert an ArrayBuffer SHA-256 checksum to base64 for RFC 9530 Repr-Digest.
+ *
+ * `checksums.sha256` is R2's whole-object SHA-256 as raw bytes, so unlike the
+ * S3 adapter there is no `<base64>-<partCount>` composite string form to
+ * reject: a 32-byte buffer always describes the full representation. If R2
+ * ever exposes a per-part checksum in this field, this digest would need the
+ * same whole-object guard S3 applies.
+ */
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create an {@link ObjectStore} backed by a Cloudflare R2 bucket.
+ *
+ * @example
+ * ```typescript
+ * import { r2Store } from "partial-content/r2";
+ *
+ * export default {
+ *   async fetch(request, env) {
+ *     const store = r2Store({ bucket: env.MY_BUCKET });
+ *     const meta = await store.headObject("reports/q4.pdf");
+ *     // ...
+ *   },
+ * };
+ * ```
+ */
+export function r2Store(opts: R2StoreOptions): ObjectStore {
+  const { bucket } = opts;
+
+  // No `classifyStoreRead` here (unlike s3/gcs/azure): the R2 Workers binding
+  // signals its recoverable outcomes structurally, not as classifiable errors.
+  // Not-found is a `null` return, a failed `onlyIf` pin is a body-less object,
+  // and both are handled inline below. R2 exposes NO documented throttle/503
+  // error shape on the native binding (rate limiting surfaces at the Workers
+  // platform layer, before the handler runs), so there is nothing to map to
+  // `StoreUnavailableError`. Inventing a classifier for an undocumented error
+  // shape would be guessing; the README correctly omits R2 from the throttle-
+  // classification list. Use `partial-content/s3` (R2's S3 endpoint) if you
+  // need SlowDown/429 -> 503 mapping.
+  return {
+    supportsRange: true,
+    // 206 bounds/total come from the R2ObjectBody's actual size/offset: the
+    // orchestrator may skip the validating HEAD for plain range requests.
+    authoritativeRange: true,
+
+    async headObject(key: string, opts?: { signal?: AbortSignal }): Promise<ObjectMetadata> {
+      opts?.signal?.throwIfAborted();
+      const obj = await bucket.head(key);
+      if (!obj) throw new ObjectNotFoundError(key);
+
+      return {
+        contentLength: obj.size,
+        etag: obj.etag,
+        lastModified: obj.uploaded.toUTCString(),
+        digest: obj.checksums.sha256
+          ? arrayBufferToBase64(obj.checksums.sha256)
+          : undefined,
+      };
+    },
+
+    async getObject(key: string, opts?: { range?: ParsedRange; signal?: AbortSignal; ifMatch?: string }): Promise<ObjectStream> {
+      const { range, ifMatch } = opts ?? {};
+      opts?.signal?.throwIfAborted();
+      // An open-ended fast-path range (OPEN_ENDED sentinel end) reads to the
+      // end of the object: pass offset alone so R2 streams the tail rather
+      // than requesting a ~9e15 length.
+      const r2Range = range
+        ? (isOpenEndedRange(range)
+            ? { offset: range.start }
+            : { offset: range.start, length: range.end - range.start + 1 })
+        : undefined;
+
+      const getOptions: R2GetOptions | undefined = r2Range || ifMatch
+        ? {
+          ...(r2Range ? { range: r2Range } : {}),
+          // Pin the read to the validated representation. On mismatch R2
+          // returns the object WITHOUT a body (checked below).
+          ...(ifMatch ? { onlyIf: { etagMatches: ifMatch } } : {}),
+        }
+        : undefined;
+
+      const obj = await bucket.get(key, getOptions);
+      if (!obj) throw new ObjectNotFoundError(key);
+
+      // onlyIf precondition failed: R2 resolves with metadata but no body.
+      if (!("body" in obj) || !obj.body) {
+        throw new ObjectChangedError(key);
+      }
+
+      const body = obj as R2ObjectBody;
+      const totalSize = obj.size;
+
+      // Content-Range must reflect what R2 ACTUALLY returned, not what was
+      // requested. `body.range` is R2's authoritative offset/length for this
+      // response; if R2 clamped the range (object changed between HEAD and
+      // GET), fabricating from the request would corrupt the client's bytes.
+      const returned = range ? body.range : undefined;
+      const start = returned?.offset ?? range?.start;
+      const length = returned?.length
+        ?? (range
+          ? (isOpenEndedRange(range) ? totalSize - range.start : range.end - range.start + 1)
+          : undefined);
+
+      const isRanged = start !== undefined && length !== undefined;
+      const contentLength = isRanged ? length : totalSize;
+
+      return {
+        // Guard the committed length: if R2 ever ends the body short of the
+        // computed contentLength, error the stream rather than under-run it.
+        body: guardStreamLength(body.body, contentLength),
+        contentLength,
+        totalSize,
+        range: isRanged ? { start, end: start + length - 1 } : undefined,
+        etag: obj.etag,
+        lastModified: obj.uploaded.toUTCString(),
+        digest: obj.checksums.sha256
+          ? arrayBufferToBase64(obj.checksums.sha256)
+          : undefined,
+      };
+    },
+  };
+}

package/src/s3.ts

@@ -0,0 +1,324 @@
+/**
+ * S3-compatible ObjectStore adapter for partial-content.
+ *
+ * Implements the read-only {@link ObjectStore} interface from the kernel,
+ * wrapping `@aws-sdk/client-s3` HeadObject/GetObject commands. Covers:
+ *   - AWS S3
+ *   - Cloudflare R2 (S3-compatible mode)
+ *   - Hetzner Object Storage
+ *   - MinIO / Backblaze B2 / Wasabi
+ *
+ * For native R2 bindings (without the AWS SDK), use `partial-content/r2`.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const client = new S3Client({ region: "eu-central-1" });
+ * const store = s3Store({ client, bucket: "documents" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import {
+  S3Client,
+  GetObjectCommand,
+  HeadObjectCommand,
+  NoSuchKey,
+  NotFound,
+} from "@aws-sdk/client-s3";
+import {
+  ObjectNotFoundError,
+  ObjectChangedError,
+  StoreUnavailableError,
+  classifyStoreRead,
+  nodeStreamToWeb,
+  guardStreamLength,
+  resolveServedRange,
+  buildContentDisposition,
+  isOpenEndedRange,
+  type ObjectStore,
+  type ObjectMetadata,
+  type ObjectStream,
+  type ParsedRange,
+  type StoreErrorClassifiers,
+} from "./index.js";
+
+// Re-export for convenience
+export { ObjectNotFoundError, ObjectChangedError, StoreUnavailableError };
+
+// ─── S3 Body -> Web ReadableStream ──────────────────────────────────────────
+
+/**
+ * Convert an S3 SDK response Body to a web ReadableStream.
+ *
+ * The SDK Body is a web ReadableStream in Bun/Deno, a Node Readable in
+ * Node.js, and may expose `transformToWebStream()` as a convenience.
+ * We try each path in order of preference.
+ */
+function toWebStream(body: unknown, signal?: AbortSignal, expectedBytes?: number): ReadableStream<Uint8Array<ArrayBuffer>> {
+  // Every branch enforces the committed length: an S3-compatible backend that
+  // ends a body cleanly but short of ContentLength (some do in-flight body
+  // retries) must error the stream, not silently under-run the response. The
+  // web-stream branches are the ones Node aws-sdk v3 and Bun/Deno actually take,
+  // so guarding only the Node-Readable fallback would leave the guard dead.
+  if (body instanceof ReadableStream) {
+    return guardStreamLength(body, expectedBytes);
+  }
+  if (typeof (body as { transformToWebStream?: () => ReadableStream }).transformToWebStream === "function") {
+    return guardStreamLength(
+      (body as { transformToWebStream: () => ReadableStream<Uint8Array> }).transformToWebStream(),
+      expectedBytes,
+    );
+  }
+  // Node Readable fallback: the shared utility auto-detects destroy() and
+  // applies the same length guard internally.
+  return nodeStreamToWeb(body as AsyncIterable<Buffer | Uint8Array>, { signal, expectedBytes });
+}
+
+// ─── S3 ObjectStore Options ─────────────────────────────────────────────────
+
+export interface S3StoreOptions {
+  /** Pre-configured S3Client instance (BYOC, no config coupling). */
+  client: S3Client;
+  /** The S3 bucket name. */
+  bucket: string;
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create an {@link ObjectStore} backed by an S3-compatible bucket.
+ *
+ * @example
+ * ```typescript
+ * import { S3Client } from "@aws-sdk/client-s3";
+ * import { s3Store } from "partial-content/s3";
+ *
+ * const client = new S3Client({ region: "eu-central-1" });
+ * const store = s3Store({ client, bucket: "documents" });
+ *
+ * // Use with partial-content's evaluateConditionalRequest:
+ * const meta = await store.headObject("reports/q4.pdf");
+ * ```
+ */
+export function s3Store(opts: S3StoreOptions): ObjectStore {
+  const { client, bucket } = opts;
+
+  return {
+    supportsRange: true,
+    // 206 bounds/total are parsed from S3's actual Content-Range: the
+    // orchestrator may skip the validating HEAD for plain range requests.
+    authoritativeRange: true,
+
+    async headObject(key: string, opts?: { signal?: AbortSignal }): Promise<ObjectMetadata> {
+      const response = await classifyStoreRead(key, () => client.send(
+        // ChecksumMode is required for S3 to return ChecksumSHA256 at all;
+        // without it the digest would silently never be emitted.
+        new HeadObjectCommand({ Bucket: bucket, Key: key, ChecksumMode: "ENABLED" }),
+        { abortSignal: opts?.signal },
+      ), s3Classifiers);
+
+      if (response.ContentLength == null) {
+        throw new Error(`HeadObject returned no ContentLength for ${key}`);
+      }
+
+      return {
+        contentLength: response.ContentLength,
+        etag: response.ETag,
+        lastModified: response.LastModified?.toUTCString(),
+        digest: toReprDigest(response.ChecksumSHA256),
+      };
+    },
+
+    async getObject(key: string, opts?: { range?: ParsedRange; signal?: AbortSignal; ifMatch?: string }): Promise<ObjectStream> {
+      const { range, signal, ifMatch } = opts ?? {};
+      // Open-ended fast-path ranges (`bytes=a-`) carry the OPEN_ENDED
+      // sentinel end; emit the bare open form so no 16-digit last-byte-pos
+      // reaches the wire (S3 clamps it, but strict proxies may reject it).
+      const rangeHeader = range
+        ? (isOpenEndedRange(range) ? `bytes=${range.start}-` : `bytes=${range.start}-${range.end}`)
+        : undefined;
+
+      const response = await classifyStoreRead(key, () => client.send(
+        new GetObjectCommand({
+          Bucket: bucket,
+          Key: key,
+          ChecksumMode: "ENABLED",
+          // Pin the read to the validated representation: S3 rejects with
+          // 412 PreconditionFailed if the object changed since HEAD.
+          ...(ifMatch ? { IfMatch: ifMatch } : {}),
+          ...(rangeHeader ? { Range: rangeHeader } : {}),
+        }),
+        { abortSignal: signal },
+      ), s3Classifiers);
+
+      if (!response.Body) {
+        throw new Error(`S3 GetObject returned empty body for ${key}`);
+      }
+
+      const stream = toWebStream(response.Body, signal, response.ContentLength);
+
+      // A null ContentLength on a GET with a live body is a degenerate response:
+      // fabricating `0` would commit `Content-Length: 0` over real bytes (a wire
+      // framing error) and silently disable the short-read guard. headObject
+      // already fails loudly on this; mirror it -- cancel the body and throw.
+      if (response.ContentLength == null) {
+        stream.cancel().catch(() => { /* already-errored streams reject cancel */ });
+        throw new Error(`S3 GetObject returned no ContentLength for ${key}`);
+      }
+      const contentLength = response.ContentLength;
+
+      // Extract served bounds + total size from Content-Range
+      // (e.g. "bytes 0-999/5000") via the shared resolver, or fall back to
+      // ContentLength for full responses. A Content-Range S3 emits but the
+      // resolver cannot parse means the byte accounting is untrustworthy:
+      // cancel the live body and fail loudly rather than guess.
+      let totalSize: number | undefined;
+      let served: { start: number; end: number } | undefined;
+      if (response.ContentRange) {
+        const resolved = resolveServedRange(response.ContentRange);
+        if (!resolved) {
+          stream.cancel().catch(() => { /* already-errored streams reject cancel */ });
+          throw new Error(`S3 returned unparseable Content-Range for ${key}: ${response.ContentRange}`);
+        }
+        served = resolved.served;
+        totalSize = resolved.totalSize;
+      } else {
+        totalSize = contentLength;
+      }
+
+      return {
+        body: stream,
+        contentLength,
+        totalSize,
+        range: served,
+        etag: response.ETag,
+        lastModified: response.LastModified?.toUTCString(),
+        // Repr-Digest MUST hash the full representation. AWS omits the checksum
+        // on ranged GETs, but a non-conforming S3-compatible backend could
+        // return a range-scoped one; never advertise it as a whole-object
+        // digest. HEAD (always whole-object) and full 200s still carry it.
+        digest: served ? undefined : toReprDigest(response.ChecksumSHA256),
+      };
+    },
+
+    async createSignedUrl(key, signOpts) {
+      try {
+        // A signed URL is a 302 redirect target: the client fetches bytes
+        // DIRECTLY from S3, bypassing the serve route's security headers
+        // (nosniff, CSP, CORP). Force a download disposition AND an inert
+        // content type so a stored SVG/HTML polyglot cannot render inline off
+        // the header-less origin response. Both are S3 query-parameter
+        // overrides honored on the presigned GET; the stored object is
+        // untouched. `downloadFilename` only customizes the name.
+        const command = new GetObjectCommand({
+          Bucket: bucket,
+          Key: key,
+          ResponseContentType: "application/octet-stream",
+          ResponseContentDisposition: buildContentDisposition(
+            signOpts.downloadFilename ?? "download",
+            { type: "attachment" },
+          ),
+        });
+
+        // Lazy import: the presigner is an optional peer needed ONLY for
+        // signed URLs. A static import would crash `partial-content/s3` at
+        // module load for every consumer who installed just
+        // @aws-sdk/client-s3 (the documented baseline) and never presigns.
+        const { getSignedUrl } = await import("@aws-sdk/s3-request-presigner");
+        const url = await getSignedUrl(client, command, {
+          expiresIn: signOpts.expiresInSeconds,
+        });
+
+        return { ok: true as const, url };
+      } catch (err) {
+        return {
+          ok: false as const,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+  };
+}
+
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+
+/** A raw base64-encoded SHA-256 hash: exactly 43 base64 chars plus padding. */
+const SHA256_BASE64_RE = /^[A-Za-z0-9+/]{43}=$/;
+
+/**
+ * Validate an S3 checksum for use as an RFC 9530 representation digest.
+ *
+ * Multipart uploads produce composite checksums ("checksum-of-checksums")
+ * in the form `<base64>-<partCount>`, which do NOT hash the object bytes
+ * and are invalid inside `Repr-Digest: sha-256=:...:`. Only a plain
+ * base64 SHA-256 of the full object passes through.
+ */
+function toReprDigest(checksum: string | undefined): string | undefined {
+  return checksum && SHA256_BASE64_RE.test(checksum) ? checksum : undefined;
+}
+
+/**
+ * Check if an S3 error indicates the object does not exist.
+ *
+ * Covers:
+ *   - AWS SDK v3 `NoSuchKey` and `NotFound` error classes
+ *   - Generic S3-compatible providers that set `$metadata.httpStatusCode: 404`
+ *   - Providers that set `name: "NotFound"` without using the SDK error classes
+ */
+function isNotFoundError(err: unknown): boolean {
+  if (err instanceof NoSuchKey || err instanceof NotFound) return true;
+  if (err instanceof Error && err.name === "NotFound") return true;
+  const meta = (err as { $metadata?: { httpStatusCode?: number } }).$metadata;
+  if (meta?.httpStatusCode === 404) return true;
+  return false;
+}
+
+/**
+ * Check if an S3 error is a failed IfMatch precondition (object changed).
+ * The SDK surfaces this as name "PreconditionFailed" with HTTP 412.
+ */
+function isPreconditionFailedError(err: unknown): boolean {
+  if (err instanceof Error && err.name === "PreconditionFailed") return true;
+  const meta = (err as { $metadata?: { httpStatusCode?: number } }).$metadata;
+  return meta?.httpStatusCode === 412;
+}
+
+/**
+ * Check if an S3 error is a transient throttle/overload the client should
+ * retry (mapped to a 503, not a 502). The AWS SDK exhausts its own adaptive
+ * retries first, so reaching here means sustained pressure.
+ *
+ * Covers:
+ *   - `$retryable.throttling` (the SDK's own throttle classification)
+ *   - HTTP 503 (`SlowDown`) and 429 (`TooManyRequests`) on `$metadata`
+ *   - the named throttle errors S3-compatible backends raise without setting
+ *     an HTTP status code
+ */
+function isThrottledError(err: unknown): boolean {
+  if ((err as { $retryable?: { throttling?: boolean } }).$retryable?.throttling === true) return true;
+  const meta = (err as { $metadata?: { httpStatusCode?: number } }).$metadata;
+  if (meta?.httpStatusCode === 503 || meta?.httpStatusCode === 429) return true;
+  if (err instanceof Error) {
+    const name = err.name;
+    return (
+      name === "SlowDown" ||
+      name === "ThrottlingException" ||
+      name === "TooManyRequestsException" ||
+      name === "RequestThrottled" ||
+      name === "RequestThrottledException" ||
+      name === "ProvisionedThroughputExceededException"
+    );
+  }
+  return false;
+}
+
+/** The ordered error-classification set shared by headObject and getObject. */
+const s3Classifiers: StoreErrorClassifiers = {
+  notFound: isNotFoundError,
+  changed: isPreconditionFailedError,
+  throttled: isThrottledError,
+};