Server functions: address calls as /_server/<id> so GET can reach the web infrastructure it was built for

[frenzzy]

Async Solid — One Graph, Two Machines puts the goal of the GET helper plainly:

GET puts the arguments on the url and sends a GET request. That one change gives us access to 30 years of web infrastructure: browser caches, CDN edges, proxies.

I've been reading the 2.0 server-function runtime with exactly that sentence in mind, and I
think the addressing deserves a second look, because it decides how much of that
infrastructure is actually reachable. Today the identity of a call lives in the query string —
/_server?id=…&args=… (client.ts:674-692) with X-Server-Function-Id as the authoritative
source (server.ts:844-850). Caches, proxies, WAFs, service workers, access logs and HTML
forms all key on the path; a query-only address is the one shape most of that
infrastructure either ignores or normalizes away.

Everything below is verified against the published @solidjs/web@2.0.0-rc.3; line references
are next @ f5939ef. Three concrete defects came out of the same reading and are filed
separately: HEAD bypassing the method gate (#3069), the id header overriding the URL
(#3070), and the cache headers on responses (#3071). This post is about the
part that isn't a bug — the default shape.

An HTML GET form cannot address a server function at all

Per the form submission algorithm, a method="get" submit discards the action URL's query
and replaces it with the serialized form data ("mutate action URL": url.query = <form data>).
So <form method="get" action={fn.url}> ships /_server?<fields>, the id is gone, and:

GET /_server?q=solid   ->   404 Server function not found

The only workaround is a hidden <input name="id">, sitting in the same namespace as the
user's own fields. And even then the fields aren't arguments — parseArguments
(server.ts:852-883) reads exactly one name, args, and expects the whole argument array as
one encoded string:

GET /_server?id=echo-0&q=solid&page=2                  ->  arguments received: []
GET /_server?id=echo-0&args=%5B%22solid%22%2C2%5D      ->  arguments received: ["solid", 2]

So a no-JS GET form can only ever send arguments hardcoded into a hidden field. Meanwhile the
POST side of progressive enhancement is fully designed: fn.url survives (POST keeps the
action query), the fields arrive as a single FormData argument, and createNoJSHandler
redirects back with a flash cookie (server.ts:1103-1146). GET has no equivalent —
isFormPost is POST-only by construction (server.ts:1158), so a GET form navigation lands on
/_server?… displaying raw JSON.

What else the path buys, including for POST

• Per-function policy at the edge. Cache TTLs, rate limits, WAF exceptions, edge auth,
  routing one heavy function to a different upstream — Envoy, nginx, CDN rules and API gateways
  all express this as a path prefix; query matching is second-class or absent. Today every call
  in an app is one route, POST /_server. This part matters for POST as much as GET.
• Observability. http.route is /_server for everything, and the discriminator sits in a
  header access logs don't record by default. Per-function latency and error rate — the first
  thing anyone asks of an RPC layer — needs custom parsing today.
• Service workers. registerRoute(/^\/_server\//) is trivial; matching a query parameter
  is not. And caches.match(request, { ignoreSearch: true }) collapses every call into one entry.
• Prefetch and speculation rules. RFC 10 already names preload URLs as a router use case;
  path patterns are what that tooling is written against.
• Cache-key robustness. A zone configured to ignore query strings in the cache key (Bunny's
  IgnoreQueryStrings, CloudFront's legacy "forward query strings: none") gives every server
  function in the app the same cache key. With the id in the path, a misconfigured zone is
  still wrong about arguments, but the blast radius is one function instead of "any function's
  body may be served in place of any other". A default should degrade into a stale answer, not
  into another feature's data.
• WAF false positives. A percent-encoded JSON blob in the query (%5B%22, brackets,
  quotes) trips common ModSecurity/CRS injection rules; plain named parameters don't.

Proposal

1. Address every call at /_server/<encodeURIComponent(id)>, GET and POST alike. .url
   stays self-describing (/_server/<id>?args=…), so an integration can still reconstruct a
   callable from a server-rendered action url. Ids are path-safe already (<hash>-<count>,
   <hash>-<count>-<name> in dev).

2. No-JS GET forms: for an unscripted call (no X-Server-Function-Instance) with no
   decodable args, pass the whole query string as a single URLSearchParams argument — the
   exact mirror of the no-JS POST convention, where the body decodes to a lone FormData. Then
   this works with no hidden fields and no client runtime:

   <form method="get" action={search.url}>
     <input name="q" />
     <button>Search</button>
   </form>
   <!-- GET /_server/abc-0?q=solid -->

3. Keep ?args= as the canonical encoding for scripted calls. A field literally named args
   is the only collision; treating args as the argument array only when it decodes as one
   (codec frame or JSON array) is a robust tiebreak.

Things worth settling alongside

• Canonicalization. JSON.stringify(args) (client.ts:678) preserves object key insertion
  order, so the same logical call from two call sites can produce two cache entries. Sorting
  keys when encoding for a URL makes the cache key canonical.
• URL length. Nothing caps the encoded arguments and nothing falls back to POST, so a large
  argument becomes a 414 somewhere in the stack (nginx ~8k request line, IIS 2048 query, CDNs
  8–16k). A documented cap with a directed error beats an infrastructure-dependent failure.
• Conditional requests. No ETag/If-None-Match story and no defined transport behavior
  for a 304 — revalidation is a large part of why GET is worth being on.
• Safety. GET is safe by contract: prefetchers, proxies and retry layers replay it freely, so
  a GET(fn) with side effects will be called more than once. Worth stating next to GET.
• Argument leakage. URL arguments reach Referer, CDN and proxy access logs, and browser
  history — inherent to any GET encoding, but it deserves a note.

Alternatives I considered

• Leave it to CDN configuration (allow-list id and args in the cache key). Works, but
  it's per-zone configuration whose failure mode is serving another function's response.
  Correctness that depends on every intermediary being configured correctly isn't a default.
• Positional query parameters (?arg1=&arg2=) as the scripted encoding. Loses types, has no
  encoding for undefined/holes/objects/cycles, collides with user-chosen field names in the
  no-JS case, and still needs the codec for anything non-primitive. One canonical args for
  scripted calls plus the whole query for unscripted ones matches how the two callers differ.
• A configurable addressing seam — endpoint accepting a builder plus
  resolveFunctionId/parseArguments options on the handler. Both halves already exist as
  private functions (client.ts:605, 674, 688, server.ts:844, 852), and prepareRequest
  deliberately never sees the URL (client.ts:339-353), so today addressing can't be changed
  without patching the package. Useful as an escape hatch, but most apps run on whatever core
  ships — which is the argument for fixing the default first.

Happy to put up a PR for any part of this, including the three bugs above, which are
independent of the addressing question and could land first.

[frenzzy]

A follow-up on the addressing part, because I think the version in the first post stops half way.

Moving only the id to the path doesn't fix the case that motivated it. On a zone that drops
the query from the cache key (Bunny's IgnoreQueryStrings, CloudFront's legacy "forward query
strings: none"), /_server/<id>?args=… still collapses every call to that function onto one
entry: right function, wrong arguments. If the address is moving, the whole address should move.

/_server/<id>[/<args>]

One extra segment carrying the argument array — base64url of exactly the string that ?args=
carries today, so the codec negotiation is untouched (a JSON array stays JSON; a value that needs
the codec still arrives as its ;0x… frame, just base64url'd, and the existing prefix check on
the server still discriminates them after decode).

fetchTopStories(10)              ->  GET /_server/a1b2c3-0/WzEwXQ
fetchStory("solid", 2)           ->  GET /_server/a1b2c3-1/WyJzb2xpZCIsMl0

It is also shorter than the query form, because percent-encoding a JSON blob is far more
expensive than base64:

arguments	?args= (percent-encoded)	path segment (base64url)
[10]	8	6
["solid",2]	21	15
[{"page":1,"tags":["a/b"]}]	59	36

Why one opaque segment rather than a readable segment per argument. Anything readable has to
survive the path, and the path is the most aggressively rewritten part of a URL: Envoy normalizes
it, nginx merges slashes, several CDNs decode %2F before matching — so a string argument
containing / cannot be carried as %2F reliably. A visible . in a segment is worse: it can
flip a CDN's extension-based caching rules (report.pdf as an argument getting the static-asset
TTL). The base64url alphabet (A–Z a–z 0–9 - _) produces none of %, /, .. Per-argument
segments would also need their own encoding for arity, holes, undefined and objects, and they
buy nothing for the cache key, which is the whole path either way. (One caveat worth writing down:
a zone configured for a case-insensitive cache key would corrupt base64url, and base32 —
~1.6× instead of ~1.33× — is the safe alternative there.)

What this buys beyond the cache key

The query string stops being ours. Path carries what the machine says — function id and
encoded arguments. Query carries what a human or a form says — named fields. Nothing overlaps,
which retires the args reserved name and with it the collision tiebreak I listed under "details
worth settling": a no-JS GET form's field named args can't collide with the runtime's encoding,
because the runtime no longer reads the query at all. The two callers stop sharing a namespace,
and the method="get" form convention (whole query as one URLSearchParams argument) becomes
unambiguous instead of heuristic.

X-Server-Function-Id stops being an addressing input, which closes #3070 by construction
rather than by rule — there is no second source of truth to disagree with the URL. Today the
header is written in exactly one place (client.ts:320) and read in exactly one
(server.ts:844-850), so removing it as an id source is contained.

Bound arguments stop needing the query too. action.with(id) currently appends ?args= to
the action url and puts the trailing FormData in the body (client.ts:411-442); those leading
arguments fit the same path segment, so a POST form action becomes /_server/<id>/<bound-args>
with the fields as the body — the same shape as today, minus the query.

Layering

This stays a transport mechanism, not policy: no router involvement, no compiler involvement (the
same reason GET needs none), and it adds no caching layer of its own — it makes the HTTP one
work. Which is the argument from the article itself: if the point of GET is 30 years of web
infrastructure, then the address has to be the shape that infrastructure actually keys on.

Cost

Roughly a hundred lines. The client builds the address in three places
(client.ts:605, 674, 688) and the transport already takes a fully-built base string, so live
(client.ts:826) inherits it for free and frameAddress is unaffected (it's a logical region
address, not a URL). The server reads it in two (resolveFunctionId, parseArguments). The one
piece worth adding is a shared address codec used by both halves — which also retires an existing
hazard, since endpoint today has to be configured identically on client and server by hand.

I'd argue for a single canonical shape rather than a "path" | "query" option: two shapes mean
two cache keys for the same call and two parse paths, and this branch has been explicit elsewhere
about no compatibility shims during the prerelease. If someone genuinely needs a different
address, that's the builder seam, not a second built-in.

Happy to put this up as a PR if the direction sounds right.

[ryansolid]

Agreed with the direction, with one split: the id belongs in the path, the args should stay in the query.

Id in path — yes. /_server/<id> is what per-function edge rules, path-pattern cache policies, log aggregation, and readable traces actually work with, and it fixes #3070 by construction: there is no id anywhere but the URL on the read path, so there is nothing for a header to override. POSTs move too — no caching reason, but the same legibility wins, and it lets the id header disappear entirely instead of surviving as the POST addressing channel.

Args in query — deliberately. Standards-compliant caches and every major CDN default already include the query string in the cache key, so /_server/<id>?args=... caches per-args correctly out of the box. What args-in-path defends against is a zone explicitly configured to ignore query strings — and pointing "cache everything, ignore query" at an API route is a config bug to document, not something to contort the addressing scheme around. Meanwhile the costs of args-in-path are real: args ride URLs on POSTs too (no-JS form posts, action.with-bound arguments), where path placement buys nothing and turns the URL into a hybrid of path-baked args plus body args; paths are treated as non-sensitive by every logging convention (query-scrubbing tooling is ubiquitous, path-scrubbing doesn't exist), which matters when args carry emails and search terms; and a big serialized blob has no graceful home in a path.

We're aware addressing is the kind of thing you'd rather break once — if there's a compelling case that args must be path-based, now is the time to make it. But "a misconfigured cache might ignore the query" hasn't cleared that bar for us.

Notes for whoever PRs this:

• Args encoding is deterministic for free — arguments are positional, so the serialization is ordered by construction. No canonicalization layer needed.
• URL length: the client transport should fall back to POST automatically when the encoded URL exceeds a threshold — a cache miss, not an error.
• Deploy skew is not this proposal's problem. A cached GET serving stale for its TTL after a deploy is the ordinary contract of Cache-Control, and it existed with query addressing too — it was just unreachable while the CSRF Vary defeated storage (fixed in Server function responses ship no Cache-Control, and a CSRF Vary that defeats GET caching #3071). Ids stay deploy-stable (long-lived tabs depend on that); staleness is the author's per-function knob. Docs note, not machinery.
• Export a URL builder. solid-router composes form-action URLs with bound args for the no-JS path; integrations should build addresses through an exported helper from server-functions rather than hand-rolling the scheme.

Groundwork already landed on next (#3069's method allowlist incl. HEAD, #3071's no-store default and Vary removal from declared reads), so this can be a pure addressing change on top.

[frenzzy]

Agreed — and the two downstream PRs are a better argument for the split than anything I wrote. #3076 is merged, solidjs/solid-router#590 and solidjs/solid-vite-plugin#332 adopt it, and between them they show where a call's address is actually known: the runtime, the plugin's dev middleware (which also pre-evaluates the owning module so the registration exists), the generated dispatchRequest gate, and the router's actionBase interception. Four places, three packages.

That settles the question I came in with. Argument placement should not be a knob in core. A second built-in shape would have to be taught to all four of those gates, and every integration downstream would have to handle both. One canonical shape is worth more than the flexibility.

What I'd still like to leave in the thread is the userland answer, because it turns out to need none of that.

An app that wants a cache-shaped url does not need a second server-function address — it needs an ordinary route that delegates. The handler takes a web Request and derives everything from it:

// GET /api/stories/42/2
import { getStory } from "./stories";           // registers the function
import { serverFunctionUrl } from "@solidjs/web/server-functions";

export async function GET({ request }) {
  const [, , , story, page] = new URL(request.url).pathname.split("/");
  return handleServerFunctionRequest(
    new Request(new URL(serverFunctionUrl(getStory.id, [story, Number(page)]), request.url), request)
  );
}

new Request(url, request) carries the method, headers and body across. No gate has to learn anything: /api/stories/... is a route, and routes already work. Verified against next — answers 200 with the arguments the function expects. The one detail worth documenting is the import: the registry is keyed by id, so the module has to have been evaluated server-side, which referencing the function does for free.

The half that was missing is on the client. A scripted call had no way to reach that route. prepareRequest runs at exactly the right moment — last, over the final init with transport headers on it — but it is handed everything about the request except the part that addresses it.

TanStack Start solves the same problem with the smallest possible shape: serverFns.fetch, a (url, init) => Response every server function call goes through, plus a per-call override. No new vocabulary, the url is the first argument, and it composes with the things people want a transport seam for anyway — retries, telemetry, a test double.

Solid's transport already funnelled through a single fetch(base, init), so it came out small: #3080. Unlike a second address format it touches none of the four gates, because what the app fetches is its own route.

configureServerFunctionsClient({
  fetch: (address, init) => fetch(rewriteForCache(address), init)
});

Writing it turned up one thing worth flagging here. The observed path — the one observeServerFunctionCalls puts you on — handed the global fetch a Request rather than (base, init), so a wrapper written against the documented shape works in production and silently misroutes the moment devtools attach, resolving the call to undefined instead of erroring. The PR normalises both paths to one shape. The undefined half of that is an older, separate edge: a response the runtime did not produce isn't treated as a failure at all — a mis-mounted route, an auth interstitial or a CDN block all arrive as a successful undefined. Worth its own issue; say the word and I'll file it.

To be explicit: not a second built-in address, and not a reason to revisit the default. An app that opts out owns both ends and the consequences — its own cache key, its own WAF story, and the fact that a rendered .url stays canonical, because the server has to read action urls without the client's help.

If the shape reads wrong, say so and I'll change it or close it — the server half already unblocks anyone who needs this today, so there's nothing urgent behind it.