@solidjs/web 2.0.0-rc.1 → 2.0.0-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/dist/server.dev.js +4472 -0
  2. package/dist/server.js +1301 -251
  3. package/dist/{server.cjs → server.observe.js} +1501 -452
  4. package/dist/{dev.cjs → web.dev.js} +699 -360
  5. package/dist/web.js +454 -139
  6. package/dist/{dev.js → web.observe.js} +505 -211
  7. package/frames/dist/client.dev.js +463 -71
  8. package/frames/dist/client.js +363 -70
  9. package/frames/dist/{client.dev.cjs → client.observe.js} +486 -133
  10. package/frames/dist/server.dev.js +1713 -0
  11. package/frames/dist/server.js +552 -2583
  12. package/frames/dist/server.observe.js +1713 -0
  13. package/frames/package.json +2 -25
  14. package/package.json +214 -255
  15. package/performance-tracks/dist/performance-tracks.dev.js +678 -0
  16. package/performance-tracks/dist/performance-tracks.js +6 -0
  17. package/performance-tracks/dist/performance-tracks.observe.js +666 -0
  18. package/performance-tracks/package.json +7 -0
  19. package/performance-tracks/types/index.d.ts +67 -0
  20. package/serialization/decode/package.json +2 -15
  21. package/serialization/dist/decode.js +92 -15
  22. package/serialization/dist/serialization.js +103 -23
  23. package/serialization/package.json +2 -15
  24. package/serialization/types/index.d.ts +76 -157
  25. package/serialization/types/serializer-decode.d.ts +149 -112
  26. package/serialization/types/serializer.d.ts +101 -0
  27. package/server-functions/dist/client.dev.js +1364 -0
  28. package/server-functions/dist/client.js +611 -97
  29. package/server-functions/dist/client.observe.js +1343 -0
  30. package/server-functions/dist/server.dev.js +2138 -202
  31. package/server-functions/dist/server.js +2042 -199
  32. package/server-functions/dist/server.observe.js +3043 -0
  33. package/server-functions/package.json +2 -35
  34. package/server-functions/rich-args/package.json +2 -15
  35. package/storage/package.json +2 -15
  36. package/types/client.d.ts +193 -288
  37. package/types/constants.d.ts +20 -0
  38. package/types/cookies.d.ts +32 -84
  39. package/types/diagnostics.d.ts +56 -0
  40. package/types/frames/client.d.ts +1 -1
  41. package/types/frames/frame-client.d.ts +323 -259
  42. package/types/frames/frame-container-plugin.d.ts +72 -0
  43. package/types/frames/frame-sink.d.ts +101 -158
  44. package/types/frames/frame-transport.d.ts +192 -190
  45. package/types/frames/serializer-decode.d.ts +219 -0
  46. package/types/frames/serializer.d.ts +76 -157
  47. package/types/frames/server.d.ts +1 -1
  48. package/types/head.d.ts +19 -0
  49. package/types/index.d.ts +52 -80
  50. package/types/index.server.d.ts +174 -0
  51. package/types/jsx.d.ts +33 -35
  52. package/types/observe.d.ts +358 -0
  53. package/types/reconcile.d.ts +1 -0
  54. package/types/render.d.ts +9 -0
  55. package/types/response.d.ts +75 -150
  56. package/types/serializer-decode.d.ts +149 -112
  57. package/types/serializer.d.ts +76 -157
  58. package/types/server-functions/client.d.ts +192 -194
  59. package/types/server-functions/flash.d.ts +28 -30
  60. package/types/server-functions/registry.d.ts +102 -0
  61. package/types/server-functions/rich-args.d.ts +1 -10
  62. package/types/server-functions/server.d.ts +511 -475
  63. package/types/server-functions/shared.d.ts +366 -425
  64. package/types/server-mock.d.ts +110 -13
  65. package/types/server-observe.d.ts +77 -0
  66. package/types/server.d.ts +425 -425
  67. package/types/trace.d.ts +127 -0
  68. package/LICENSE +0 -21
  69. package/dist/web.cjs +0 -2008
  70. package/frames/dist/client.cjs +0 -1916
  71. package/frames/dist/server.cjs +0 -3756
  72. package/serialization/dist/decode.cjs +0 -122
  73. package/serialization/dist/serialization.cjs +0 -244
  74. package/serialization/types-cjs/index.d.cts +0 -182
  75. package/serialization/types-cjs/package.json +0 -3
  76. package/serialization/types-cjs/serializer-decode.d.cts +0 -182
  77. package/server-functions/dist/client.cjs +0 -793
  78. package/server-functions/dist/rich-args.cjs +0 -11
  79. package/server-functions/dist/server.cjs +0 -1171
  80. package/server-functions/dist/server.dev.cjs +0 -1171
  81. package/storage/dist/storage.cjs +0 -12
  82. package/storage/types-cjs/index.d.cts +0 -28
  83. package/storage/types-cjs/package.json +0 -3
  84. package/types/core.d.ts +0 -6
  85. package/types-cjs/client.d.cts +0 -337
  86. package/types-cjs/cookies.d.cts +0 -93
  87. package/types-cjs/core.d.cts +0 -6
  88. package/types-cjs/frames/client.d.cts +0 -36
  89. package/types-cjs/frames/frame-client.d.cts +0 -338
  90. package/types-cjs/frames/frame-sink.d.cts +0 -194
  91. package/types-cjs/frames/frame-transport.d.cts +0 -222
  92. package/types-cjs/frames/serializer.d.cts +0 -182
  93. package/types-cjs/frames/server.d.cts +0 -52
  94. package/types-cjs/index.d.cts +0 -244
  95. package/types-cjs/jsx-properties.d.cts +0 -93
  96. package/types-cjs/jsx.d.cts +0 -4159
  97. package/types-cjs/package.json +0 -3
  98. package/types-cjs/response.d.cts +0 -174
  99. package/types-cjs/serializer-decode.d.cts +0 -182
  100. package/types-cjs/serializer.d.cts +0 -182
  101. package/types-cjs/server-functions/client.d.cts +0 -231
  102. package/types-cjs/server-functions/flash.d.cts +0 -38
  103. package/types-cjs/server-functions/rich-args.d.cts +0 -10
  104. package/types-cjs/server-functions/server.d.cts +0 -616
  105. package/types-cjs/server-functions/shared.d.cts +0 -523
  106. package/types-cjs/server-mock.d.cts +0 -277
  107. package/types-cjs/server.d.cts +0 -523
@@ -1,35 +1,11 @@
1
+ export { ChunkReader, ERROR_HEADER, FLASH_COOKIE, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, createChunk, createEventChunk, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, encodeErrorHeaderValue, frameAddress, getServerFunctionMetadata, hasFlashCookie, invoke, isServerFunction, serializeStream, subscribeFlightData, textDigest, withMeta } from "./shared.js";
2
+ export { decodeFlashCookie, encodeFlashCookie } from "./flash.js";
1
3
  import { ResponseEnvelope } from "../response.js";
2
4
  import { JSONCodecOptions } from "../serializer-decode.js";
