What

Stacked on #1448. Adds a get option to defineQueryHandler implementing RFC 10008 §2.3's cacheability guidance end-to-end: the same handler serves an equivalent, HTTP-cacheable GET, and successful QUERY responses advertise it via Content-Location — no server-side result store needed.

const searchBooks = defineQueryHandler({
  formats: ["application/sql", "application/jsonpath"],
  get: "q",
  handler: (event, { format, query }) => runQuery(format, query),
});
app.get("/books", searchBooks).query("/books", searchBooks);
// QUERY /books      -> 200 + Content-Location: /books?q=<query>&format=<format>
// GET  /books?q=... -> same result, ordinary HTTP caching applies
// HEAD /books?q=... -> same headers, empty body (via #1452's automatic GET matching)

Behavior

• With get set, the handler context gains query on both paths (body text on QUERY, URL param on GET/HEAD); without it, behavior is unchanged (typed via overloads).
• GET format comes from ?format= (customizable: get: { param, formatParam }); it may be omitted only when exactly one concrete (non-wildcard) format is accepted — silent defaulting across formats would change query semantics. All GET-path rejections are 400 (per RFC 9110, 415/422 apply to request content, which a GET has none of).
• Content-Location preserves the request's existing search params (a QUERY to /books?lang=en advertises /books?lang=en&q=…), is built via URLSearchParams, is skipped when the URL would exceed 2048 chars (long queries being the reason QUERY exists), and is never set on the GET path.
• HEAD needs no extra registration: h3 matches the GET route automatically (feat: automatically match GET routes for HEAD requests #1452), the handler runs with event.req.method === "HEAD", and the body is stripped downstream — so clients can revalidate/probe the advertised URL cheaply.
• Method guard becomes 405 + Allow: GET, HEAD, QUERY; Accept-Query stays on every response including errors.

Design review

The plan was adversarially reviewed by an agent against the codebase and the RFC text before implementation. Notable outcomes:

• Content-Location on 2xx confirmed as exactly RFC 10008 §2.3's mechanism (relative references valid per RFC 9110 §8.7).
• A companion cache: {...} option (wiring handleCacheHeaders) was dropped: it duplicates a documented one-liner, and handleCacheHeaders currently force-prepends public to Cache-Control and ORs If-None-Match/If-Modified-Since (RFC 9110 §13.2.2 wants ETag to take precedence) — worth fixing upstream before building sugar on it. Can open a separate issue.

Changes

• src/utils/query.ts: get option + overloads; src/utils/internal/query-get.ts: GET resolution + Content-Location helpers (keeps query.ts under the size guideline)
• test/query.test.ts: 13 new matrix tests (round-trip identity, param preservation, encoding, wildcard/ambiguous/missing-param 400s, length cutoff, HEAD via automatic GET matching, 405 Allow)
• examples/query.mjs: rewritten around get — drops the result Map, queryId hash, and /books/:id route (~30 lines shorter); curl comments include a HEAD probe
• Docs: new "Offer a Cacheable GET Equivalent" section (links to the routing guide's "HEAD Requests" section from feat: automatically match GET routes for HEAD requests #1452); fixed a wording error (QUERY responses are cacheable per §2.7, just not URL-addressable)

Test plan

• Rebased on main (includes feat: automatically match GET routes for HEAD requests #1452): full suite green — 1391 passed, no type errors, lint clean.

Disclaimer

🤖 This PR was written by Claude Code (design and implementation reviewed and directed by a human).

🤖 Generated with Claude Code