feat(web): hand an unscripted read its query as one URLSearchParams

A `method="get"` form submit replaces the action url's query with the form's
fields — which is why only an address in the path survives one — so what
arrives on an unscripted read is the form, not an argument encoding. Those
fields now reach the function as a lone `URLSearchParams`, the read-side
mirror of a no-JS form post decoding to a lone `FormData`:

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

HEAD reads it the same way, so a HEAD to a form url describes the GET response
that url would produce, arguments included.

The two readings of a query overlap in exactly one place: a bound action url
followed as a plain link carries an `args` that decodes as an argument array,
while a form field named `args` does not — so a decode failure falls through
to the form reading, and only there. A scripted caller sent an encoding, so
its failure stays a real one.

Author: frenzzy

.changeset/server-function-path-addressing.md

@@ -8,6 +8,8 @@ The id used to travel in `X-Server-Function-Id`, with `?id=` as the fallback for
 
 Arguments stay in the query. Standards-compliant caches and CDN defaults key on it, ordinary log tooling scrubs it, path normalization leaves it alone, and it is where bound arguments already ride for form posts — so a POST url does not become a hybrid of path-baked arguments plus a body.
 
+The query string is also what makes `method="get"` forms work at all: a GET submit replaces the action url's query with the form's fields, so an address in the path is the only kind that survives it, and an unscripted read now hands its whole query to the function as a lone `URLSearchParams` — the read-side mirror of a no-JS form post decoding to a lone `FormData`.
+
 `X-Server-Function-Id` is gone from the wire and from the package's exports; `X-Server-Function-Instance` still marks a scripted call, and `endpoint` keeps its meaning as the mount path. Both entries gain `serverFunctionUrl(id, boundArgs?)` and `parseServerFunctionUrl(url)` — the two halves of the addressing scheme, resolved against the configured endpoint — so integrations composing action urls (a router turning a bound action into a `<form action>` for the no-JS path) build them through the runtime instead of hand-rolling the shape.
 
 A GET call whose encoded url would exceed 2000 characters dispatches over POST instead: declaring GET grants the read methods without revoking the default transport, so the call still runs, it just stops being cacheable — a cache miss rather than a 414 from whichever proxy in the chain draws the line first.

documentation/solid-2.0/10-server-functions.md

@@ -118,7 +118,7 @@ The protocol folds integration data (typically revalidated route data) into a mu
 
 ### No-JS and progressive enhancement
 
