RFC: QUERY method transport for server$ (RFC 10008) — deferred follow-up to #358

[maiieul]

RFC status: follow-up proposal, intentionally deferred. Companion to #358 (error handling).
Kept short on purpose — sized for one meeting review. It proposes when and how Qwik adopts the
new HTTP QUERY method, and confirms what #358 already does so that adopting it later costs
nothing.

The problem: the missing quadrant

HTTP never had a method for "a read with a big input". RFC 10008
(June 2026) fixes that with QUERY:

	GET	POST	QUERY
Request body	❌ (URL only, ~2KB practical)	✅	✅
Safe (no side effects → auto-retryable)	✅	❌	✅
Idempotent	✅	❌	✅
Cacheable	✅	❌	✅ (cache key includes a body digest)

Reads whose input doesn't fit a URL — faceted-search filter objects, vector/embedding arrays,
"fetch these 200 ids", GraphQL-ish queries — are forced into POST today, losing caching, dedupe,
and safe retry.

What Qwik has today

• server$(fn, { method: 'GET' }) already exists: args serialize into a qdata= search param and
  the function can set cacheControl() — cacheable, safe reads for small args. This is exactly
  the "GET equivalence" escape hatch h3 ships in h3#1448.
• Default POST: any input size, but uncacheable and not safely retryable.
• Loaders don't need QUERY and shouldn't get it: loader input must be reconstructible from the
  URL alone, because the SSR document request is a GET (URL-as-state contract). The gap is
  server$ reads only.

flowchart TD
    R["server read with arguments"] --> S{"args fit in a URL?"}
    S -- "yes" --> G["server$ method: 'GET'<br/>exists today — cacheable, safe"]
    S -- "no" --> M{"mutation?"}
    M -- "yes" --> P["server$ POST — correct"]
    M -- "no, a read" --> Q["server$ method: 'QUERY'<br/>this RFC — the missing quadrant"]

Loading

Proposal (later, small)

export const searchProducts = server$(
  async function (filters: ProductFilters) {
    this.cacheControl({ maxAge: 60 }); // meaningful: QUERY responses cache like GET
    return db.searchProducts(filters); // read-only by developer contract
  },
  { method: 'QUERY' }
);

A pure addition, because #358 (§5.3) pins server-function error handling as method-agnostic:

1. Client: send QUERY with the serialized-args body (same code path as POST; fetch() permits
   the method).
2. Server: register the server-function handler for QUERY.
3. Security: add QUERY to the CSRF origin-check list — it carries a body; "safe" doesn't exempt
   it (fail closed).
4. Docs: safe/idempotent is a developer promise, exactly like a GET handler anywhere.

Error semantics inherit from #358 unchanged: PublicError → 200 envelope + no-store; unexpected
→ 500 generic. Success responses may carry real cache headers — that's where QUERY earns its
keep. Bonus: safe + idempotent makes every retry path legitimate (async-computed
invalidate()/poll/expires, proxies, service workers) — none of which is kosher against POST.

Why deferred

RFC 10008 is weeks old. Browsers can send QUERY, but browser HTTP caches and CDNs don't cache
it yet (body-digest cache keys are new machinery), and some proxies will 405 it. Until infra
catches up, QUERY ≈ POST in practice; the GET mode we already ship is the part that caches today.
h3 hedges the same way (its QUERY handler optionally serves a GET twin). Waiting costs zero
code thanks to the method-agnostic invariant.

Decisions for the meeting

1. API shape: server$(fn, { method: 'QUERY' }) (proposed) vs a dedicated query$() twin?
2. Fallback: none — explicit method, loud failure on 405 (proposed) — vs auto-downgrade to
   POST? (Silent downgrade changes cache semantics; propose no.)
3. Confirm loaders are out of scope, permanently (URL-as-state).
4. Adoption trigger: propose revisiting once the RFC: Qwik v2 error handling — PublicError, fail(), and ErrorBoundary #358 error rework has shipped AND at least one
   major CDN announces QUERY caching (or h3/Nitro ship it stable and demand shows up).