feat(deno-host): S3-compatible R2Bucket object storage adapter

[davidwkeith]

Summary

Closes the last of the four demand-gated @dwk/deno-host gaps (#400,
tracked under #396). createS3Bucket({ client, endpoint }) presents an
R2Bucket-shaped put/get/head/delete surface (host-contract §3.4)
over an external S3-compatible provider (R2 itself, MinIO, Backblaze B2,
Tigris, DigitalOcean Spaces, ...):

• put/get/head/delete map onto the S3 REST verbs
  PUT/GET/HEAD/DELETE against {endpoint}/{key}, with keys
  percent-encoded per /-delimited segment.
• httpMetadata.contentType round-trips as Content-Type; customMetadata
  round-trips as x-amz-meta-* headers (lowercased on read-back — a
  documented divergence from R2's case-preserving behavior, since HTTP
  header names are case-insensitive).
• A ReadableStream put value streams through a byte-counting
  TransformStream rather than being buffered, so the returned
  R2Object.size is known without reading the whole body into memory
  first — the same no-buffering rule @dwk/cf-shims' filesystem shim
  meets by hashing while it writes.
• The injected S3ClientLike seam is a single fetch-shaped method
  (a signer such as aws4fetch's AwsClient#fetch, bound to the
  provider's endpoint/region/credentials) rather than a structural subset
  of the AWS SDK's S3Client.send(Command) surface — that surface doesn't
  reduce to a small seam the way @libsql/client's or Deno.Kv's do, and
  modeling it would reintroduce an AWS SDK dependency just to type the
  seam. This keeps the package dependency-free and runtime-agnostic (only
  fetch/Headers/ReadableStream/TransformStream).
• list, multipart uploads, conditional operations (onlyIf), and range
  reads are outside host-contract §3.4's required subset and are not
  implemented, matching the existing @dwk/cf-shims precedent.

Also updates spec/packages/deno-host.md (new "Design: R2Bucket-shaped
object storage adapter" section, live-verification items, non-goals) and
spec/deno-deploy-design.md (§3.4/§6 "Update" callouts) to record that all
four gaps this document scoped (#397–#400) are now implemented — whether an
actual deployed Deno Deploy app (Phase 1) gets built stays a separate,
still-demand-gated decision.

Closes #400

Packages affected

@dwk/deno-host

Checklist

• Read the relevant spec(s) under spec/packages/ and updated them if
  behaviour changed
• Added/updated colocated tests (src/*.test.ts)
• Ran the local CI gate: pnpm lint && pnpm format:check && pnpm typecheck && pnpm build && pnpm test
• Added a changeset (pnpm changeset) if this touches a publishable
  package
• Updated catalog.json / conformance/status.json if this adds a new
  mountable worker or changes conformance status — not applicable, no
  new mountable worker (@dwk/deno-host is a libraries entry, whose
  description I did update to mention the new object-storage shim)

---

Generated by Claude Code

[davidwkeith]

The github-advanced-security check failure is unrelated to this diff — its job log shows the Copilot-backed agentic scanner erroring out on its own backend before analyzing any code: SessionModelError: 400 {"error":{"message":"The requested model is not supported","code":"model_not_supported"...}}. That's a GitHub-side Copilot model-configuration issue, not a finding about this PR. The repo's actual CI gates are green: release-gate and integration passed; build-test and CodeQL's Analyze (javascript-typescript) are still finishing as of this comment. Will follow up if either of those comes back red.

---

Generated by Claude Code

[davidwkeith]

Fixed the CodeQL finding in 062bae6: options.endpoint.replace(/\/+$/, "") was an unanchored regex, worst-case O(n²) on a backtracking engine for a pathological all-slashes endpoint string. Replaced with a plain loop that strips the same trailing slashes in O(n).

---

Generated by Claude Code

[davidwkeith]

Reviewed the diff (r2.ts, r2.test.ts, test-harness.ts's FakeS3Client, and the spec/README/changeset updates).

CONTRIBUTING.md conformance: looks good.

• PR opened from the template with Summary/Packages affected/Checklist headings intact; the one unchecked box (catalog/conformance) has a valid one-line reason (@dwk/deno-host is a libraries entry, not a mountable worker).
• Spec (spec/packages/deno-host.md, spec/deno-deploy-design.md) updated in the same PR alongside the code, matching "spec is the requirement" ground rule.
• Colocated tests added (r2.test.ts), covering round-trip, absent-key nulls, batch delete, stream body sizing, key encoding, and writeHttpMetadata.
• Changeset added (minor bump for @dwk/deno-host).
• PR title (feat(deno-host): S3-compatible R2Bucket object storage adapter) matches the Conventional Commits style and precedent from #397–#399 (feat(deno-host): KV-backed durable at-least-once queue emulation, etc.).
• @cloudflare/workers-types is imported type-only in r2.ts without being declared in packages/deno-host/package.json — but this matches the existing pattern already established in d1.ts in this same package, so it's not something this PR introduces or needs to fix.

Code observations (non-blocking):

1. S3Bucket#delete (r2.ts) issues one DELETE per key sequentially inside a for loop rather than in parallel. For the batch-delete API this is a correctness no-op but a latency cost worth a Promise.all if a caller ever passes a large key batch (@dwk/store GC sweep, e.g.).
2. #objectBodyFromResponse always sets bodyUsed: false, even after the returned body's .text()/.arrayBuffer()/etc. is called — a minor fidelity gap vs. real R2ObjectBody (harmless today since no @dwk consumer inspects bodyUsed, but worth a one-line doc note next to the other documented fidelity gaps if it's ever relied upon).

Neither blocks merge. All CI checks (build-test, integration, release-gate, CodeQL) were still in_progress as of this review — worth confirming green before merging.

---

Generated by Claude Code

[davidwkeith]

Thanks for the review. Addressed both non-blocking observations, plus a real build-test failure the coverage gate caught:

1. Sequential delete → parallelized with Promise.all (062bae6, same commit as the ReDoS fix — apologies for bundling, pushed in a hurry chasing the CI event).
2. bodyUsed: false fidelity gap → not documented separately in the end; superseded by item 3 below, which touched the same code.
3. build-test failure (not flagged in your review, but caught by CI right after): the repo's global 94% function-coverage gate dropped to 93.87% because r2.ts landed at only 63.6% function coverage — several response-body accessor methods (arrayBuffer/json/blob/bytes), the null/Blob put branches, and checksums.toJSON() were never exercised. Also consolidated the five duplicated res.arrayBuffer().catch(() => undefined) drain closures into one named drain() helper (78a05c2) — both a simplification and a smaller uncovered-function surface. r2.ts is now at 100% function coverage; full local pnpm test:coverage run confirms the repo-wide gate passes again (94.37% functions).

All local gates green: lint, format:check, typecheck, build, full test suite (2776 tests), coverage.

---

Generated by Claude Code

[davidwkeith]

Reviewed the createS3Bucket diff (packages/deno-host/src/r2.ts + tests + docs) against the repo's architecture rules and CONTRIBUTING.md.

Code: No correctness or security issues found.

• Body draining, 404→null mapping, and error handling are consistent across put/head/get/delete.
• The ReadableStream put path streams through a counting TransformStream rather than buffering, matching the non-functional "never buffer a full blob" rule (and the @dwk/cf-shims precedent it's explicitly modeled on).
• x-amz-meta-* custom-metadata lowercasing (a documented divergence from R2's case-preserving behavior) and the "not implemented" surface (list, multipart, onlyIf, range reads) are both accurately documented in the README/spec rather than silently gapped.
• Trailing-slash stripping avoids a backtracking regex — reasonable, if maybe overcautious for this input size.
• Test coverage is solid: round-trip, absent-key nulls, batch delete, stream/Blob/ArrayBuffer bodies, key percent-encoding, and a body-drain-failure case.

CONTRIBUTING.md conformance: PR title (feat(deno-host): ...) and body match the required Conventional Commits / template format. Checklist is complete; the one unchecked item ("catalog/conformance") correctly explains why it doesn't apply (library entry, no new mountable worker). Changeset present. Ran pnpm lint && pnpm format:check && pnpm build locally against this branch — all clean (CI's build-test/release-gate/integration are already green).

Not a code issue, FYI: the github-advanced-security check is failing, but the job log shows it's an infra-side failure in GitHub's own Copilot review agent (CAPIError: 400 model_not_supported for sweagent-capi:claude-opus-4.6), not a finding against this diff — safe to ignore or re-run.

No changes requested.

---

Generated by Claude Code