3
- import { RequestEvent } from "../server.js";
4
-
5
- export {
6
- ERROR_HEADER,
7
- FLASH_COOKIE,
8
- FUNCTION_HEADER,
9
- INSTANCE_HEADER,
10
- SINGLE_FLIGHT_HEADER,
11
- clearFlashCookie,
12
- decodeErrorHeaderValue,
13
- decodeResponse,
14
- decodeResponsePayload,
15
- encodeErrorHeaderValue,
16
- getServerFunctionMetadata,
17
- hasFlashCookie,
18
- isServerFunction,
19
- subscribeFlightData,
20
- withMeta
21
- } from "./shared.js";
22
- export type {
23
- FlightDataConsumer,
24
- FlightDataContext,
25
- ServerFunction,
26
- ServerFunctionMetadata,
27
- SingleFlightPayload
28
- } from "./shared.js";
29
- export { decodeFlashCookie, encodeFlashCookie } from "./flash.js";
5
+ import { RequestEvent, ServerErrorHook } from "../server.js";
6
+ import type { ServerFunction } from "./shared.js";
7
+ export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.js";
30
8
  export type { FlashSubmission } from "./flash.js";
31
- import { ServerFunction } from "./shared.js";
32
-
33
9
  /**
34
10
  * The request event a server function call runs under: the base
35
11
  * `RequestEvent` (request + locals) with `serverOnly` added, set when the
@@ -37,64 +13,64 @@ import { ServerFunction } from "./shared.js";
37
13
  * client.
38
14
  */
39
15
  export interface ServerFunctionEvent extends RequestEvent {
40
- serverOnly?: boolean;
16
+ serverOnly?: boolean;
41
17
  }
42
-
43
18
  /**
44
19
  * What a server function call resolved to, as seen by the single-flight
45
20
  * hook — enough context for any data-production strategy without core
46
21
  * assuming one.
47
22
  */
48
23
  export interface ServerFunctionOutcome {
49
- /** The build-stable id of the function that ran. */
50
- id: string;
51
- /**
52
- * The value the caller will receive: the raw return for plain results,
53
- * the unwrapped `value` for `ResponseEnvelope`s, `null` for body-less
54
- * control-flow `Response`s (redirect/reload).
55
- */
56
- value: unknown;
57
- /**
58
- * The `Response` carrying the result's HTTP metadata, when there is one
59
- * (from a returned/thrown `Response` or a `ResponseEnvelope`). Read
60
- * `Location` here for redirect-with-data — the data should describe the
61
- * destination route — and `X-Revalidate` for the invalidated keys.
62
- * Undefined for plain values.
63
- */
64
- response: Response | undefined;
65
- /**
66
- * The original HTTP request, untouched: headers the client integration
67
- * sent (referrer, custom route context) ride here for the hook to read —
68
- * core assigns them no meaning.
69
- */
70
- request: Request;
71
- /** Whether the result was thrown rather than returned. */
72
- thrown: boolean;
73
- /**
74
- * The URL the client will show after the mutation — the redirect
75
- * `Location` when the outcome carries one (resolved against the request
76
- * URL, as a browser would), the referring page otherwise. Undefined
77
- * without a usable referer (a non-browser caller has no page to produce
78
- * data for) and for redirects leaving the app's origin: produce no data
79
- * when this is undefined.
80
- */
81
- targetUrl: string | undefined;
82
- /**
83
- * The outcome's `X-Revalidate` keys, split — the invalidation scope the
84
- * mutation declared. Undefined when the outcome carries none (integrations
85
- * typically collect everything for the target in that case).
86
- */
87
- revalidateKeys: string[] | undefined;
88
- /**
89
- * The request headers with the mutation's cookie effects applied: the
90
- * event response's `Set-Cookie`s (set during the call), then the
91
- * outcome's own (e.g. `redirect(to, { headers })`), later winning on
92
- * conflict, deletions honored. Build the data-collection request from
93
- * these so re-run reads observe post-mutation cookie state.
94
- */
95
- foldedHeaders: Headers;
24
+ /** The build-stable id of the function that ran. */
25
+ id: string;
26
+ /**
27
+ * The value the caller will receive: the raw return for plain results,
28
+ * the unwrapped `value` for `ResponseEnvelope`s, `null` for body-less
29
+ * control-flow `Response`s (redirect/reload).
30
+ */
31
+ value: unknown;
32
+ /**
33
+ * The `Response` carrying the result's HTTP metadata, when there is one
34
+ * (from a returned/thrown `Response` or a `ResponseEnvelope`). Read
35
+ * `Location` here for redirect-with-data — the data should describe the
36
+ * destination route — and `X-Revalidate` for the invalidated keys.
37
+ * Undefined for plain values.
38
+ */
39
+ response: Response | undefined;
40
+ /**
41
+ * The original HTTP request, untouched: headers the client integration
42
+ * sent (referrer, custom route context) ride here for the hook to read —
43
+ * core assigns them no meaning.
44
+ */
45
+ request: Request;
46
+ /** Whether the result was thrown rather than returned. */
47
+ thrown: boolean;
48
+ /**
49
+ * The URL the client will show after the mutation — the redirect
50
+ * `Location` when the outcome carries one (resolved against the request
51
+ * URL, as a browser would), the referring page otherwise. Undefined
52
+ * without a usable referer (a non-browser caller has no page to produce
53
+ * data for) and for redirects leaving the app's origin: produce no data
54
+ * when this is undefined.
55
+ */
56
+ targetUrl: string | undefined;
57
+ /**
58
+ * The outcome's `X-Revalidate` keys, split — the invalidation scope the
59
+ * mutation declared. Undefined when the outcome carries none (integrations
60
+ * typically collect everything for the target in that case); `[""]` for
61
+ * an empty declaration (nothing); `["*"]` for `REVALIDATE_ALL`, delivered
62
+ * as declared so a collector can tell "everything" from named keys.
63
+ */
64
+ revalidateKeys: string[] | undefined;
65
+ /**
66
+ * The request headers with the mutation's cookie effects applied: the
67
+ * event response's `Set-Cookie`s (set during the call), then the
68
+ * outcome's own (e.g. `redirect(to, { headers })`), later winning on
69
+ * conflict, deletions honored. Build the data-collection request from
70
+ * these so re-run reads observe post-mutation cookie state.
71
+ */
72
+ foldedHeaders: Headers;
96
73
  }
97
-
98
74
  /**
99
75
  * The single-flight server hook: given the request event and the function's
100
76
  * outcome, optionally produce a data payload (possibly async) to fold into
@@ -114,11 +90,7 @@ export interface ServerFunctionOutcome {
114
90
  * pre-digested on the outcome (`targetUrl`, `revalidateKeys`,
115
91
  * `foldedHeaders`); the hook supplies only the data strategy.
116
92
  */
117
- export type CollectFlightDataHook = (
118
- event: ServerFunctionEvent,
119
- outcome: ServerFunctionOutcome
120
- ) => unknown | Promise<unknown>;
121
-
93
+ export type CollectFlightDataHook = (event: ServerFunctionEvent, outcome: ServerFunctionOutcome) => unknown | Promise<unknown>;
122
94
  /**
123
95
  * Wraps a server function execution — the per-invocation seam for
124
96
  * framework policies (per-function middleware, auth, logging, error
@@ -135,174 +107,247 @@ export type CollectFlightDataHook = (
135
107
  * return `run()`'s value, not an unconditional promise, unless it needs to
136
108
  * be async.
137
109
  */