-A reference’s `.url` serves as a form `action`, and action urls are **self-describing** (`<endpoint>/<id>?args=...`): an integration can reconstruct a callable from a server-rendered action url alone, with bound arguments kept in the query string where the server reads them for natural-encoding bodies. `serverFunctionUrl(id, boundArgs?)` and `parseServerFunctionUrl(url)` are the two halves of that scheme for integrations composing action urls the runtime did not render. The absence of the `X-Server-Function-Instance` header marks an unscripted call (a form submit or direct HTTP); arguments are parsed from the query string or FormData by content-type sniffing — a no-JS form post decodes to a lone `FormData` argument. The `handleNoJS` handler hook builds the response for these calls (default: the normal serialized response).
+A reference’s `.url` serves as a form `action`, and action urls are **self-describing** (`<endpoint>/<id>?args=...`): an integration can reconstruct a callable from a server-rendered action url alone, with bound arguments kept in the query string where the server reads them for natural-encoding bodies. `serverFunctionUrl(id, boundArgs?)` and `parseServerFunctionUrl(url)` are the two halves of that scheme for integrations composing action urls the runtime did not render. The absence of the `X-Server-Function-Instance` header marks an unscripted call (a form submit or direct HTTP); arguments are parsed from the query string or FormData by content-type sniffing — a no-JS form post decodes to a lone `FormData` argument, and an unscripted read hands its whole query over as a lone `URLSearchParams`, which is what a `method="get"` form submits (the browser replaces the action url's query with its fields, so only an address in the path survives one). The two readings of a query overlap in one place: a bound action url followed as a plain link carries an `args` that decodes, a form field named `args` does not. The `handleNoJS` handler hook builds the response for these calls (default: the normal serialized response).
 
 The full unscripted flow (flash cookie → redirect → SSR-seeded submission state) has a settled ownership chain:
 

packages/web/server-functions/src/server.ts

@@ -868,19 +868,39 @@ async function parseArguments(request, url, instance, codec) {
   // client stubs with bound arguments serialize the full argument array in
   // the body and never put arguments in the url.
   const bodyFormat = request.method === "POST" ? request.headers.get(BODY_FORMAT_HEADER) : null;
+  // A read made without the client runtime carries the form's own parameters,
+  // not an argument encoding: a `method="get"` submit replaces the action
+  // url's query with its fields (which is why only an address in the path
+  // survives one). They reach the function as a lone `URLSearchParams`, the
+  // read-side mirror of a no-JS form post decoding to a lone `FormData`.
+  const unscriptedRead = !instance && (request.method === "GET" || request.method === "HEAD");
+  let decodedArguments = false;
   if (!instance || request.method === "GET" || bodyFormat !== BodyFormat.Serialized) {
     const args = url.searchParams.get("args");
     if (args) {
-      // framed codec output (from the client runtime) or plain JSON (from
-      // integrations building no-JS urls by hand)
-      const result = args.startsWith(";0x")
-        ? await deserializeString(args, codec)
-        : JSON.parse(args);
-      for (const arg of result) {
-        parsed.push(arg);
+      try {
+        // framed codec output (from the client runtime) or plain JSON (from
+        // integrations building no-JS urls by hand)
+        const result = args.startsWith(";0x")
+          ? await deserializeString(args, codec)
+          : JSON.parse(args);
+        for (const arg of result) {
+          parsed.push(arg);
+        }
+        decodedArguments = true;
+      } catch (error) {
+        // The one place the two readings of a query overlap: a bound action
+        // url followed as a plain link carries `args` that decodes, a form
+        // field named `args` does not. Only the form reading survives a
+        // decode failure — a scripted caller sent an encoding, so its
+        // failure is a real one.
+        if (!unscriptedRead) throw error;
       }
     }
   }
+  if (unscriptedRead && !decodedArguments && url.search) {
+    parsed.push(url.searchParams);
+  }
   if (request.method === "POST" && request.body !== null) {
     const decoded = await extractBody(request.clone(), codec);
     // Both argument-array encodings: codec-framed and plain JSON.

packages/web/test/server/server-functions-addressing.spec.tsx

@@ -171,6 +171,50 @@ describe("server function addressing (built bundles)", () => {
     expect(parseServerFunctionUrl("/somewhere/else")).toBeNull();
   });
 
+  it("hands an unscripted read its own query as one URLSearchParams", async () => {
+    // What `<form method="get" action={fn.url}>` sends: the browser replaces
+    // the action url's query with the form's fields, and the address in the
+    // path is what survives it.
+    serverGET(
+      createServerSideReference(
+        registerServerReference("addr-form-0", async (params: URLSearchParams) => ({
+          q: params.get("q"),
+          page: params.get("page")
+        }))
+      )
+    );
+    const response = await unscripted("/_server/addr-form-0?q=solid&page=2");
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ q: "solid", page: "2" });
+  });
+
+  it("describes the same read on HEAD: same arguments, no body", async () => {
+    serverGET(
+      createServerSideReference(
+        registerServerReference("addr-form-2", async (params: URLSearchParams) => params.get("q"))
+      )
+    );
+    const response = await unscripted("/_server/addr-form-2?q=solid", { method: "HEAD" });
+    expect(response.status).toBe(200);
+    expect(response.body).toBeNull();
+  });
+
+  it("reads a field named `args` as a field, and a bound action url as arguments", async () => {
+    serverGET(
+      createServerSideReference(
+        registerServerReference("addr-form-1", async (value: URLSearchParams | string) =>
+          typeof value === "string" ? `bound:${value}` : `field:${value.get("args")}`
+        )
+      )
+    );
+    // a form whose field happens to be named `args`
+    expect(await (await unscripted("/_server/addr-form-1?args=hello")).text()).toBe("field:hello");
+    // a bound action url followed as a plain link
+    expect(await (await unscripted(serverFunctionUrl("addr-form-1", ["hello"]))).text()).toBe(
+      "bound:hello"
+    );
+  });
+
   it("keeps the address well-formed when the endpoint carries a trailing slash", () => {
     try {
       configureServerFunctionsClient({ endpoint: "/rpc/" });
@@ -198,4 +242,21 @@ describe("server function addressing (built bundles)", () => {
     expect(() => serverFunctionUrl("addr-bound-1", [new Date()])).toThrow(/JSON-safe/);
   });
 
+  it("still fails a scripted call whose argument encoding is broken", async () => {
+    // the form reading is for calls the client runtime did not make; a
+    // scripted caller sent an encoding, so a decode failure stays a failure
+    serverGET(
+      createServerSideReference(
+        registerServerReference("addr-broken-0", async (value: unknown) => typeof value)
+      )
+    );
+    await expect(
+      unscripted("/_server/addr-broken-0?args=not-an-encoding", {
+        headers: { "X-Server-Function-Instance": "server-function:test" }
+      })
+    ).rejects.toThrow();
+    // the same request without the instance header reads it as a form field
+    const asForm = await unscripted("/_server/addr-broken-0?args=not-an-encoding");
+    expect(await asForm.text()).toBe("object");
+  });
 });