Public key-addressed web seam: fetchWebKey(key, request)

[gmoon]

Proposal

Promote the internal key-addressed path to the public web API:

// Caller names the S3 key; the Request contributes method (GET/HEAD) and
// conditional/Range headers. The request URL plays no role in key selection.
fetchWebKey(key: string, request: Request): Promise<Response>

fetchWeb then becomes a thin adapter over it:

fetchWeb(request) {
  return this.fetchWebKey(keyFromUrl(request), request);
}

No new behavior — this publishes a seam that already exists internally (fetchKey is private) and sharpens the v4 layering: URL→key mapping is adapter business; the core primitive is "stream this key with these request semantics."

Motivation

Today the public web API derives the key exclusively from the request URL path. Any consumer whose URL→key mapping is not identity has to fabricate a synthetic Request to smuggle the key through the URL:

// e.g. an app mounting a bucket under /files/*
const key = url.pathname.replace(/^\/files\//, '');  // derive key
url.pathname = `/${key}`;                             // re-embed in a URL
return proxy.fetchWeb(new Request(url, c.req.raw));    // s3proxy re-parses key from URL

The key round-trips key → URL-encode → Request → URL-parse → key. Three costs, ascending:

1. Waste — a synthetic URL + Request per request, and a duplicated parse.
2. Split ownership — "how a path becomes a key" lives in two places that must agree.
3. Encoding hazard (the real one) — the key is smuggled through URL encoding/decoding. For keys containing %, +, spaces, or the specialCharacters!... fixture already in the test bucket, the consumer's encoder and s3proxy's decoder must agree exactly, or the wrong object is served / a valid key 404s. Identity mapping never hits this; every rewriting consumer does.

Consumer classes that need non-identity mapping:

• Sub-path mounts — serving a bucket under /files/*, /assets/* inside an existing app
• Multi-tenant prefix injection — request identity resolves to a server-side key prefix (tenants/<org>/…) the client never sees; a security property, since the client shouldn't dictate the raw key
• Key rewriting — default documents, versioned keys, vanity paths

Design notes

• Alternative shape: an options override on the existing method — fetchWeb(request, { key }). Smaller surface; the separate method is arguably more honest (URL ignored vs. URL authoritative), maintainer's call.
• Contract to document: key is the raw S3 key (not URL-encoded); method must be GET/HEAD; Range/If-* headers flow through unchanged.
• Conformance case: fetchWebKey(weirdKey, req) must behave identically to a correctly-encoded fetchWeb for the special-characters fixture.

Estimated scope: ~10 lines plus tests. The cost is permanent public API surface on a deliberately minimal package — hence framing as promoting the existing internal seam, not adding a feature.

[gmoon]

Scope clarification: this is not GetObject with extra steps

A fair objection to pre-empt: isn't fetchWebKey(key, request) just duplicating the S3 SDK?

No — the signature is the tell. It takes a Request and returns a Response; the key argument only overrides which object. All of the value is in the HTTP ↔ S3 translation the SDK does not do:

Concern	Raw GetObjectCommand	fetchWebKey
Range → 206 + correct Content-Range	you translate it	passthrough, tested
If-None-Match → 304, If-Modified-Since	you translate it	passthrough
Unsatisfiable range → 416	SDK throws; you map it	mapped
Missing/denied key → 404/403	SDK throws; naive handlers emit 500s or empty 200s	typed error → correct status + body
ContentType/ETag/LastModified → HTTP headers	you map each one	mapped, conformance-tested
HEAD semantics	separate command	uniform
Node Readable → Web Response (backpressure, no buffering, mid-stream errors)	Readable.toWeb + edge cases	done

A true SDK duplicate would be fetchKey(key) → stream — object in, stream out, no HTTP anywhere. That is exactly what this proposal is not, and it should stay private.

The two signatures bracket the package's identity:

• fetchWeb(request) — URL picks the key + HTTP translation
• fetchWebKey(key, request) — caller picks the key + the same HTTP translation

Decision rule for consumers (worth putting in the docs if this ships): if you don't need an HTTP Response — backend processing, ETL, a bespoke API shaping its own headers — use the AWS SDK; s3proxy adds nothing there. s3proxy's scope is serving S3 objects over HTTP, correctly, and fetchWebKey stays inside that scope — it decouples object selection from URL parsing without expanding the package's job.