@solidjs/web 2.0.0-rc.2 → 2.0.0-rc.20

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 (124) hide show
  1. package/README.md +1 -1
  2. package/dist/server.dev.js +5065 -0
  3. package/dist/server.js +1757 -355
  4. package/dist/{server.cjs → server.observe.js} +1951 -558
  5. package/dist/{dev.cjs → web.dev.js} +945 -550
  6. package/dist/web.js +635 -332
  7. package/dist/{dev.js → web.observe.js} +688 -403
  8. package/frames/dist/assets.js +92 -0
  9. package/frames/dist/client.dev.js +1296 -1198
  10. package/frames/dist/client.js +1128 -1191
  11. package/frames/dist/client.observe.js +2041 -0
  12. package/frames/dist/regions.js +171 -0
  13. package/frames/dist/server.dev.js +2549 -0
  14. package/frames/dist/server.js +1688 -3005
  15. package/frames/dist/server.observe.js +2548 -0
  16. package/frames/dist/trace.js +45 -0
  17. package/frames/dist/wire.js +594 -0
  18. package/frames/package.json +2 -25
  19. package/package.json +244 -256
  20. package/performance-tracks/dist/performance-tracks.dev.js +679 -0
  21. package/performance-tracks/dist/performance-tracks.js +6 -0
  22. package/performance-tracks/dist/performance-tracks.observe.js +667 -0
  23. package/performance-tracks/package.json +7 -0
  24. package/performance-tracks/types/index.d.ts +69 -0
  25. package/serialization/decode/package.json +2 -15
  26. package/serialization/dist/decode.js +121 -25
  27. package/serialization/dist/serialization.js +242 -88
  28. package/serialization/package.json +2 -15
  29. package/serialization/types/index.d.ts +85 -158
  30. package/serialization/types/serializer-decode.d.ts +173 -114
  31. package/serialization/types/serializer.d.ts +109 -0
  32. package/server-functions/dist/client.dev.js +1462 -0
  33. package/server-functions/dist/client.js +667 -165
  34. package/server-functions/dist/client.observe.js +1441 -0
  35. package/server-functions/dist/rich-args.js +84 -1
  36. package/server-functions/dist/server.dev.js +2714 -297
  37. package/server-functions/dist/server.js +2595 -271
  38. package/server-functions/dist/server.observe.js +3594 -0
  39. package/server-functions/package.json +2 -35
  40. package/server-functions/rich-args/package.json +2 -15
  41. package/skills/server-components/SKILL.md +117 -0
  42. package/storage/package.json +2 -15
  43. package/types/client.d.ts +342 -288
  44. package/types/constants.d.ts +22 -0
  45. package/types/cookies.d.ts +32 -84
  46. package/types/diagnostics.d.ts +80 -0
  47. package/types/frames/assets-tier.d.ts +78 -0
  48. package/types/frames/client.d.ts +40 -1
  49. package/types/frames/frame-client.d.ts +443 -280
  50. package/types/frames/frame-container-plugin.d.ts +64 -0
  51. package/types/frames/frame-morph.d.ts +29 -0
  52. package/types/frames/frame-sink.d.ts +141 -161
  53. package/types/frames/frame-transport.d.ts +263 -184
  54. package/types/frames/regions-tier.d.ts +60 -0
  55. package/types/frames/serializer-decode.d.ts +241 -0
  56. package/types/frames/serializer.d.ts +85 -158
  57. package/types/frames/server.d.ts +2 -2
  58. package/types/frames/trace-tier.d.ts +2 -0
  59. package/types/frames/tree-rewrite.d.ts +39 -0
  60. package/types/frames/wire-tier.d.ts +169 -0
  61. package/types/head.d.ts +20 -0
  62. package/types/index.d.ts +98 -81
  63. package/types/index.server.d.ts +159 -0
  64. package/types/jsx.d.ts +49 -44
  65. package/types/observe.d.ts +535 -0
  66. package/types/reconcile.d.ts +1 -0
  67. package/types/render.d.ts +11 -0
  68. package/types/request-error-hook.d.ts +5 -0
  69. package/types/response.d.ts +95 -147
  70. package/types/serializer-decode.d.ts +173 -114
  71. package/types/serializer.d.ts +85 -158
  72. package/types/server-functions/argument-codec.d.ts +30 -0
  73. package/types/server-functions/client.d.ts +238 -223
  74. package/types/server-functions/flash.d.ts +28 -30
  75. package/types/server-functions/registry.d.ts +105 -0
  76. package/types/server-functions/rich-args.d.ts +1 -10
  77. package/types/server-functions/server.d.ts +539 -531
  78. package/types/server-functions/shared.d.ts +398 -425
  79. package/types/server-functions/uploads.d.ts +50 -0
  80. package/types/server-mock.d.ts +120 -13
  81. package/types/server-observe.d.ts +86 -0
  82. package/types/server.d.ts +571 -422
  83. package/types/trace.d.ts +127 -0
  84. package/LICENSE +0 -21
  85. package/dist/web.cjs +0 -2033
  86. package/frames/dist/client.cjs +0 -2002
  87. package/frames/dist/client.dev.cjs +0 -2022
  88. package/frames/dist/server.cjs +0 -3877
  89. package/serialization/dist/decode.cjs +0 -139
  90. package/serialization/dist/serialization.cjs +0 -261
  91. package/serialization/types-cjs/index.d.cts +0 -182
  92. package/serialization/types-cjs/package.json +0 -3
  93. package/serialization/types-cjs/serializer-decode.d.cts +0 -182
  94. package/server-functions/dist/client.cjs +0 -834
  95. package/server-functions/dist/rich-args.cjs +0 -11
  96. package/server-functions/dist/server.cjs +0 -1242
  97. package/server-functions/dist/server.dev.cjs +0 -1242
  98. package/storage/dist/storage.cjs +0 -12
  99. package/storage/types-cjs/index.d.cts +0 -28
  100. package/storage/types-cjs/package.json +0 -3
  101. package/types/core.d.ts +0 -9
  102. package/types-cjs/client.d.cts +0 -337
  103. package/types-cjs/cookies.d.cts +0 -93
  104. package/types-cjs/core.d.cts +0 -9
  105. package/types-cjs/frames/client.d.cts +0 -36
  106. package/types-cjs/frames/frame-client.d.cts +0 -356
  107. package/types-cjs/frames/frame-sink.d.cts +0 -194
  108. package/types-cjs/frames/frame-transport.d.cts +0 -222
  109. package/types-cjs/frames/serializer.d.cts +0 -182
  110. package/types-cjs/frames/server.d.cts +0 -52
  111. package/types-cjs/index.d.cts +0 -244
  112. package/types-cjs/jsx-properties.d.cts +0 -93
  113. package/types-cjs/jsx.d.cts +0 -4159
  114. package/types-cjs/package.json +0 -3
  115. package/types-cjs/response.d.cts +0 -174
  116. package/types-cjs/serializer-decode.d.cts +0 -182
  117. package/types-cjs/serializer.d.cts +0 -182
  118. package/types-cjs/server-functions/client.d.cts +0 -262
  119. package/types-cjs/server-functions/flash.d.cts +0 -38
  120. package/types-cjs/server-functions/rich-args.d.cts +0 -10
  121. package/types-cjs/server-functions/server.d.cts +0 -681
  122. package/types-cjs/server-functions/shared.d.cts +0 -523
  123. package/types-cjs/server-mock.d.cts +0 -286
  124. package/types-cjs/server.d.cts +0 -544