138
- export type WrapInvocationHook = (
139
- run: () => unknown,
140
- context: {
110
+ export type WrapInvocationHook = (run: () => unknown, context: {
141
111
  id: string;
142
112
  args: unknown[];
143
113
  event: ServerFunctionEvent;
144
114
  request?: Request;
145
115
  direct: boolean;
146
- }
147
- ) => unknown;
148
-
149
- /**
150
- * Request headers with `setCookies` folded into the `Cookie` header, as the
151
- * browser would have applied them before its next request. Later entries
152
- * win on conflict, and deletions are honored (`Max-Age` at or below zero,
153
- * `Expires` in the past). The input headers are not modified.
154
- *
155
- * For work re-run on the server after a mutation — a
156
- * `CollectFlightDataHook` gathering fresh data, typically. That pass starts
157
- * from the request that triggered the mutation, whose cookies are
158
- * pre-mutation by definition, so a read depending on a session the mutation
159
- * just established would otherwise see the old state. Which responses
160
- * contribute their `Set-Cookie`s, and in what order, is the caller's
161
- * decision.
162
- *
163
- * @example
164
- * ```ts
165
- * const headers = foldSetCookies(event.request.headers, [
166
- * ...(event.response?.headers?.getSetCookie() ?? []),
167
- * ...(outcome.response?.headers?.getSetCookie() ?? [])
168
- * ]);
169
- * ```
170
- */
171
- export function foldSetCookies(headers: Headers, setCookies: readonly string[]): Headers;
172
-
116
+ }) => unknown;
173
117
  /** Options for `createNoJSHandler`. */
174
118
  export interface NoJSHandlerOptions {
175
- /** The app's mount path, for resolving a relative redirect `Location`. */
176
- base?: string;
119
+ /** The app's mount path, for resolving a relative redirect `Location`. */
120
+ base?: string;
121
+ }
122
+ export type ServerFunctionOriginMatcher = string | readonly string[] | ((origin: string, request: Request) => boolean | Promise<boolean>);
123
+ /** Same-origin validation options for server function requests. */
124
+ export interface ServerFunctionCSRFOptions {
125
+ /**
126
+ * The origins allowed to call server functions: a single origin, a list,
127
+ * or a matcher `(origin, request) => boolean` (async allowed; anything
128
+ * but a literal `true` refuses, #3169) for multi-tenant hosts. Defaults
129
+ * to the incoming request URL's origin, which admits same-origin callers
130
+ * only.
131
+ *
132
+ * Listing an origin OTHER than the deployment's own is the opt-in for a
133
+ * cross-origin client — a static build in a WebView
134
+ * (`capacitor://localhost`), an embedded widget, a marketing site calling
135
+ * the app's API — whose `configureServerFunctionsClient({ endpoint })`
136
+ * names this handler's absolute URL. A `Sec-Fetch-Site: cross-site` (or
137
+ * `same-site`) request carrying a browser-set `Origin` is decided by this
138
+ * matcher, and an admitted cross-origin caller gets the CORS answer the
139
+ * browser needs to read the response: `Access-Control-Allow-Origin`
140
+ * echoing its exact `Origin` (with `Vary: Origin`), the protocol's
141
+ * response headers exposed, and the `OPTIONS` preflight answered for the
142
+ * transport's methods and headers. Without a configured matcher no
143
+ * cross-origin caller is admitted (#3538); `Sec-Fetch-Site: none` and a
144
+ * request carrying no `Origin` at all stay refused whatever is listed.
145
+ * Configuring a matcher also puts `Vary: Origin` on every `GET`-declared
146
+ * read (the one cacheable answer): its answer now depends on who asked,
147
+ * and a shared cache must not serve one caller's variant to another.
148
+ *
149
+ * The trust decision is the same one this option always claimed: a
150
+ * browser sets `Origin` and a page cannot forge it, so a listed origin's
151
+ * pages may call — with the user's cookies only if `allowCredentials`
152
+ * says so. A cross-origin client should prefer bearer tokens through the
153
+ * client's `prepareRequest`.
154
+ */
155
+ origin?: ServerFunctionOriginMatcher;
156
+ /**
157
+ * Sends `Access-Control-Allow-Credentials: true` to an admitted
158
+ * cross-origin caller, letting a `credentials: "include"` fetch carry
159
+ * and receive cookies. Off by default so that listing an origin never
160
+ * silently turns on cookie sharing; a cookie that is meant to travel
161
+ * cross-site also needs `SameSite=None; Secure`. Has no effect on
162
+ * same-origin responses.
163
+ * @default false
164
+ */
165
+ allowCredentials?: boolean;
166
+ /**
167
+ * Allows requests without `Sec-Fetch-Site`, `Origin`, or `Referer`.
168
+ * Cross-origin metadata is still decided by `origin`: an unlisted origin
169
+ * stays refused.
170
+ * @default false
171
+ */
172
+ allowRequestsWithoutOriginCheck?: boolean;
173
+ /**
174
+ * Applies the origin gate to GET-declared reads as well. By default the
175
+ * gate is skipped for declared reads: same-origin policy already keeps a
176
+ * cross-site caller from READING the response, and the gate's `Vary`
177
+ * fragments (or, on CDNs that ignore Vary, poisons) the shared-cache
178
+ * entries the `GET` helper exists to enable (#3071). The premise that
179
+ * skip rests on is `GET()`'s safety contract — declared reads are safe
180
+ * to EXECUTE from any origin (#3114). A deployment that does not rely
181
+ * on shared caches can enable this to gate its reads too.
182
+ * @default false
183
+ */
184
+ protectDeclaredReads?: boolean;
177
185
  }
178
-
179
- /**
180
- * Builds the `handleNoJS` implementation for the no-JS form convention: a
181
- * form posted without the client runtime has no way to receive a value, so
182
- * the call redirects back to the referring page (or to the result's own
183
- * `Location`, resolved against `base`) with the outcome riding a one-shot
184
- * flash cookie. `303 See Other` turns the POST into a GET unless the result
185
- * names a redirect status of its own. A result that is already a `Response`
186
- * carries its meaning in its metadata and is not flashed.
187
- *
188
- * The render that follows reads the cookie with `decodeFlashCookie` and
189
- * surfaces the outcome however it likes — that half is the integration's.
190
- *
191
- * The handler applies to every call it receives. `handleServerFunctionRequest`
192
- * already uses it for browser form posts, so wire it explicitly only to set
193
- * a `base`, or to extend the convention to direct HTTP calls by registering
194
- * it through `configureServerFunctionsServer`.
195
- */
196
- export function createNoJSHandler(
197
- options?: NoJSHandlerOptions
198
- ): (result: unknown, request: Request, args: unknown[], thrown?: boolean) => Response;
199
-
200
186
  /** Options for `configureServerFunctionsServer`. */
