@solidjs/web 2.0.0-beta.20 → 2.0.0-beta.21

package/server-functions/dist/server.cjs

@@ -67,9 +67,30 @@ function configureServerFunctionsCodec(codec) {
 function getServerFunctionsCodec() {
   return codecConfig.codec;
 }
+function subscribeFlightData(consumer) {
+  return () => {
+  };
+}
+const SERVER_FUNCTION_METADATA = Symbol.for("solid.ServerFunctionMetadata");
+function getServerFunctionMetadata(fn) {
+  if (typeof fn !== "function") return undefined;
+  return fn[SERVER_FUNCTION_METADATA] || undefined;
+}
+function isServerFunction(fn) {
+  return typeof fn === "function" && !!fn[SERVER_FUNCTION_METADATA];
+}
+function withMeta(fn, meta) {
+  const metadata = getServerFunctionMetadata(fn);
+  if (!metadata) {
+    throw new Error("withMeta expects a server function reference");
+  }
+  Object.assign(metadata, meta);
+  return fn;
+}
 const FUNCTION_HEADER = "X-Server-Function-Id";
 const INSTANCE_HEADER = "X-Server-Function-Instance";
 const BODY_FORMAT_HEADER = "X-Server-Function-Format";
+const SINGLE_FLIGHT_HEADER = "X-Single-Flight";
 const FILE_FORM_KEY = "__server_function_file__";
 const BodyFormat = {
   Serialized: "0",
@@ -282,14 +303,17 @@ async function decodeResponse(response, codecOptions) {
 
 const config = {
   provideEvent: undefined,
+  collectFlightData: undefined,
   endpoint: "/_server"
 };
 function configureServerFunctionsServer({
   provideEvent,
+  collectFlightData,
   endpoint,
   codec
 } = {}) {
   if (provideEvent !== undefined) config.provideEvent = provideEvent;
+  if (collectFlightData !== undefined) config.collectFlightData = collectFlightData;
   if (endpoint !== undefined) config.endpoint = endpoint;
   if (codec !== undefined) configureServerFunctionsCodec(codec);
 }
@@ -300,6 +324,7 @@ function provideEvent(event, fn) {
   throw new Error("No request event provider. Configure one with configureServerFunctionsServer({ provideEvent }).");
 }
 const REGISTRATIONS = new Map();
+const METHODS = new Map();
 function registerServerFunction(id, callback) {
   REGISTRATIONS.set(id, callback);
   return callback;
@@ -311,24 +336,30 @@ function getServerFunction(id) {
   }
   throw new Error("invalid server function: " + id);
 }
-function registerServerReference(id, fn) {
+function registerServerReference(id, fn, name) {
   registerServerFunction(id, fn);
   return {
     id,
-    fn
+    fn,
+    name
   };
 }
 function createServerReference({
   id,
-  fn
+  fn,
+  name
 }) {
   if (typeof fn !== "function") throw new Error("Export from a 'use server' module must be a function");
+  const metadata = name === undefined ? {} : {
+    name
+  };
   return new Proxy(fn, {
-    get(target, prop, receiver) {
+    get(target, prop) {
+      if (prop === "id") return id;
       if (prop === "url") {
         return `${config.endpoint}?id=${encodeURIComponent(id)}`;
       }
-      if (prop === "GET") return receiver;
+      if (prop === SERVER_FUNCTION_METADATA) return metadata;
       return target[prop];
     },
     apply(target, thisArg, args) {
@@ -347,6 +378,15 @@ function createServerReference({
     }
   });
 }
+function GET(fn) {
+  if (!isServerFunction(fn) || typeof fn.id !== "string") {
+    throw new Error("GET expects a server function reference");
+  }
+  METHODS.set(fn.id, "GET");
+  return withMeta(fn, {
+    method: "GET"
+  });
+}
 function getServerFunctionMeta() {
   const event = getRequestEvent();
   return event && event.locals.serverFunctionMeta;
@@ -379,6 +419,15 @@ async function parseArguments(request, url, instance, codec) {
   }
   return parsed;
 }
+async function foldFlightData(hook, event, headers, outcome) {
+  const data = await hook(event, outcome);
+  if (data === undefined) return outcome.value;
+  headers.set(SINGLE_FLIGHT_HEADER, "true");
+  return {
+    value: outcome.value,
+    data
+  };
+}
 function serializedResponse(value, headers, codec) {
   headers.set(BODY_FORMAT_HEADER, BodyFormat.Serialized);
   headers.set("Content-Type", "text/plain");
@@ -421,11 +470,22 @@ async function handleServerFunctionRequest(request, options = {}) {
       status: 404
     });
   }
+  const allowedMethod = METHODS.get(functionId) || "POST";
+  if (request.method === "GET" !== (allowedMethod === "GET")) {
+    return new Response(process.env.NODE_ENV === "development" ? `Method not allowed for server function: ${functionId}` : null, {
+      status: 405,
+      headers: {
+        Allow: allowedMethod
+      }
+    });
+  }
   const event = options.createEvent ? options.createEvent(request) : {
     request,
     locals: {}
   };
   const provide = options.provideEvent || provideEvent;
+  const flightHook = options.collectFlightData !== undefined ? options.collectFlightData : config.collectFlightData;
+  const collectsFlight = !!(flightHook && instance && request.headers.has(SINGLE_FLIGHT_HEADER));
   const parsed = await parseArguments(request, url, instance, codec);
   const headers = new Headers();
   try {
@@ -442,6 +502,7 @@ async function handleServerFunctionRequest(request, options = {}) {
       });
     }
     let status = 200;
+    let metadata;
     if (isResponseEnvelope(result)) {
       const {
         response,
@@ -456,6 +517,7 @@ async function handleServerFunctionRequest(request, options = {}) {
       if (response && response.status && (response.status < 300 || response.status >= 400)) {
         status = response.status;
       }
+      metadata = response;
       result = value;
     } else if (result instanceof Response) {
       if (result.headers && result.headers.has("X-Content-Raw")) return result;
@@ -466,11 +528,21 @@ async function handleServerFunctionRequest(request, options = {}) {
         if (result.status && (result.status < 300 || result.status >= 400)) {
           status = result.status;
         }
+        metadata = result;
         if (result.body == null) {
           result = null;
         }
       }
     }
+    if (collectsFlight) {
+      result = await foldFlightData(flightHook, event, headers, {
+        id: functionId,
+        value: result,
+        response: metadata,
+        request,
+        thrown: false
+      });
+    }
     if (!instance) {
       if (options.handleNoJS) return options.handleNoJS(result, request, parsed);
       if (result instanceof Response) return result;
@@ -487,6 +559,7 @@ async function handleServerFunctionRequest(request, options = {}) {
         });
       }
       let status = 200;
+      let metadata;
       if (isResponseEnvelope(x)) {
         const {
           response,
@@ -498,6 +571,7 @@ async function handleServerFunctionRequest(request, options = {}) {
         if (response && response.status && (!instance || response.status < 300 || response.status >= 400)) {
           status = response.status;
         }
+        metadata = response;
         x = value;
       } else if (x instanceof Response) {
         if (x.headers) {
@@ -506,10 +580,20 @@ async function handleServerFunctionRequest(request, options = {}) {
         if (x.status && (!instance || x.status < 300 || x.status >= 400)) {
           status = x.status;
         }
+        metadata = x;
         if (x.body == null) {
           x = null;
         }
       }
+      if (collectsFlight) {
+        x = await foldFlightData(flightHook, event, headers, {
+          id: functionId,
+          value: x,
+          response: metadata,
+          request,
+          thrown: true
+        });
+      }
       headers.set("X-Server-Function-Error", "true");
       if (!instance) {
         if (options.handleNoJS) return options.handleNoJS(x, request, parsed, true);
@@ -531,12 +615,18 @@ async function handleServerFunctionRequest(request, options = {}) {
 }
 
 exports.FUNCTION_HEADER = FUNCTION_HEADER;
+exports.GET = GET;
 exports.INSTANCE_HEADER = INSTANCE_HEADER;
+exports.SINGLE_FLIGHT_HEADER = SINGLE_FLIGHT_HEADER;
 exports.configureServerFunctionsServer = configureServerFunctionsServer;
 exports.createServerReference = createServerReference;
 exports.decodeResponse = decodeResponse;
 exports.getServerFunction = getServerFunction;
 exports.getServerFunctionMeta = getServerFunctionMeta;
+exports.getServerFunctionMetadata = getServerFunctionMetadata;
 exports.handleServerFunctionRequest = handleServerFunctionRequest;
+exports.isServerFunction = isServerFunction;
 exports.registerServerFunction = registerServerFunction;
 exports.registerServerReference = registerServerReference;
+exports.subscribeFlightData = subscribeFlightData;
+exports.withMeta = withMeta;

package/server-functions/dist/server.js

@@ -65,9 +65,30 @@ function configureServerFunctionsCodec(codec) {
 function getServerFunctionsCodec() {
   return codecConfig.codec;
 }
+function subscribeFlightData(consumer) {
+  return () => {
+  };
+}
+const SERVER_FUNCTION_METADATA = Symbol.for("solid.ServerFunctionMetadata");
+function getServerFunctionMetadata(fn) {
+  if (typeof fn !== "function") return undefined;
+  return fn[SERVER_FUNCTION_METADATA] || undefined;
+}
+function isServerFunction(fn) {
+  return typeof fn === "function" && !!fn[SERVER_FUNCTION_METADATA];
+}
+function withMeta(fn, meta) {
+  const metadata = getServerFunctionMetadata(fn);
+  if (!metadata) {
+    throw new Error("withMeta expects a server function reference");
+  }
+  Object.assign(metadata, meta);
+  return fn;
+}
 const FUNCTION_HEADER = "X-Server-Function-Id";
 const INSTANCE_HEADER = "X-Server-Function-Instance";
 const BODY_FORMAT_HEADER = "X-Server-Function-Format";
+const SINGLE_FLIGHT_HEADER = "X-Single-Flight";
 const FILE_FORM_KEY = "__server_function_file__";
 const BodyFormat = {
   Serialized: "0",
@@ -280,14 +301,17 @@ async function decodeResponse(response, codecOptions) {
 
 const config = {
   provideEvent: undefined,
+  collectFlightData: undefined,
   endpoint: "/_server"
 };
 function configureServerFunctionsServer({
   provideEvent,
+  collectFlightData,
   endpoint,
   codec
 } = {}) {
   if (provideEvent !== undefined) config.provideEvent = provideEvent;
+  if (collectFlightData !== undefined) config.collectFlightData = collectFlightData;
   if (endpoint !== undefined) config.endpoint = endpoint;
   if (codec !== undefined) configureServerFunctionsCodec(codec);
 }
@@ -298,6 +322,7 @@ function provideEvent(event, fn) {
   throw new Error("No request event provider. Configure one with configureServerFunctionsServer({ provideEvent }).");
 }
 const REGISTRATIONS = new Map();
+const METHODS = new Map();
 function registerServerFunction(id, callback) {
   REGISTRATIONS.set(id, callback);
   return callback;
@@ -309,24 +334,30 @@ function getServerFunction(id) {
   }
   throw new Error("invalid server function: " + id);
 }
-function registerServerReference(id, fn) {
+function registerServerReference(id, fn, name) {
   registerServerFunction(id, fn);
   return {
     id,
-    fn
+    fn,
+    name
   };
 }
 function createServerReference({
   id,
-  fn
+  fn,
+  name
 }) {
   if (typeof fn !== "function") throw new Error("Export from a 'use server' module must be a function");
+  const metadata = name === undefined ? {} : {
+    name
+  };
   return new Proxy(fn, {
-    get(target, prop, receiver) {
+    get(target, prop) {
+      if (prop === "id") return id;
       if (prop === "url") {
         return `${config.endpoint}?id=${encodeURIComponent(id)}`;
       }
-      if (prop === "GET") return receiver;
+      if (prop === SERVER_FUNCTION_METADATA) return metadata;
       return target[prop];
     },
     apply(target, thisArg, args) {
@@ -345,6 +376,15 @@ function createServerReference({
     }
   });
 }
+function GET(fn) {
+  if (!isServerFunction(fn) || typeof fn.id !== "string") {
+    throw new Error("GET expects a server function reference");
+  }
+  METHODS.set(fn.id, "GET");
+  return withMeta(fn, {
+    method: "GET"
+  });
+}
 function getServerFunctionMeta() {
   const event = getRequestEvent();
   return event && event.locals.serverFunctionMeta;
@@ -377,6 +417,15 @@ async function parseArguments(request, url, instance, codec) {
   }
   return parsed;
 }
+async function foldFlightData(hook, event, headers, outcome) {
+  const data = await hook(event, outcome);
+  if (data === undefined) return outcome.value;
+  headers.set(SINGLE_FLIGHT_HEADER, "true");
+  return {
+    value: outcome.value,
+    data
+  };
+}
 function serializedResponse(value, headers, codec) {
   headers.set(BODY_FORMAT_HEADER, BodyFormat.Serialized);
   headers.set("Content-Type", "text/plain");
@@ -419,11 +468,22 @@ async function handleServerFunctionRequest(request, options = {}) {
       status: 404
     });
   }
+  const allowedMethod = METHODS.get(functionId) || "POST";
+  if (request.method === "GET" !== (allowedMethod === "GET")) {
+    return new Response(process.env.NODE_ENV === "development" ? `Method not allowed for server function: ${functionId}` : null, {
+      status: 405,
+      headers: {
+        Allow: allowedMethod
+      }
+    });
+  }
   const event = options.createEvent ? options.createEvent(request) : {
     request,
     locals: {}
   };
   const provide = options.provideEvent || provideEvent;
+  const flightHook = options.collectFlightData !== undefined ? options.collectFlightData : config.collectFlightData;
+  const collectsFlight = !!(flightHook && instance && request.headers.has(SINGLE_FLIGHT_HEADER));
   const parsed = await parseArguments(request, url, instance, codec);
   const headers = new Headers();
   try {
@@ -440,6 +500,7 @@ async function handleServerFunctionRequest(request, options = {}) {
       });
     }
     let status = 200;
+    let metadata;
     if (isResponseEnvelope(result)) {
       const {
         response,
@@ -454,6 +515,7 @@ async function handleServerFunctionRequest(request, options = {}) {
       if (response && response.status && (response.status < 300 || response.status >= 400)) {
         status = response.status;
       }
+      metadata = response;
       result = value;
     } else if (result instanceof Response) {
       if (result.headers && result.headers.has("X-Content-Raw")) return result;
@@ -464,11 +526,21 @@ async function handleServerFunctionRequest(request, options = {}) {
         if (result.status && (result.status < 300 || result.status >= 400)) {
           status = result.status;
         }
+        metadata = result;
         if (result.body == null) {
           result = null;
         }
       }
     }
+    if (collectsFlight) {
+      result = await foldFlightData(flightHook, event, headers, {
+        id: functionId,
+        value: result,
+        response: metadata,
+        request,
+        thrown: false
+      });
+    }
     if (!instance) {
       if (options.handleNoJS) return options.handleNoJS(result, request, parsed);
       if (result instanceof Response) return result;
@@ -485,6 +557,7 @@ async function handleServerFunctionRequest(request, options = {}) {
         });
       }
       let status = 200;
+      let metadata;
       if (isResponseEnvelope(x)) {
         const {
           response,
@@ -496,6 +569,7 @@ async function handleServerFunctionRequest(request, options = {}) {
         if (response && response.status && (!instance || response.status < 300 || response.status >= 400)) {
           status = response.status;
         }
+        metadata = response;
         x = value;
       } else if (x instanceof Response) {
         if (x.headers) {
@@ -504,10 +578,20 @@ async function handleServerFunctionRequest(request, options = {}) {
         if (x.status && (!instance || x.status < 300 || x.status >= 400)) {
           status = x.status;
         }
+        metadata = x;
         if (x.body == null) {
           x = null;
         }
       }
+      if (collectsFlight) {
+        x = await foldFlightData(flightHook, event, headers, {
+          id: functionId,
+          value: x,
+          response: metadata,
+          request,
+          thrown: true
+        });
+      }
       headers.set("X-Server-Function-Error", "true");
       if (!instance) {
         if (options.handleNoJS) return options.handleNoJS(x, request, parsed, true);
@@ -528,4 +612,4 @@ async function handleServerFunctionRequest(request, options = {}) {
   }
 }
 
-export { FUNCTION_HEADER, INSTANCE_HEADER, configureServerFunctionsServer, createServerReference, decodeResponse, getServerFunction, getServerFunctionMeta, handleServerFunctionRequest, registerServerFunction, registerServerReference };
+export { FUNCTION_HEADER, GET, INSTANCE_HEADER, SINGLE_FLIGHT_HEADER, configureServerFunctionsServer, createServerReference, decodeResponse, getServerFunction, getServerFunctionMeta, getServerFunctionMetadata, handleServerFunctionRequest, isServerFunction, registerServerFunction, registerServerReference, subscribeFlightData, withMeta };

package/types/server-functions/client.d.ts

@@ -1,6 +1,48 @@
 import { JSONCodecOptions } from "../serializer.js";
+import { ServerFunction, ServerFunctionMetadata } from "./shared.js";
 
-export { FUNCTION_HEADER, INSTANCE_HEADER, decodeResponse } from "./shared.js";
+export {
+  FUNCTION_HEADER,
+  INSTANCE_HEADER,
+  SINGLE_FLIGHT_HEADER,
+  decodeResponse,
+  getServerFunctionMetadata,
+  isServerFunction,
+  subscribeFlightData,
+  withMeta
+} from "./shared.js";
+export type {
+  FlightDataConsumer,
+  FlightDataContext,
+  ServerFunction,
+  ServerFunctionMetadata,
+  SingleFlightPayload
+} from "./shared.js";
+
+/** The context `prepareRequest` receives alongside the outgoing RequestInit. */
+export interface PrepareRequestContext {
+  /** The build-stable id of the function being called. */
+  id: string;
+  /**
+   * The reference's declaration metadata (e.g. `method: "GET"` for
+   * `GET(fn)` references). Plain references carry an empty object.
+   */
+  meta: ServerFunctionMetadata | undefined;
+}
+
+/**
+ * Client-side session-dynamic transport hook: runs before every
+ * server-function fetch. Return (or mutate and return) the RequestInit the
+ * transport will use — the hook sees the final init, transport headers
+ * included. The motivating case is dynamic credentials that rotate during
+ * a session and apply uniformly to every call (OAuth bearer tokens); it is
+ * the client-side symmetric of the server handler hooks. Single hook, not
+ * a chain — compose by wrapping functions in userland.
+ */
+export type PrepareRequestHook = (
+  init: RequestInit,
+  context: PrepareRequestContext
+) => RequestInit | Promise<RequestInit>;
 
 /** Options for `configureServerFunctionsClient`. */
 export interface ServerFunctionsClientConfig {
@@ -18,40 +60,72 @@ export interface ServerFunctionsClientConfig {
    * `decodeResponse` sees them too.
    */
   codec?: JSONCodecOptions;
+  /**
+   * Runs before every server-function fetch. Return (or mutate and return)
+   * the RequestInit the transport will use; `context.meta` is the
+   * reference's declaration metadata (e.g. method). For session-dynamic
+   * cross-cutting concerns — bearer tokens, tracing headers:
+   *
+   * ```ts
+   * configureServerFunctionsClient({
+   *   prepareRequest(init) {
+   *     return {
+   *       ...init,
+   *       headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
+   *     };
+   *   }
+   * });
+   * ```
+   */
+  prepareRequest?: PrepareRequestHook;
 }
 
 /**
  * Configures the client transport. Call once, before any server function is
  * invoked — typically in the client entry, next to `hydrate()`. Only needed
- * when deviating from the defaults (custom endpoint or codec plugins).
+ * when deviating from the defaults (custom endpoint, codec plugins, or a
+ * `prepareRequest` hook).
  */
 export function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
 
 /**
- * What a server function import is at runtime on the client: an async
- * callable that fetches the server, plus escape hatches for forms and
- * custom requests.
+ * Declares a server function callable over HTTP GET: calls to the returned
+ * reference go out as GET requests with the arguments codec-encoded in the
+ * query string — cacheable by HTTP infrastructure. Cache headers flow
+ * through the handler's header forwarding
+ * (`respond(data, { headers: { "cache-control": "max-age=60" } })`).
+ *
+ * The declaration rides the metadata channel
+ * (`getServerFunctionMetadata(fn)?.method === "GET"`) for routers and
+ * integrations to detect, and the server enforces it: GET-declared
+ * functions accept GET requests (and only GET), everything else answers
+ * 405. Server-side the wrapper is identity-flavored — SSR calls stay
+ * in-process.
+ *
+ * Wrap the reference at its declaration; the compiler round-trips the call
+ * in both builds:
+ *
+ * ```ts
+ * export const getUser = GET(async (id: string) => {
+ *   "use server";
+ *   return db.users.find(id);
+ * });
+ * ```
  */
-export interface ServerFunctionCallable {
-  (...args: any[]): Promise<any>;
-  /** URL invoking this function directly over HTTP (e.g. form `action`s). */
-  url: string;
-  /**
-   * Variant issuing GET requests with the arguments encoded in the query
-   * string — cacheable by HTTP infrastructure.
-   */
-  GET: ServerFunctionCallable;
-  /** Variant applying a custom RequestInit to every call (headers etc.). */
-  withOptions(options: RequestInit): ServerFunctionCallable;
-}
+export function GET<A extends readonly any[], R>(
+  fn: (...args: A) => R
+): ServerFunction<A, Awaited<R>>;
 
 /**
  * Compiler ABI — emitted by compiled `"use server"` client output where a
  * server function was referenced; produces the fetch-backed callable for
- * the function's build-stable id. Not meant for hand-written code.
+ * the function's build-stable id. Development builds pass the function's
+ * source name as the trailing argument (dev-only metadata seeded on the
+ * metadata channel; never emitted in production). Not meant for
+ * hand-written code.
  * @internal
  */
-export function createServerReference(id: string): ServerFunctionCallable;
+export function createServerReference(id: string, name?: string): ServerFunction;
 
 /**
  * Compiler ABI — only ever referenced by server-mode compiler output;