@@ -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, ServerFunctionMetadata } 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, ServerFunctionMetadata } 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,200 +107,263 @@ 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;
177
121
  }
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
- export type ServerFunctionOriginMatcher =
201
- | string
202
- | readonly string[]
203
- | ((origin: string, request: Request) => boolean | Promise<boolean>);
204
-
122
+ export type ServerFunctionOriginMatcher = string | readonly string[] | ((origin: string, request: Request) => boolean | Promise<boolean>);
205
123
  /** Same-origin validation options for server function requests. */
206
124
  export interface ServerFunctionCSRFOptions {
207
- /**
208
- * Expected public origin. Defaults to the incoming request URL's origin.
209
- * A function can validate origins dynamically for multi-tenant hosts.
210
- */
211
- origin?: ServerFunctionOriginMatcher;
212
- /**
213
- * Allows requests without `Sec-Fetch-Site`, `Origin`, or `Referer`.
214
- * Cross-origin metadata is still rejected.
215
- * @default false
216
- */
217
- allowRequestsWithoutOriginCheck?: boolean;
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;
218
185
  }
219
-
220
186
  /** Options for `configureServerFunctionsServer`. */
221
187
  export interface ServerFunctionsServerConfig {
222
- /**
223
- * Establishes the request-event scope for a call — the function passed
224
- * runs with `event` visible to `getRequestEvent()`. Wire it to
225
- * `provideRequestEvent` from `@solidjs/web/storage` (or the framework's
226
- * equivalent). When omitted, falls back to the AsyncLocalStorage instance
227
- * an established request scope parks on the global.
228
- */
229
- provideEvent?: <T>(event: ServerFunctionEvent, fn: () => T) => T;
230
- /**
231
- * Wraps every server function execution — HTTP dispatch and direct SSR
232
- * calls alike — with the invocation identity already established (see
233
- * `WrapInvocationHook`). The per-invocation seam for framework policies:
234
- * per-function middleware, auth, logging, error mapping. A per-request
235
- * option overrides it for HTTP dispatch.
236
- */
237
- wrapInvocation?: WrapInvocationHook;
238
- /**
239
- * The single-flight hook: produces the data payload folded into
240
- * responses of calls that opted in (see `CollectFlightDataHook`).
241
- * Registered once by the integration that owns data production (a
242
- * router); per-handler `collectFlightData` options override it.
243
- */
244
- collectFlightData?: CollectFlightDataHook;
245
- /**
246
- * Server-wide default for the handler's `transformResult` (same contract
247
- * — see `HandleServerFunctionRequestOptions`); a per-request option
248
- * overrides it. Registering it here makes result policies (e.g. frames'
249
- * `frameTransformResult`) work through generic dispatchers that call
250
- * `handleServerFunctionRequest(request)` with no options.
251
- */
252
- transformResult?(
253
- event: ServerFunctionEvent,
254
- result: unknown,
255
- context: {
256
- id: string;
257
- args: unknown[];
258
- instance: string | null;
259
- request: Request;
260
- thrown?: boolean;
261
- }
262
- ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
263
- /**
264
- * `transformResult`'s counterpart for the single-flight fold: when a
265
- * call's flight payload needs a body only a policy knows how to build
266
- * (frames' `frameTransformFlightResult` — an invalidated entry is
267
- * markup), this gets first refusal on the `{ value, data }` outcome.
268
- * Return a `Response` to carry the outcome (call headers and cookies are
269
- * copied onto it), or `undefined` to decline and keep the plain
270
- * serialized envelope. A per-request option overrides it.
271
- */
272
- transformFlightResult?(
273
- event: ServerFunctionEvent,
274
- outcome: { value: unknown; data: unknown },
275
- context: { id: string; args: unknown[]; instance: string | null; request: Request }
276
- ): Response | undefined | Promise<Response | undefined>;
277
- /**
278
- * The in-process mirror of `transformResult` for direct (same-server)
279
- * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
280
- */
281
- transformDirectResult?(
282
- value: unknown,
283
- options: { id: string; args: unknown[]; event: ServerFunctionEvent }
284
- ): unknown;
285
- /**
286
- * Server-wide response builder for calls made without the client runtime
287
- * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
288
- * per-request option overrides it. Set it to `createNoJSHandler({ base })`
289
- * to apply the convention to every non-scripted call rather than only to
290
- * browser form posts, to a handler of your own to replace it, or to
291
- * `null` to disable the built-in convention and answer form posts with
292
- * the plain serialized response.
293
- */
294
- handleNoJS?:
295
- | ((
296
- result: unknown,
297
- request: Request,
298
- args: unknown[],
299
- thrown?: boolean
300
- ) => Response | Promise<Response>)
301
- | null;
302
- /**
303
- * Endpoint the HTTP handler is mounted on, used for the `url` of SSR'd
304
- * references (e.g. form actions) — must match the client configuration.
305
- * Prefix it when the app serves from a base path (e.g.
306
- * `` `${BASE_URL}_server` ``).
307
- * @default "/_server"
308
- */
309
- endpoint?: string;
310
- /**
311
- * Same-origin protection for HTTP server function calls. Enabled by
312
- * default. Set to `false` only when another trusted layer protects the
313
- * endpoint.
314
- */
315
- csrf?: boolean | ServerFunctionCSRFOptions;
316
- /**
317
- * Codec options (extra plugins etc.) for decoding arguments and encoding
318
- * results — must match the client's. Stored in the shared layer, so
319
- * `decodeResponse` sees them too.
320
- */
321
- 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. One asymmetry is fixed: arguments are
284
+ * client input and never decode `Response` or `Request` values, whatever
285
+ * plugins are configured — a call carrying one is refused with `400`.
286
+ * Results keep the full set. Every plugin added here is a type a client
287
+ * can make the server construct. When `serializeErrorStacks` is omitted,
288
+ * the server-function boundary defaults it from this module's compiled
289
+ * development variant.
290
+ */
291
+ codec?: JSONCodecOptions;
292
+ /**
293
+ * Upper bound, in bytes, on a call's argument payload — the POST body,
294
+ * or the `?args=` query encoding. The payload is buffered and decoded
295
+ * before dispatch, so its cost is paid before application code can
296
+ * decline it; the bound is enforced up front and a request over it is
297
+ * refused with `413` before any decoding (#3115). Raise it for functions
298
+ * that accept large uploads, or set `Infinity` to remove the bound.
299
+ * @default 1_048_576 (1 MiB)
300
+ */
301
+ bodySizeLimit?: number;
302
+ /**
303
+ * Upper bound on the number of arguments a call may carry. The decoded
304
+ * argument array is spread into the function call, so an unbounded list
305
+ * forces a range error out of any function regardless of what it does;
306
+ * past the bound the request is refused with `400` (#3115).
307
+ * @default 1000
308
+ */
309
+ maxArguments?: number;
310
+ /**
311
+ * The DEPLOYMENT SECRET: one value per deployment, from which any feature
312
+ * that needs a key derives its own (domain-separated, so per-purpose keys
313
+ * share no material). Today one feature does — the no-JS flash cookie
314
+ * (#3239): the flash carries the submitted form input — whatever the user
315
+ * typed — so its payload is always AES-GCM encrypted; it never rides the
316
+ * wire or rests in the cookie jar as plaintext. Every instance that can
317
+ * serve the render after a form post must share the secret (behind a load
318
+ * balancer, a per-instance secret would silently lose outcomes), so there
319
+ * is no generated fallback here: when this is not set, the secret falls
320
+ * back to the one the Solid bundler plugin injects into the server build
321
+ * (a fresh value per build), and with neither present the outcome is
322
+ * simply not flashed — the form post still redirects cleanly, and dev
323
+ * builds warn once.
324
+ *
325
+ * Use a HIGH-ENTROPY value, 32 bytes or more, and keep it out of source
326
+ * control:
327
+ *
328
+ * ```sh
329
+ * node -e "console.log(crypto.randomBytes(32).toString('base64url'))"
330
+ * ```
331
+ *
332
+ * A captured cookie is an offline oracle for this value. Key derivation
333
+ * stretches it (PBKDF2-HMAC-SHA-256), which raises the price of a guess
334
+ * but does not make a guessable secret safe, and recovering it means
335
+ * reading every flash payload and forging new ones. A passphrase, an app
336
+ * name, or anything else a person would think up is not enough.
337
+ *
338
+ * Rotating it (or redeploying with the plugin's value) invalidates
339
+ * in-flight flashes. They are 60-second one-shot cookies, so the next
340
+ * render reads "no flash".
341
+ */
342
+ secret?: string;
343
+ /**
344
+ * DEV ONLY — the chaos knob: end every live response this many
345
+ * milliseconds after it opens, the way a dying connection ends it (the
346
+ * body breaks off with the stream still open). The client's `live` loop
347
+ * reads it as a death and reconnects — backoff, `Last-Event-ID`, the
348
+ * digest-equal skip, `onstatus` — so the reconnect path is exercised
349
+ * continuously without a network to break. Applies to every event-stream
350
+ * response the live address answers, data and frames alike. Ignored
351
+ * outside the dev build; `0`/`undefined` is off.
352
+ */
353
+ chaosReconnectEvery?: number;
354
+ /**
355
+ * Id of the build this server was bundled with. A call whose
356
+ * `X-Server-Function-Build` header names another build is answered `409`
357
+ * and the function does not run: the page was loaded from a build whose
358
+ * functions may take other arguments or return another shape. The answer
359
+ * carries the unknown-function label, so the client rejects with
360
+ * `unknownFunction: true`, the same as for an id this build does not
361
+ * have. The client runtime does not send the header itself: the build
362
+ * integration adds it through `prepareRequest`. Calls without the header
363
+ * are not checked. Leave unset to check nothing.
364
+ */
365
+ buildId?: string;
322
366
  }
323
-
324
- /**
325
- * Configures the server runtime. Call once at server startup, before
326
- * handling requests. Only needed when deviating from the defaults (custom
327
- * endpoint, codec plugins, an explicit event provider, or a single-flight
328
- * hook).
329
- */
330
- export function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
331
-
332
367
  /**
333
368
  * A registered server function: its build-stable id paired with the
334
369
  * original implementation. Returned by `registerServerReference` and
@@ -338,91 +373,19 @@ export function configureServerFunctionsServer(config?: ServerFunctionsServerCon
338
373
  * @internal
339
374
  */
340
375
  export interface ServerFunctionReference<T extends any[] = any[], R = any> {
341
- id: string;
342
- fn: (...args: T) => R;
343
- /**
344
- * The function's source name, emitted by development builds only —
345
- * `createServerReference` seeds the metadata channel with it.
346
- * @internal
347
- */
348
- name?: string;
376
+ id: string;
377
+ fn: (...args: T) => R;
378
+ /**
379
+ * The function's source name, emitted by development builds only —
380
+ * `createServerReference` seeds the metadata channel with it.
381
+ * @internal
382
+ */
383
+ name?: string;
349
384
  }
350
-
351
- /**
352
- * Adds a function to the dispatch registry under an id and returns it
353
- * unchanged. The low-level registry write for integrations registering
354
- * functions outside the compiler (e.g. a router registering its own
355
- * endpoints); compiled output goes through `registerServerReference`
356
- * instead. Ids must be stable across the client and server builds.
357
- */
358
- export function registerServerFunction<T extends any[], R>(
359
- id: string,
360
- callback: (...args: T) => R
361
- ): (...args: T) => R;
362
-
363
- /**
364
- * Looks up a registered server function by id; throws for unknown ids.
365
- * The HTTP handler uses this for dispatch — integrations building custom
366
- * dispatch (or introspection) can too.
367
- */
368
- export function getServerFunction<T extends any[], R>(id: string): (...args: T) => R;
369
-
370
- /**
371
- * Compiler ABI — emitted by compiled `"use server"` server output for
372
- * every server function: registers `fn` for HTTP dispatch under its
373
- * build-stable id and returns the reference the server-side
374
- * `createServerReference` consumes. Development builds pass the function's
375
- * source name as the trailing argument (dev-only metadata; never emitted in
376
- * production). Not meant for hand-written code.
377
- * @internal
378
- */
379
- export function registerServerReference<T extends any[], R>(
380
- id: string,
381
- fn: (...args: T) => R,
382
- name?: string
383
- ): ServerFunctionReference<T, R>;
384
-
385
- /**
386
- * Compiler ABI — emitted by compiled `"use server"` server output where
387
- * the function was referenced; produces the server-side callable. Calling
388
- * it during SSR runs the original function in-process (no HTTP), under a
389
- * request event derived from the current one — marked `serverOnly` and
390
- * carrying the function's meta. Not meant for hand-written code.
391
- * @internal
392
- */
393
- export function createServerReference<T extends any[], R>(
394
- reference: ServerFunctionReference<T, R>
395
- ): (...args: T) => R;
396
-
397
- /**
398
- * Declares a server function callable over HTTP GET. The server half is
399
- * identity-flavored — SSR calls stay in-process — but it brands the
400
- * declaration on the reference's metadata channel
401
- * (`getServerFunctionMetadata(fn)?.method === "GET"`) and records the
402
- * declared method for the function's id so `handleServerFunctionRequest`
403
- * honors it: GET-declared functions accept GET requests in addition to the
404
- * default POST transport (declaring GET grants, it does not revoke);
405
- * functions that never declared GET answer GET requests with 405.
406
- *
407
- * Wrap the reference at its declaration; the compiler round-trips the call
408
- * in both builds:
409
- *
410
- * ```ts
411
- * export const getUser = GET(async (id: string) => {
412
- * "use server";
413
- * return db.users.find(id);
414
- * });
415
- * ```
416
- */
417
- export function GET<A extends readonly any[], R>(
418
- fn: (...args: A) => R
419
- ): ServerFunction<A, Awaited<R>>;
420
-
421
385
  /** Wire-state transitions a live call's iterable can report (client side).
422
386
  * `"closed"` carries the error when a definite rejection (4xx) ended the
423
387
  * call instead of the retry loop. */
424
388
  export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
425
-
426
389
  /**
427
390
  * Type-level mirror of the client's live answer shape so isomorphic code
428
391
  * assigning `onstatus` typechecks against either build's declarations. On
@@ -430,155 +393,252 @@ export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
430
393
  * own iterable — there is no connection to report on.
431
394
  */
432
395
  export type LiveSource<R> = R & {
433
- onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
396
+ onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
434
397
  };
435
-
436
- /**
437
- * Declares a value-shaped live source: a server function returning an async
438
- * iterable whose yields are successive VALUES of one logical query, with
439
- * the contract that the source re-yields current state on every invocation.
440
- * Writes `live: true` on the metadata channel and brands the resolved
441
- * iterable (registered symbol `solid.LiveSource`) so SSR faces meeting the
442
- * value in-process can apply live policy (document face: first value, then
443
- * client takeover). Dispatch is untouched — over-the-wire calls stream the
444
- * raw registered function's result. Declare live outermost:
445
- * `live(GET(fn))`.
446
- */
447
- export function live<A extends readonly any[], R>(
448
- fn: (...args: A) => R
449
- ): ServerFunction<A, LiveSource<Awaited<R>>>;
450
-
451
398
  /** Identity of the currently executing server function call. */
452
399
  export interface ServerFunctionInvocation {
453
- id: string;
400
+ id: string;
401
+ /**
402
+ * The call arrived at the live address: a `live` loop is reading, and the
403
+ * answer is framed as an event stream for as long as it stands (RFC 10,
404
+ * `live(fn)` → Framing). A result policy building the answer's Response
405
+ * itself (`frameTransformResult`) reads this to frame it the same way.
406
+ * `false` for the data and bare addresses, and for in-process calls.
407
+ */
408
+ live: boolean;
409
+ /** A live call to a `broadcast` declaration: its answer is shared. */
410
+ broadcast?: boolean;
411
+ /**
412
+ * For a broadcast call, the arguments as they arrived on the wire: callers
413
+ * whose encodings are equal share one render. Absent when the encoding
414
+ * wasn't kept (an unbuffered body), and then the call is not shared.
415
+ */
416
+ shareKey?: string;
454
417
  }
455
-
456
- /**
457
- * Reads the in-flight server function invocation (its id) for the current
458
- * request event — usable inside a server function body, e.g. to key caches
459
- * or logs by function. Returns undefined outside a server function call.
460
- * The state lives in a module-private WeakMap keyed by the per-call request
461
- * event (never in `event.locals`, which derived events share with their
462
- * outer event). Distinct from `getServerFunctionMetadata(fn)`, which reads
463
- * a reference's static declaration metadata; this describes the call
464
- * currently executing.
465
- */
466
- export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
467
-
468
- /**
469
- * The event-keyed half of `getServerFunctionInvocation`, for callers handed
470
- * an event outside its provideEvent scope (the handler's result transforms
471
- * run after the scope has exited). Integration plumbing — application code
472
- * reads the ambient accessor instead.
473
- * @internal
474
- */
475
- export function getEventServerFunctionInvocation(
476
- event: RequestEvent | undefined
477
- ): ServerFunctionInvocation | undefined;
478
-
479
418
  /**
480
419
  * Hooks layering framework policy onto `handleServerFunctionRequest`.
481
420
  * All are optional — the bare handler dispatches, scopes events, and
482
421
  * encodes results on its own.
483
422
  */
484
423
  export interface HandleServerFunctionOptions {
485
- /**
486
- * Builds the request event a call runs under (default: bare
487
- * `{ request, locals: {} }`). Integrations supply their richer event
488
- * (cookies, response helpers, platform handles).
489
- */
490
- createEvent?(request: Request): ServerFunctionEvent;
491
- /**
492
- * Overrides the configured event provider for this handler — same
493
- * contract as the `provideEvent` config option.
494
- */
495
- provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
496
- /**
497
- * Overrides the configured per-invocation wrap for this handler — same
498
- * contract as the `wrapInvocation` config option (see
499
- * `WrapInvocationHook`), except it only applies to HTTP dispatch (a
500
- * per-request option can't see direct SSR calls).
501
- */
502
- wrapInvocation?: WrapInvocationHook;
503
- /**
504
- * Observes or replaces the function's result before encoding — the
505
- * extension point for response metadata policies (headers, statuses,
506
- * substituted results). Runs for returned and thrown results alike
507
- * (`context.thrown` distinguishes); `context.instance` is null for no-JS
508
- * calls. The context carries the call's identity — the function `id` and
509
- * the parsed `args` the implementation was invoked with — matching the
510
- * direct-call mirror (`transformDirectResult`), so a policy keying state
511
- * by the call works over either dispatch path. Return the result
512
- * unchanged to pass through, or a `ResponseEnvelope` (exposed through
513
- * the core entry) to send HTTP metadata plus a structured payload. Runs
514
- * before `collectFlightData`, so the flight hook sees the transformed
515
- * outcome — use `collectFlightData`, not this, to fold data into the
516
- * response.
517
- */
518
- transformResult?(
519
- event: ServerFunctionEvent,
520
- result: unknown,
521
- context: {
522
- id: string;
523
- args: unknown[];
524
- instance: string | null;
525
- request: Request;
526
- thrown?: boolean;
527
- }
528
- ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
529
- /**
530
- * Overrides the configured single-flight hook for this handler — same
531
- * contract as the `collectFlightData` config option (see
532
- * `CollectFlightDataHook`).
533
- */
534
- collectFlightData?: CollectFlightDataHook;
535
- /**
536
- * Overrides the configured single-flight fold policy for this handler —
537
- * same contract as the `transformFlightResult` config option.
538
- */
539
- transformFlightResult?(
540
- event: ServerFunctionEvent,
541
- outcome: { value: unknown; data: unknown },
542
- context: { id: string; args: unknown[]; instance: string | null; request: Request }
543
- ): Response | undefined | Promise<Response | undefined>;
544
- /**
545
- * Builds the response for calls made without the client runtime (no
546
- * instance header — no-JS form posts, direct HTTP). Receives the
547
- * (transformed) result, the request, and the decoded arguments; `thrown`
548
- * is set when the result was thrown rather than returned.
549
- *
550
- * Overrides the configured hook, which in turn overrides the built-in
551
- * `createNoJSHandler()` applied to browser form posts. Other
552
- * no-instance callers get the normal serialized response.
553
- */
554
- handleNoJS?(
555
- result: unknown,
556
- request: Request,
557
- args: unknown[],
558
- thrown?: boolean
559
- ): Response | Promise<Response>;
560
- /**
561
- * Overrides same-origin protection for this handler. Set to `false` only
562
- * when another trusted layer protects the endpoint.
563
- */
564
- csrf?: boolean | ServerFunctionCSRFOptions;
565
- /** Overrides the configured codec options for this handler. */
566
- codec?: JSONCodecOptions;
424
+ /**
425
+ * Builds the request event a call runs under (default: bare
426
+ * `{ request, locals: {} }`). Integrations supply their richer event
427
+ * (cookies, response helpers, platform handles).
428
+ *
429
+ * `request` is a standards-shaped `Request` — url, method, headers,
430
+ * signal, readable body — and nothing more. Enforcing `bodySizeLimit`
431
+ * puts the runtime between the host's stream and the decoder, so the
432
+ * object handed here may be one the runtime rebuilt; host-specific
433
+ * fields on the inbound object (`request.cf`, srvx's `runtime`, `ip`,
434
+ * `waitUntil`) are not carried. The host has its own request in closure
435
+ * when it calls the handler: read platform handles there and put them on
436
+ * the event (`locals`) rather than through `request`.
437
+ */
438
+ createEvent?(request: Request): ServerFunctionEvent;
439
+ /**
440
+ * Overrides the configured event provider for this handler — same
441
+ * contract as the `provideEvent` config option.
442
+ */
443
+ provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
444
+ /**
445
+ * Overrides the configured per-invocation wrap for this handler — same
446
+ * contract as the `wrapInvocation` config option (see
447
+ * `WrapInvocationHook`), except it is ENTRY-ONLY: it wraps exactly the
448
+ * invocation the request addressed. Nested direct server-function calls
449
+ * made by the dispatched body are not re-wrapped by it — they consult
450
+ * only the configured hook, which is ambient and wraps every direct call
451
+ * (a per-request option can't see direct SSR calls). Policy that must
452
+ * cover every hop belongs on `configureServerFunctionsServer`'s
453
+ * `wrapInvocation`, not here.
454
+ */
455
+ wrapInvocation?: WrapInvocationHook;
456
+ /**
457
+ * This request's server error hook, ahead of `configureServerErrors`' (see
458
+ * `ServerErrorHook` in `@solidjs/web`): the function's throw
459
+ * (`handling: "thrown"`) and a failure escaping through its result graph
460
+ * (`"channel"`), once per error per request, before the wire policy applies. Entry-only
461
+ * like `wrapInvocation`: a direct call the body makes during a render
462
+ * reports through the ambient hook.
463
+ */
464
+ onError?: ServerErrorHook;
465
+ /**
466
+ * Observes or replaces the function's result before encoding — the
467
+ * extension point for response metadata policies (headers, statuses,
468
+ * substituted results). Runs for returned and thrown results alike
469
+ * (`context.thrown` distinguishes). The context carries the call's
470
+ * identity — the function `id` and the parsed `args` the implementation
471
+ * was invoked with — matching the direct-call mirror
472
+ * (`transformDirectResult`), so a policy keying state by the call works
473
+ * over either dispatch path; `context.request` tells a scripted call (the
474
+ * `/data/` address) from a bare-address one. Return the result
475
+ * unchanged to pass through, or a `ResponseEnvelope` (exposed through
476
+ * the core entry) to send HTTP metadata plus a structured payload. Runs
477
+ * before `collectFlightData`, so the flight hook sees the transformed
478
+ * outcome — use `collectFlightData`, not this, to fold data into the
479
+ * response.
480
+ */
481
+ transformResult?(event: ServerFunctionEvent, result: unknown, context: {
482
+ id: string;
483
+ args: unknown[];
484
+ request: Request;
485
+ thrown?: boolean;
486
+ }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
487
+ /**
488
+ * Overrides the configured single-flight hook for this handler — same
489
+ * contract as the `collectFlightData` config option (see
490
+ * `CollectFlightDataHook`).
491
+ */
492
+ collectFlightData?: CollectFlightDataHook;
493
+ /**
494
+ * Overrides the configured single-flight fold policy for this handler —
495
+ * same contract as the `transformFlightResult` config option.
496
+ */
497
+ transformFlightResult?(event: ServerFunctionEvent, outcome: {
498
+ value: unknown;
499
+ data: unknown;
500
+ }, context: {
501
+ id: string;
502
+ args: unknown[];
503
+ request: Request;
504
+ }): Response | undefined | Promise<Response | undefined>;
505
+ /**
506
+ * Builds the response for calls made without the client runtime (at
507
+ * the bare address — no-JS form posts, direct HTTP). Receives the
508
+ * (transformed) result, the request, and the decoded arguments; `thrown`
509
+ * is set when the result was thrown rather than returned.
510
+ *
511
+ * Overrides the configured hook, which in turn overrides the built-in
512
+ * `createNoJSHandler()` applied to browser form posts. Other
513
+ * bare-address callers get the normal serialized response.
514
+ */
515
+ handleNoJS?(result: unknown, request: Request, args: unknown[], thrown?: boolean): Response | Promise<Response>;
516
+ /**
517
+ * Overrides same-origin protection for this handler. Set to `false` only
518
+ * when another trusted layer protects the endpoint.
519
+ */
520
+ csrf?: boolean | ServerFunctionCSRFOptions;
521
+ /** Overrides the configured codec options for this handler. */
522
+ codec?: JSONCodecOptions;
523
+ /**
524
+ * Overrides the configured argument payload bound for this handler (see
525
+ * `ServerFunctionsServerConfig.bodySizeLimit`).
526
+ */
527
+ bodySizeLimit?: number;
528
+ /**
529
+ * Overrides the configured argument count bound for this handler (see
530
+ * `ServerFunctionsServerConfig.maxArguments`).
531
+ */
532
+ maxArguments?: number;
567
533
  }
568
-
534
+ export declare function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
535
+ export declare function registerFlightDataSource(source: string, hook: CollectFlightDataHook): () => void;
536
+ export declare function registerServerFunction<T extends any[], R>(id: string, callback: (...args: T) => R): (...args: T) => R;
537
+ export declare function getServerFunction<T extends any[], R>(id: string): (...args: T) => R;
538
+ export declare function registerServerReference<T extends any[], R>(id: string, fn: (...args: T) => R, name?: string): ServerFunctionReference<T, R>;
539
+ export declare function createServerReference<T extends any[], R>(reference: ServerFunctionReference<T, R>): (...args: T) => R;
540
+ export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
541
+ export declare function live<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, LiveSource<Awaited<R>>>;
542
+ /**
543
+ * Declares a live server function whose answer is the same for every
544
+ * viewer: implies `live` and `GET`, and at the live address every caller
545
+ * with the same arguments shares ONE render (frames server half) or ONE
546
+ * data source (see sharedSourceResponse). The outer body still runs per
547
+ * call — a gate (auth, redirects) — but what it returns is the shared
548
+ * answer's to render.
549
+ * @experimental
550
+ */
551
+ export declare function broadcast<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, LiveSource<Awaited<R>>>;
552
+ export declare function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
553
+ export declare function getEventServerFunctionInvocation(event: RequestEvent | undefined): ServerFunctionInvocation | undefined;
554
+ export declare function foldSetCookies(headers: Headers, setCookies: readonly string[]): Headers;
555
+ export declare function createNoJSHandler(options?: NoJSHandlerOptions): (result: unknown, request: Request, args: unknown[], thrown?: boolean) => Promise<Response>;
556
+ /** @internal */
557
+ export declare function guardFailures(value: any, state: any): any;
558
+ /**
559
+ * The response-side codec stream: `serializeStream` (shared.js) hardened
560
+ * with request-lifetime teardown. Server-only on purpose — the shared half
561
+ * is re-exported into client bundles, where this plumbing is dead weight.
562
+ *
563
+ * An abort of `signal` (the platform fires request.signal when the caller's
564
+ * fetch aborts or the tab goes away) or the consumer cancelling the
565
+ * ReadableStream (how platforms surface a dropped connection to the body)
566
+ * stops pending serialization and tears down EVERY async-iterable or
567
+ * ReadableStream source in the result graph, nested ones included (#3125) —
568
+ * each producer's `iterator.return()` / `reader.cancel()` runs, so
569
+ * generator `finally` blocks execute instead of the server pumping streams
570
+ * nobody is reading. The wiring rides guardFailures' walk: it already wraps
571
+ * every channel before the codec sees the value, so the demand gate and the
572
+ * teardown registry are threaded through its state (`{ items: rows() }` —
573
+ * a cursor beside a total — gets the same two guarantees as `return rows()`).
574
+ *
575
+ * `live` selects the event-stream framing a live address answers in (see
576
+ * encodeLiveResult): the same payloads one per event, a comment heartbeat
577
+ * while idle, and each yield's position — parked on `live.pending` by the
578
+ * live adapter — riding as the `id:` of the record that carries the yield.
579
+ * A broadcast's shared stream (`live.nodes`) is nobody's body: it carries
580
+ * no heartbeat or chaos (each tap arms its own), and records which node
581
+ * each chunk carries for the fan-out to read (see startSharedSource).
582
+ */
583
+ export declare function serializeResponseStream(value: any, codecOptions: any, signal: any, scope: any, live: any): ReadableStream<any>;
584
+ /**
585
+ * Arms what every live body carries beyond its payloads, whichever writer
586
+ * frames them — the codec stream (`serializeResponseStream`) and a frame
587
+ * stream (`serverComponentResponse` at the live address) alike:
588
+ *
589
+ * - the heartbeat: an event-stream comment every 20s while the response is
590
+ * open, so a proxy's idle timeout never mistakes a waiting source for a
591
+ * dead one. Not demand-gated — the two bytes ride ahead of any parked
592
+ * pull. Unref'd where the runtime allows: the connection holds the
593
+ * process open, not the timer;
594
+ * - the chaos knob (dev only, `chaosReconnectEvery`): end this response as
595
+ * a dying connection would — `teardown` first (the producer's own), then
596
+ * the body errors with the stream still open, so the client reads a
597
+ * death, not a completion.
598
+ *
599
+ * Returns the disarm; the caller runs it on every road the body ends by, so
600
+ * a response that completed on its own is never touched.
601
+ * @internal
602
+ */
603
+ export declare function armLiveBody(controller: ReadableStreamDefaultController<Uint8Array>, teardown: () => void): () => void;
604
+ /** Message a sanitized (production) server error carries on the wire. */
605
+ export declare const GENERIC_SERVER_ERROR_MESSAGE = "Internal Server Error";
606
+ export declare function setServerFunctionsDev(dev: boolean): void;
607
+ export declare function sanitizeServerError(value: unknown): unknown;
608
+ export declare function serverFunctionUrl<A extends readonly unknown[]>(fn: ServerFunction<A, any>, ...args: A): string;
609
+ export declare function serverFunctionActionUrl(fn: ServerFunction | string, ...boundArgs: readonly unknown[]): string;
610
+ export declare function parseServerFunctionActionUrl(url: string): string | null;
569
611
  /**
570
612
  * Web-standard HTTP handler for server function calls: resolves the
571
- * function id from the request, gates GET dispatch on the declaration (405
572
- * for a GET request to a function that never declared `GET`; POST is always
573
- * accepted), decodes arguments, runs the function under a request-event scope,
574
- * and encodes the result (forwarding redirect/revalidation metadata
575
- * through headers). Mount it on the endpoint the client transport targets
576
- * (default `/_server`); platform adapters (h3, express, ...) convert their
577
- * request shape to a web `Request` around it.
613
+ * function id from the request, enforces the method allowlist (POST always
614
+ * dispatches; GET and HEAD dispatch only to functions that declared `GET`,
615
+ * with HEAD returning the equivalent GET's status and headers minus the
616
+ * body; every other method answers 405), decodes arguments, runs the
617
+ * function under a request-event scope, and encodes the result (forwarding
618
+ * redirect/revalidation metadata through headers). Mount it on the endpoint
619
+ * the client transport targets (default `/_server`); platform adapters (h3,
620
+ * express, ...) convert their request shape to a web `Request` around it.
578
621
  *
579
622
  * Requests are same-origin by default. The handler accepts browser requests
580
623
  * proven by `Sec-Fetch-Site`, `Origin`, or `Referer`, and rejects requests
581
- * without usable metadata unless explicitly configured otherwise.
624
+ * without usable metadata unless explicitly configured otherwise. A
625
+ * cross-origin browser call is admitted only when `csrf.origin` lists its
626
+ * `Origin`, and is then answered with CORS — `Access-Control-Allow-Origin`
627
+ * echoing that origin, the protocol's headers exposed, the `OPTIONS`
628
+ * preflight answered, credentials only when `csrf.allowCredentials` says so
629
+ * (#3538). GET/HEAD requests to `GET`-declared functions skip this gate:
630
+ * they are reads by contract, cross-site response READING is already
631
+ * blocked by same-origin policy, and skipping it keeps the
632
+ * `Vary: Sec-Fetch-Site, Origin, Referer` it would impose off the responses
633
+ * shared caches are meant to store. Once `csrf.origin` lists an origin,
634
+ * though, a read's answer depends on who asked — `Allow-Origin` for a
635
+ * listed caller, nothing for anyone else — so every declared read then
636
+ * carries `Vary: Origin` (and only that), or a shared cache would serve one
637
+ * caller's variant to the other.
638
+ *
639
+ * Every response leaves with `Cache-Control: no-store` unless the function
640
+ * set its own cache policy (via `respond()` headers or a returned
641
+ * `Response`) — caching is opt-in on the wire, not just in prose.
582
642
  *
583
643
  * When the event carries a `response` head stub (`event.response`, see the
584
644
  * server entry's `ResponseStub`), the handler folds it onto every outgoing
@@ -617,7 +677,7 @@ export interface HandleServerFunctionOptions {
617
677
  *
618
678
  * @example
619
679
  * ```ts
620
- * import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
680
+ * import { handleServerFunctionRequest } from "@solidjs/web/server-functions/server";
621
681
  * import "virtual:solid-server-function-manifest";
622
682
  *
623
683
  * // in the server's request handling:
@@ -626,56 +686,4 @@ export interface HandleServerFunctionOptions {
626
686
  * }
627
687
  * ```
628
688
  */
629
- export function handleServerFunctionRequest(
630
- request: Request,
631
- options?: HandleServerFunctionOptions
632
- ): Promise<Response>;
633
-
634
- /** Message a sanitized (production) server error carries on the wire. */
635
- export const GENERIC_SERVER_ERROR_MESSAGE: string;
636
-
637
- /**
638
- * The production error-sanitization policy `handleServerFunctionRequest`
639
- * applies to a plain thrown value before serialization. Returns `value`
640
- * unchanged in the dev build or when it is branded safe (`markSafeError`);
641
- * otherwise returns a generic `Error` carrying `GENERIC_SERVER_ERROR_MESSAGE`.
642
- * Exposed for frameworks composing their own dispatch around the same policy.
643
- */
644
- export function sanitizeServerError(value: unknown): unknown;
645
-
646
- export interface ServerFunctionRequestCall {
647
- type: "request";
648
- id: string;
649
- instance: string;
650
- request: Request;
651
- meta: ServerFunctionMetadata | undefined;
652
- time: number;
653
- }
654
-
655
- export interface ServerFunctionResponseCall {
656
- type: "response";
657
- id: string;
658
- instance: string;
659
- response: Response;
660
- meta: ServerFunctionMetadata | undefined;
661
- time: number;
662
- }
663
-
664
- export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
665
-
666
- /**
667
- * Client-only inspection seam. A no-op on this entry so isomorphic
668
- * `@solidjs/web/server-functions` imports resolve.
669
- */
670
- export function observeServerFunctionCalls(
671
- observer: (call: ServerFunctionCall) => void
672
- ): () => void;
673
-
674
- /**
675
- * Overrides the build-variant dev flag for this module instance — the seam
676
- * for test harnesses and hand-rolled bundles whose packaging cannot replace
677
- * `_DX_DEV_`. Applications never call this; select the dev build through
678
- * the `development` export condition instead.
679
- * @internal
680
- */
681
- export function setServerFunctionsDev(dev: boolean): void;
689
+ export declare function handleServerFunctionRequest(request: Request, options?: HandleServerFunctionOptions): Promise<Response>;