201
187
  export interface ServerFunctionsServerConfig {
202
- /**
203
- * Establishes the request-event scope for a call — the function passed
204
- * runs with `event` visible to `getRequestEvent()`. Wire it to
205
- * `provideRequestEvent` from `@solidjs/web/storage` (or the framework's
206
- * equivalent). When omitted, falls back to the AsyncLocalStorage instance
207
- * an established request scope parks on the global.
208
- */
209
- provideEvent?: <T>(event: ServerFunctionEvent, fn: () => T) => T;
210
- /**
211
- * Wraps every server function execution — HTTP dispatch and direct SSR
212
- * calls alike — with the invocation identity already established (see
213
- * `WrapInvocationHook`). The per-invocation seam for framework policies:
214
- * per-function middleware, auth, logging, error mapping. A per-request
215
- * option overrides it for HTTP dispatch.
216
- */
217
- wrapInvocation?: WrapInvocationHook;
218
- /**
219
- * The single-flight hook: produces the data payload folded into
220
- * responses of calls that opted in (see `CollectFlightDataHook`).
221
- * Registered once by the integration that owns data production (a
222
- * router); per-handler `collectFlightData` options override it.
223
- */
224
- collectFlightData?: CollectFlightDataHook;
225
- /**
226
- * Server-wide default for the handler's `transformResult` (same contract
227
- * — see `HandleServerFunctionRequestOptions`); a per-request option
228
- * overrides it. Registering it here makes result policies (e.g. frames'
229
- * `frameTransformResult`) work through generic dispatchers that call
230
- * `handleServerFunctionRequest(request)` with no options.
231
- */
232
- transformResult?(
233
- event: ServerFunctionEvent,
234
- result: unknown,
235
- context: {
236
- id: string;
237
- args: unknown[];
238
- instance: string | null;
239
- request: Request;
240
- thrown?: boolean;
241
- }
242
- ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
243
- /**
244
- * `transformResult`'s counterpart for the single-flight fold: when a
245
- * call's flight payload needs a body only a policy knows how to build
246
- * (frames' `frameTransformFlightResult` — an invalidated entry is
247
- * markup), this gets first refusal on the `{ value, data }` outcome.
248
- * Return a `Response` to carry the outcome (call headers and cookies are
249
- * copied onto it), or `undefined` to decline and keep the plain
250
- * serialized envelope. A per-request option overrides it.
251
- */
252
- transformFlightResult?(
253
- event: ServerFunctionEvent,
254
- outcome: { value: unknown; data: unknown },
255
- context: { id: string; args: unknown[]; instance: string | null; request: Request }
256
- ): Response | undefined | Promise<Response | undefined>;
257
- /**
258
- * The in-process mirror of `transformResult` for direct (same-server)
259
- * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
260
- */
261
- transformDirectResult?(
262
- value: unknown,
263
- options: { id: string; args: unknown[]; event: ServerFunctionEvent }
264
- ): unknown;
265
- /**
266
- * Server-wide response builder for calls made without the client runtime
267
- * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
268
- * per-request option overrides it. Set it to `createNoJSHandler({ base })`
269
- * to apply the convention to every non-scripted call rather than only to
270
- * browser form posts, to a handler of your own to replace it, or to
271
- * `null` to disable the built-in convention and answer form posts with
272
- * the plain serialized response.
273
- */
274
- handleNoJS?:
275
- | ((
276
- result: unknown,
277
- request: Request,
278
- args: unknown[],
279
- thrown?: boolean
280
- ) => Response | Promise<Response>)
281
- | null;
282
- /**
283
- * Endpoint the HTTP handler is mounted on, used for the `url` of SSR'd
284
- * references (e.g. form actions) — must match the client configuration.
285
- * Prefix it when the app serves from a base path (e.g.
286
- * `` `${BASE_URL}_server` ``).
287
- * @default "/_server"
288
- */
289
- endpoint?: string;
290
- /**
291
- * Codec options (extra plugins etc.) for decoding arguments and encoding
292
- * results — must match the client's. Stored in the shared layer, so
293
- * `decodeResponse` sees them too.
294
- */
295
- codec?: JSONCodecOptions;
188
+ /**
189
+ * Establishes the request-event scope for a call — the function passed
190
+ * runs with `event` visible to `getRequestEvent()`. Wire it to
191
+ * `provideRequestEvent` from `@solidjs/web/storage` (or the framework's
192
+ * equivalent). When omitted, falls back to the AsyncLocalStorage instance
193
+ * an established request scope parks on the global.
194
+ */
195
+ provideEvent?: <T>(event: ServerFunctionEvent, fn: () => T) => T;
196
+ /**
197
+ * Wraps every server function execution — HTTP dispatch and direct SSR
198
+ * calls alike — with the invocation identity already established (see
199
+ * `WrapInvocationHook`). The per-invocation seam for framework policies:
200
+ * per-function middleware, auth, logging, error mapping. A per-request
201
+ * option overrides it for HTTP dispatch.
202
+ */
203
+ wrapInvocation?: WrapInvocationHook;
204
+ /**
205
+ * The unnamed single-flight hook: produces the data payload folded into
206
+ * responses of calls that opted in (see `CollectFlightDataHook`).
207
+ * Registered once by the integration that owns data production (a
208
+ * router); per-handler `collectFlightData` options override it. Other
209
+ * integrations contribute additively through
210
+ * `registerFlightDataSource(id, hook)` instead of competing for this
211
+ * slot.
212
+ */
213
+ collectFlightData?: CollectFlightDataHook;
214
+ /**
215
+ * Server-wide default for the handler's `transformResult` (same contract
216
+ * — see `HandleServerFunctionRequestOptions`); a per-request option
217
+ * overrides it. Registering it here makes result policies (e.g. frames'
218
+ * `frameTransformResult`) work through generic dispatchers that call
219
+ * `handleServerFunctionRequest(request)` with no options.
220
+ */
221
+ transformResult?(event: ServerFunctionEvent, result: unknown, context: {
222
+ id: string;
223
+ args: unknown[];
224
+ request: Request;
225
+ thrown?: boolean;
226
+ }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
227
+ /**
228
+ * `transformResult`'s counterpart for the single-flight fold: when a
229
+ * call's flight payload needs a body only a policy knows how to build
230
+ * (frames' `frameTransformFlightResult` — an invalidated entry is
231
+ * markup), this gets first refusal on the `{ value, data }` outcome.
232
+ * Return a `Response` to carry the outcome (call headers and cookies are
233
+ * copied onto it), or `undefined` to decline and keep the plain
234
+ * serialized envelope. A per-request option overrides it.
235
+ */
236
+ transformFlightResult?(event: ServerFunctionEvent, outcome: {
237
+ value: unknown;
238
+ data: unknown;
239
+ }, context: {
240
+ id: string;
241
+ args: unknown[];
242
+ request: Request;
243
+ }): Response | undefined | Promise<Response | undefined>;
244
+ /**
245
+ * The in-process mirror of `transformResult` for direct (same-server)
246
+ * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
247
+ */
248
+ transformDirectResult?(value: unknown, options: {
249
+ id: string;
250
+ args: unknown[];
251
+ event: ServerFunctionEvent;
252
+ }): unknown;
253
+ /**
254
+ * Server-wide response builder for calls made without the client runtime
255
+ * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
256
+ * per-request option overrides it. Set it to `createNoJSHandler({ base })`
257
+ * to apply the convention to every non-scripted call rather than only to
258
+ * browser form posts, to a handler of your own to replace it, or to
259
+ * `null` to disable the built-in convention and answer form posts with
260
+ * the plain serialized response.
261
+ */
262
+ handleNoJS?: ((result: unknown, request: Request, args: unknown[], thrown?: boolean) => Response | Promise<Response>) | null;
263
+ /**
264
+ * Mount path the HTTP handler answers on. Must match the client
265
+ * configuration — the id travels as the segment after it, a request whose
266
+ * path does not start with it is not a call, and SSR'd reference `url`s
267
+ * (e.g. form actions) derive from it. Prefix it when the app serves from
268
+ * a base path (e.g. `` `${BASE_URL}_server` ``).
269
+ * @default "/_server"
270
+ */
271
+ endpoint?: string;
272
+ /**
273
+ * Same-origin protection for HTTP server function calls. Enabled by
274
+ * default. Set to `false` only when another trusted layer protects the
275
+ * endpoint. `{ origin }` lists the origins allowed to call — the opt-in
276
+ * for a cross-origin client, answered with CORS (see
277
+ * `ServerFunctionCSRFOptions`).
278
+ */
279
+ csrf?: boolean | ServerFunctionCSRFOptions;
280
+ /**
281
+ * Codec options (extra plugins etc.) for decoding arguments and encoding
282
+ * results — must match the client's. Stored in the shared layer, so
283
+ * `decodeResponse` sees them too. When `serializeErrorStacks` is omitted,
284
+ * the server-function boundary defaults it from this module's compiled
285
+ * development variant.
286
+ */
287
+ codec?: JSONCodecOptions;
288
+ /**
289
+ * Upper bound, in bytes, on a call's argument payload — the POST body,
290
+ * or the `?args=` query encoding. The payload is buffered and decoded
291
+ * before dispatch, so its cost is paid before application code can
292
+ * decline it; the bound is enforced up front and a request over it is
293
+ * refused with `413` before any decoding (#3115). Raise it for functions
294
+ * that accept large uploads, or set `Infinity` to remove the bound.
295
+ * @default 1_048_576 (1 MiB)
296
+ */
297
+ bodySizeLimit?: number;
298
+ /**
299
+ * Upper bound on the number of arguments a call may carry. The decoded
300
+ * argument array is spread into the function call, so an unbounded list
301
+ * forces a range error out of any function regardless of what it does;
302
+ * past the bound the request is refused with `400` (#3115).
303
+ * @default 1000
304
+ */
305
+ maxArguments?: number;
306
+ /**
307
+ * The DEPLOYMENT SECRET: one value per deployment, from which any feature
308
+ * that needs a key derives its own (domain-separated, so per-purpose keys
309
+ * share no material). Today one feature does — the no-JS flash cookie
310
+ * (#3239): the flash carries the submitted form input — whatever the user
311
+ * typed — so its payload is always AES-GCM encrypted; it never rides the
312
+ * wire or rests in the cookie jar as plaintext. Every instance that can
313
+ * serve the render after a form post must share the secret (behind a load
314
+ * balancer, a per-instance secret would silently lose outcomes), so there
315
+ * is no generated fallback here: when this is not set, the secret falls
316
+ * back to the one the Solid bundler plugin injects into the server build
317
+ * (a fresh value per build), and with neither present the outcome is
318
+ * simply not flashed — the form post still redirects cleanly, and dev
319
+ * builds warn once.
320
+ *
321
+ * Use a HIGH-ENTROPY value, 32 bytes or more, and keep it out of source
322
+ * control:
323
+ *
324
+ * ```sh
325
+ * node -e "console.log(crypto.randomBytes(32).toString('base64url'))"
326
+ * ```
327
+ *
328
+ * A captured cookie is an offline oracle for this value. Key derivation
329
+ * stretches it (PBKDF2-HMAC-SHA-256), which raises the price of a guess
330
+ * but does not make a guessable secret safe, and recovering it means
331
+ * reading every flash payload and forging new ones. A passphrase, an app
332
+ * name, or anything else a person would think up is not enough.
333
+ *
334
+ * Rotating it (or redeploying with the plugin's value) invalidates
335
+ * in-flight flashes. They are 60-second one-shot cookies, so the next
336
+ * render reads "no flash".
337
+ */
338
+ secret?: string;
339
+ /**
340
+ * DEV ONLY — the chaos knob: end every live response this many
341
+ * milliseconds after it opens, the way a dying connection ends it (the
342
+ * body breaks off with the stream still open). The client's `live` loop
343
+ * reads it as a death and reconnects — backoff, `Last-Event-ID`, the
344
+ * digest-equal skip, `onstatus` — so the reconnect path is exercised
345
+ * continuously without a network to break. Applies to every event-stream
346
+ * response the live address answers, data and frames alike. Ignored
347
+ * outside the dev build; `0`/`undefined` is off.
348
+ */
349
+ chaosReconnectEvery?: number;
296
350
  }
297
-
298
- /**
299
- * Configures the server runtime. Call once at server startup, before
300
- * handling requests. Only needed when deviating from the defaults (custom
301
- * endpoint, codec plugins, an explicit event provider, or a single-flight
302
- * hook).
303
- */
304
- export function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
305
-
306
351
  /**
307
352
  * A registered server function: its build-stable id paired with the
308
353
  * original implementation. Returned by `registerServerReference` and
@@ -312,89 +357,19 @@ export function configureServerFunctionsServer(config?: ServerFunctionsServerCon
312
357
  * @internal
313
358
  */
314
359
  export interface ServerFunctionReference<T extends any[] = any[], R = any> {
315
- id: string;
316
- fn: (...args: T) => R;
317
- /**
318
- * The function's source name, emitted by development builds only —
319
- * `createServerReference` seeds the metadata channel with it.
320
- * @internal
321
- */
322
- name?: string;
360
+ id: string;
361
+ fn: (...args: T) => R;
362
+ /**
363
+ * The function's source name, emitted by development builds only —
364
+ * `createServerReference` seeds the metadata channel with it.
365
+ * @internal
366
+ */
367
+ name?: string;
323
368
  }
324
-
325
- /**
326
- * Adds a function to the dispatch registry under an id and returns it
327
- * unchanged. The low-level registry write for integrations registering
328
- * functions outside the compiler (e.g. a router registering its own
329
- * endpoints); compiled output goes through `registerServerReference`
330
- * instead. Ids must be stable across the client and server builds.
331
- */
332
- export function registerServerFunction<T extends any[], R>(
333
- id: string,
334
- callback: (...args: T) => R
335
- ): (...args: T) => R;
336
-
337
- /**
338
- * Looks up a registered server function by id; throws for unknown ids.
339
- * The HTTP handler uses this for dispatch — integrations building custom
340
- * dispatch (or introspection) can too.
341
- */
342
- export function getServerFunction<T extends any[], R>(id: string): (...args: T) => R;
343
-
344
- /**
345
- * Compiler ABI — emitted by compiled `"use server"` server output for
346
- * every server function: registers `fn` for HTTP dispatch under its
347
- * build-stable id and returns the reference the server-side
348
- * `createServerReference` consumes. Development builds pass the function's
349
- * source name as the trailing argument (dev-only metadata; never emitted in
350
- * production). Not meant for hand-written code.
351
- * @internal
352
- */
353
- export function registerServerReference<T extends any[], R>(
354
- id: string,
355
- fn: (...args: T) => R,
356
- name?: string
357
- ): ServerFunctionReference<T, R>;
358
-
359
- /**
360
- * Compiler ABI — emitted by compiled `"use server"` server output where
361
- * the function was referenced; produces the server-side callable. Calling
362
- * it during SSR runs the original function in-process (no HTTP), under a
363
- * request event derived from the current one — marked `serverOnly` and
364
- * carrying the function's meta. Not meant for hand-written code.
365
- * @internal
366
- */
367
- export function createServerReference<T extends any[], R>(
368
- reference: ServerFunctionReference<T, R>
369
- ): (...args: T) => R;
370
-
371
- /**
372
- * Declares a server function callable over HTTP GET. The server half is
373
- * identity-flavored — SSR calls stay in-process — but it brands the
374
- * declaration on the reference's metadata channel
375
- * (`getServerFunctionMetadata(fn)?.method === "GET"`) and records the
376
- * declared method for the function's id so `handleServerFunctionRequest`
377
- * honors it: GET-declared functions accept GET requests in addition to the
378
- * default POST transport (declaring GET grants, it does not revoke);
379
- * functions that never declared GET answer GET requests with 405.
380
- *
381
- * Wrap the reference at its declaration; the compiler round-trips the call
382
- * in both builds:
383
- *
384
- * ```ts
385
- * export const getUser = GET(async (id: string) => {
386
- * "use server";
387
- * return db.users.find(id);
388
- * });
389
- * ```
390
- */
391
- export function GET<A extends readonly any[], R>(
392
- fn: (...args: A) => R
393
- ): ServerFunction<A, Awaited<R>>;
394
-
395
- /** Wire-state transitions a live call's iterable can report (client side). */
369
+ /** Wire-state transitions a live call's iterable can report (client side).
370
+ * `"closed"` carries the error when a definite rejection (4xx) ended the
371
+ * call instead of the retry loop. */
396
372
  export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
397
-
398
373
  /**
399
374
  * Type-level mirror of the client's live answer shape so isomorphic code
400
375
  * assigning `onstatus` typechecks against either build's declarations. On
@@ -402,146 +377,231 @@ export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
402
377
  * own iterable — there is no connection to report on.
403
378
  */
404
379
  export type LiveSource<R> = R & {
405
- onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
380
+ onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
406
381
  };
407
-
408
- /**
409
- * Declares a value-shaped live source: a server function returning an async
410
- * iterable whose yields are successive VALUES of one logical query, with
411
- * the contract that the source re-yields current state on every invocation.
412
- * Writes `live: true` on the metadata channel and brands the resolved
413
- * iterable (registered symbol `solid.LiveSource`) so SSR faces meeting the
414
- * value in-process can apply live policy (document face: first value, then
415
- * client takeover). Dispatch is untouched — over-the-wire calls stream the
416
- * raw registered function's result. Declare live outermost:
417
- * `live(GET(fn))`.
418
- */
419
- export function live<A extends readonly any[], R>(
420
- fn: (...args: A) => R
421
- ): ServerFunction<A, LiveSource<Awaited<R>>>;
422
-
423
382
  /** Identity of the currently executing server function call. */
424
383
  export interface ServerFunctionInvocation {
425
- id: string;
384
+ id: string;
385
+ /**
386
+ * The call arrived at the live address: a `live` loop is reading, and the
387
+ * answer is framed as an event stream for as long as it stands (RFC 10,
388
+ * `live(fn)` → Framing). A result policy building the answer's Response
389
+ * itself (`frameTransformResult`) reads this to frame it the same way.
390
+ * `false` for the data and bare addresses, and for in-process calls.
391
+ */
392
+ live: boolean;
426
393
  }
427
-
428
- /**
429
- * Reads the in-flight server function invocation (its id) for the current
430
- * request event — usable inside a server function body, e.g. to key caches
431
- * or logs by function. Returns undefined outside a server function call.
432
- * The state lives in a module-private WeakMap keyed by the per-call request
433
- * event (never in `event.locals`, which derived events share with their
434
- * outer event). Distinct from `getServerFunctionMetadata(fn)`, which reads
435
- * a reference's static declaration metadata; this describes the call
436
- * currently executing.
437
- */
438
- export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
439
-
440
- /**
441
- * The event-keyed half of `getServerFunctionInvocation`, for callers handed
442
- * an event outside its provideEvent scope (the handler's result transforms
443
- * run after the scope has exited). Integration plumbing — application code
444
- * reads the ambient accessor instead.
445
- * @internal
446
- */
447
- export function getEventServerFunctionInvocation(
448
- event: RequestEvent | undefined
449
- ): ServerFunctionInvocation | undefined;
450
-
451
394
  /**
452
395
  * Hooks layering framework policy onto `handleServerFunctionRequest`.
453
396
  * All are optional — the bare handler dispatches, scopes events, and
454
397
  * encodes results on its own.
455
398
  */
456
399
  export interface HandleServerFunctionOptions {
457
- /**
458
- * Builds the request event a call runs under (default: bare
459
- * `{ request, locals: {} }`). Integrations supply their richer event
460
- * (cookies, response helpers, platform handles).
461
- */
462
- createEvent?(request: Request): ServerFunctionEvent;
463
- /**
464
- * Overrides the configured event provider for this handler — same
465
- * contract as the `provideEvent` config option.
466
- */
467
- provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
468
- /**
469
- * Overrides the configured per-invocation wrap for this handler — same
470
- * contract as the `wrapInvocation` config option (see
471
- * `WrapInvocationHook`), except it only applies to HTTP dispatch (a
472
- * per-request option can't see direct SSR calls).
473
- */
474
- wrapInvocation?: WrapInvocationHook;
475
- /**
476
- * Observes or replaces the function's result before encoding — the
477
- * extension point for response metadata policies (headers, statuses,
478
- * substituted results). Runs for returned and thrown results alike
479
- * (`context.thrown` distinguishes); `context.instance` is null for no-JS
480
- * calls. The context carries the call's identity — the function `id` and
481
- * the parsed `args` the implementation was invoked with — matching the
482
- * direct-call mirror (`transformDirectResult`), so a policy keying state
483
- * by the call works over either dispatch path. Return the result
484
- * unchanged to pass through, or a `ResponseEnvelope` (exposed through
485
- * the core entry) to send HTTP metadata plus a structured payload. Runs
486
- * before `collectFlightData`, so the flight hook sees the transformed
487
- * outcome — use `collectFlightData`, not this, to fold data into the
488
- * response.
489
- */
490
- transformResult?(
491
- event: ServerFunctionEvent,
492
- result: unknown,
493
- context: {
494
- id: string;
495
- args: unknown[];
496
- instance: string | null;
497
- request: Request;
498
- thrown?: boolean;
499
- }
500
- ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
501
- /**
502
- * Overrides the configured single-flight hook for this handler — same
503
- * contract as the `collectFlightData` config option (see
504
- * `CollectFlightDataHook`).
505
- */
506
- collectFlightData?: CollectFlightDataHook;
507
- /**
508
- * Overrides the configured single-flight fold policy for this handler —
509
- * same contract as the `transformFlightResult` config option.
510
- */
511
- transformFlightResult?(
512
- event: ServerFunctionEvent,
513
- outcome: { value: unknown; data: unknown },
514
- context: { id: string; args: unknown[]; instance: string | null; request: Request }
515
- ): Response | undefined | Promise<Response | undefined>;
516
- /**
517
- * Builds the response for calls made without the client runtime (no
518
- * instance header — no-JS form posts, direct HTTP). Receives the
519
- * (transformed) result, the request, and the decoded arguments; `thrown`
520
- * is set when the result was thrown rather than returned.
521
- *
522
- * Overrides the configured hook, which in turn overrides the built-in
523
- * `createNoJSHandler()` applied to browser form posts. Other
524
- * no-instance callers get the normal serialized response.
525
- */
526
- handleNoJS?(
527
- result: unknown,
528
- request: Request,
529
- args: unknown[],
530
- thrown?: boolean
531
- ): Response | Promise<Response>;
532
- /** Overrides the configured codec options for this handler. */
533
- codec?: JSONCodecOptions;
400
+ /**
401
+ * Builds the request event a call runs under (default: bare
402
+ * `{ request, locals: {} }`). Integrations supply their richer event
403
+ * (cookies, response helpers, platform handles).
404
+ *
405
+ * `request` is a standards-shaped `Request` — url, method, headers,
406
+ * signal, readable body — and nothing more. Enforcing `bodySizeLimit`
407
+ * puts the runtime between the host's stream and the decoder, so the
408
+ * object handed here may be one the runtime rebuilt; host-specific
409
+ * fields on the inbound object (`request.cf`, srvx's `runtime`, `ip`,
410
+ * `waitUntil`) are not carried. The host has its own request in closure
411
+ * when it calls the handler: read platform handles there and put them on
412
+ * the event (`locals`) rather than through `request`.
413
+ */
414
+ createEvent?(request: Request): ServerFunctionEvent;
415
+ /**
416
+ * Overrides the configured event provider for this handler — same
417
+ * contract as the `provideEvent` config option.
418
+ */
419
+ provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
420
+ /**
421
+ * Overrides the configured per-invocation wrap for this handler — same
422
+ * contract as the `wrapInvocation` config option (see
423
+ * `WrapInvocationHook`), except it is ENTRY-ONLY: it wraps exactly the
424
+ * invocation the request addressed. Nested direct server-function calls
425
+ * made by the dispatched body are not re-wrapped by it — they consult
426
+ * only the configured hook, which is ambient and wraps every direct call
427
+ * (a per-request option can't see direct SSR calls). Policy that must
428
+ * cover every hop belongs on `configureServerFunctionsServer`'s
429
+ * `wrapInvocation`, not here.
430
+ */
431
+ wrapInvocation?: WrapInvocationHook;
432
+ /**
433
+ * This request's server error hook, ahead of `configureServerErrors`' (see
434
+ * `ServerErrorHook` in `@solidjs/web`): the function's throw
435
+ * (`handling: "thrown"`) and a failure escaping through its result graph
436
+ * (`"channel"`), once per error, before the wire policy applies. Entry-only
437
+ * like `wrapInvocation`: a direct call the body makes during a render
438
+ * reports through the ambient hook.
439
+ */
440
+ onError?: ServerErrorHook;
441
+ /**
442
+ * Observes or replaces the function's result before encoding — the
443
+ * extension point for response metadata policies (headers, statuses,
444
+ * substituted results). Runs for returned and thrown results alike
445
+ * (`context.thrown` distinguishes). The context carries the call's
446
+ * identity — the function `id` and the parsed `args` the implementation
447
+ * was invoked with — matching the direct-call mirror
448
+ * (`transformDirectResult`), so a policy keying state by the call works
449
+ * over either dispatch path; `context.request` tells a scripted call (the
450
+ * `/data/` address) from a bare-address one. Return the result
451
+ * unchanged to pass through, or a `ResponseEnvelope` (exposed through
452
+ * the core entry) to send HTTP metadata plus a structured payload. Runs
453
+ * before `collectFlightData`, so the flight hook sees the transformed
454
+ * outcome — use `collectFlightData`, not this, to fold data into the
455
+ * response.
456
+ */
457
+ transformResult?(event: ServerFunctionEvent, result: unknown, context: {
458
+ id: string;
459
+ args: unknown[];
460
+ request: Request;
461
+ thrown?: boolean;
462
+ }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
463
+ /**
464
+ * Overrides the configured single-flight hook for this handler — same
465
+ * contract as the `collectFlightData` config option (see
466
+ * `CollectFlightDataHook`).
467
+ */
468
+ collectFlightData?: CollectFlightDataHook;
469
+ /**
470
+ * Overrides the configured single-flight fold policy for this handler —
471
+ * same contract as the `transformFlightResult` config option.
472
+ */
473
+ transformFlightResult?(event: ServerFunctionEvent, outcome: {
474
+ value: unknown;
475
+ data: unknown;
476
+ }, context: {
477
+ id: string;
478
+ args: unknown[];
479
+ request: Request;
480
+ }): Response | undefined | Promise<Response | undefined>;
481
+ /**
482
+ * Builds the response for calls made without the client runtime (at
483
+ * the bare address — no-JS form posts, direct HTTP). Receives the
484
+ * (transformed) result, the request, and the decoded arguments; `thrown`
485
+ * is set when the result was thrown rather than returned.
486
+ *
487
+ * Overrides the configured hook, which in turn overrides the built-in
488
+ * `createNoJSHandler()` applied to browser form posts. Other
489
+ * bare-address callers get the normal serialized response.
490
+ */
491
+ handleNoJS?(result: unknown, request: Request, args: unknown[], thrown?: boolean): Response | Promise<Response>;
492
+ /**
493
+ * Overrides same-origin protection for this handler. Set to `false` only
494
+ * when another trusted layer protects the endpoint.
495
+ */
496
+ csrf?: boolean | ServerFunctionCSRFOptions;
497
+ /** Overrides the configured codec options for this handler. */
498
+ codec?: JSONCodecOptions;
499
+ /**
500
+ * Overrides the configured argument payload bound for this handler (see
501
+ * `ServerFunctionsServerConfig.bodySizeLimit`).
502
+ */
503
+ bodySizeLimit?: number;
504
+ /**
505
+ * Overrides the configured argument count bound for this handler (see
506
+ * `ServerFunctionsServerConfig.maxArguments`).
507
+ */
508
+ maxArguments?: number;
534
509
  }
535
-
510
+ export declare function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
511
+ export declare function registerFlightDataSource(source: string, hook: CollectFlightDataHook): () => void;
512
+ export declare function registerServerFunction<T extends any[], R>(id: string, callback: (...args: T) => R): (...args: T) => R;
513
+ export declare function getServerFunction<T extends any[], R>(id: string): (...args: T) => R;
514
+ export declare function registerServerReference<T extends any[], R>(id: string, fn: (...args: T) => R, name?: string): ServerFunctionReference<T, R>;
515
+ export declare function createServerReference<T extends any[], R>(reference: ServerFunctionReference<T, R>): (...args: T) => R;
516
+ export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
517
+ export declare function live<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, LiveSource<Awaited<R>>>;
518
+ export declare function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
519
+ export declare function getEventServerFunctionInvocation(event: RequestEvent | undefined): ServerFunctionInvocation | undefined;
520
+ export declare function foldSetCookies(headers: Headers, setCookies: readonly string[]): Headers;
521
+ export declare function createNoJSHandler(options?: NoJSHandlerOptions): (result: unknown, request: Request, args: unknown[], thrown?: boolean) => Promise<Response>;
522
+ /** @internal */
523
+ export declare function guardFailures(value: any, state: any): any;
524
+ /**
525
+ * The response-side codec stream: `serializeStream` (shared.js) hardened
526
+ * with request-lifetime teardown. Server-only on purpose — the shared half
527
+ * is re-exported into client bundles, where this plumbing is dead weight.
528
+ *
529
+ * An abort of `signal` (the platform fires request.signal when the caller's
530
+ * fetch aborts or the tab goes away) or the consumer cancelling the
531
+ * ReadableStream (how platforms surface a dropped connection to the body)
532
+ * stops pending serialization and tears down EVERY async-iterable or
533
+ * ReadableStream source in the result graph, nested ones included (#3125) —
534
+ * each producer's `iterator.return()` / `reader.cancel()` runs, so
535
+ * generator `finally` blocks execute instead of the server pumping streams
536
+ * nobody is reading. The wiring rides guardFailures' walk: it already wraps
537
+ * every channel before the codec sees the value, so the demand gate and the
538
+ * teardown registry are threaded through its state (`{ items: rows() }` —
539
+ * a cursor beside a total — gets the same two guarantees as `return rows()`).
540
+ *
541
+ * `live` selects the event-stream framing a live address answers in (see
542
+ * encodeLiveResult): the same payloads one per event, a comment heartbeat
543
+ * while idle, and each yield's position — parked on `live.pending` by the
544
+ * live adapter — riding as the `id:` of the record that carries the yield.
545
+ */
546
+ export declare function serializeResponseStream(value: any, codecOptions: any, signal: any, scope: any, live: any): ReadableStream<any>;
547
+ /**
548
+ * Arms what every live body carries beyond its payloads, whichever writer
549
+ * frames them — the codec stream (`serializeResponseStream`) and a frame
550
+ * stream (`serverComponentResponse` at the live address) alike:
551
+ *
552
+ * - the heartbeat: an event-stream comment every 20s while the response is
553
+ * open, so a proxy's idle timeout never mistakes a waiting source for a
554
+ * dead one. Not demand-gated — the two bytes ride ahead of any parked
555
+ * pull. Unref'd where the runtime allows: the connection holds the
556
+ * process open, not the timer;
557
+ * - the chaos knob (dev only, `chaosReconnectEvery`): end this response as
558
+ * a dying connection would — `teardown` first (the producer's own), then
559
+ * the body errors with the stream still open, so the client reads a
560
+ * death, not a completion.
561
+ *
562
+ * Returns the disarm; the caller runs it on every road the body ends by, so
563
+ * a response that completed on its own is never touched.
564
+ * @internal
565
+ */
566
+ export declare function armLiveBody(controller: ReadableStreamDefaultController<Uint8Array>, teardown: () => void): () => void;
567
+ /** Message a sanitized (production) server error carries on the wire. */
568
+ export declare const GENERIC_SERVER_ERROR_MESSAGE = "Internal Server Error";
569
+ export declare function setServerFunctionsDev(dev: boolean): void;
570
+ export declare function sanitizeServerError(value: unknown): unknown;
571
+ export declare function serverFunctionUrl<A extends readonly unknown[]>(fn: ServerFunction<A, any>, ...args: A): string;
572
+ export declare function serverFunctionActionUrl(fn: ServerFunction | string, ...boundArgs: readonly unknown[]): string;
573
+ export declare function parseServerFunctionActionUrl(url: string): string | null;
536
574
  /**
537
575
  * Web-standard HTTP handler for server function calls: resolves the
538
- * function id from the request, gates GET dispatch on the declaration (405
539
- * for a GET request to a function that never declared `GET`; POST is always
540
- * accepted), decodes arguments, runs the function under a request-event scope,
541
- * and encodes the result (forwarding redirect/revalidation metadata
542
- * through headers). Mount it on the endpoint the client transport targets
543
- * (default `/_server`); platform adapters (h3, express, ...) convert their
544
- * request shape to a web `Request` around it.
576
+ * function id from the request, enforces the method allowlist (POST always
577
+ * dispatches; GET and HEAD dispatch only to functions that declared `GET`,
578
+ * with HEAD returning the equivalent GET's status and headers minus the
579
+ * body; every other method answers 405), decodes arguments, runs the
580
+ * function under a request-event scope, and encodes the result (forwarding
581
+ * redirect/revalidation metadata through headers). Mount it on the endpoint
582
+ * the client transport targets (default `/_server`); platform adapters (h3,
583
+ * express, ...) convert their request shape to a web `Request` around it.
584
+ *
585
+ * Requests are same-origin by default. The handler accepts browser requests
586
+ * proven by `Sec-Fetch-Site`, `Origin`, or `Referer`, and rejects requests
587
+ * without usable metadata unless explicitly configured otherwise. A
588
+ * cross-origin browser call is admitted only when `csrf.origin` lists its
589
+ * `Origin`, and is then answered with CORS — `Access-Control-Allow-Origin`
590
+ * echoing that origin, the protocol's headers exposed, the `OPTIONS`
591
+ * preflight answered, credentials only when `csrf.allowCredentials` says so
592
+ * (#3538). GET/HEAD requests to `GET`-declared functions skip this gate:
593
+ * they are reads by contract, cross-site response READING is already
594
+ * blocked by same-origin policy, and skipping it keeps the
595
+ * `Vary: Sec-Fetch-Site, Origin, Referer` it would impose off the responses
596
+ * shared caches are meant to store. Once `csrf.origin` lists an origin,
597
+ * though, a read's answer depends on who asked — `Allow-Origin` for a
598
+ * listed caller, nothing for anyone else — so every declared read then
599
+ * carries `Vary: Origin` (and only that), or a shared cache would serve one
600
+ * caller's variant to the other.
601
+ *
602
+ * Every response leaves with `Cache-Control: no-store` unless the function
603
+ * set its own cache policy (via `respond()` headers or a returned
604
+ * `Response`) — caching is opt-in on the wire, not just in prose.
545
605
  *
546
606
  * When the event carries a `response` head stub (`event.response`, see the
547
607
  * server entry's `ResponseStub`), the handler folds it onto every outgoing
@@ -580,7 +640,7 @@ export interface HandleServerFunctionOptions {
580
640
  *
581
641
  * @example
582
642
  * ```ts
583
- * import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
643
+ * import { handleServerFunctionRequest } from "@solidjs/web/server-functions/server";
584
644
  * import "virtual:solid-server-function-manifest";
585
645
  *
586
646
  * // in the server's request handling:
@@ -589,28 +649,4 @@ export interface HandleServerFunctionOptions {
589
649
  * }
590
650
  * ```
591
651
  */
592
- export function handleServerFunctionRequest(
593
- request: Request,
594
- options?: HandleServerFunctionOptions
595
- ): Promise<Response>;
596
-
597
- /** Message a sanitized (production) server error carries on the wire. */
598
- export const GENERIC_SERVER_ERROR_MESSAGE: string;
599
-
600
- /**
601
- * The production error-sanitization policy `handleServerFunctionRequest`
602
- * applies to a plain thrown value before serialization. Returns `value`
603
- * unchanged in the dev build or when it is branded safe (`markSafeError`);
604
- * otherwise returns a generic `Error` carrying `GENERIC_SERVER_ERROR_MESSAGE`.
605
- * Exposed for frameworks composing their own dispatch around the same policy.
606
- */
607
- export function sanitizeServerError(value: unknown): unknown;
608
-
609
- /**
610
- * Overrides the build-variant dev flag for this module instance — the seam
611
- * for test harnesses and hand-rolled bundles whose packaging cannot replace
612
- * `_DX_DEV_`. Applications never call this; select the dev build through
613
- * the `development` export condition instead.
614
- * @internal
615
- */
616
- export function setServerFunctionsDev(dev: boolean): void;
652
+ export declare function handleServerFunctionRequest(request: Request, options?: HandleServerFunctionOptions): Promise<Response>;