@solidjs/web 2.0.0-rc.7 → 2.0.0-rc.9

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 (88) hide show
  1. package/dist/server.dev.js +638 -124
  2. package/dist/server.js +445 -94
  3. package/dist/{server.dev.cjs → server.observe.js} +602 -416
  4. package/dist/web.dev.js +229 -49
  5. package/dist/web.js +194 -46
  6. package/dist/{web.cjs → web.observe.js} +290 -275
  7. package/frames/dist/client.dev.js +103 -4
  8. package/frames/dist/client.js +5 -2
  9. package/frames/dist/{client.dev.cjs → client.observe.js} +139 -79
  10. package/frames/dist/server.dev.js +540 -79
  11. package/frames/dist/server.js +371 -52
  12. package/frames/dist/{server.cjs → server.observe.js} +544 -140
  13. package/frames/package.json +15 -21
  14. package/package.json +145 -294
  15. package/serialization/decode/package.json +3 -9
  16. package/serialization/package.json +3 -9
  17. package/serialization/types/serializer-decode.d.ts +49 -2
  18. package/server-functions/dist/{client.cjs → client.dev.js} +140 -107
  19. package/server-functions/dist/client.js +74 -69
  20. package/server-functions/dist/client.observe.js +1102 -0
  21. package/server-functions/dist/server.dev.js +430 -41
  22. package/server-functions/dist/server.js +367 -40
  23. package/server-functions/dist/{server.cjs → server.observe.js} +430 -85
  24. package/server-functions/package.json +15 -21
  25. package/server-functions/rich-args/package.json +3 -9
  26. package/storage/package.json +3 -9
  27. package/types/client.d.ts +39 -1
  28. package/types/diagnostics.d.ts +24 -0
  29. package/types/frames/frame-transport.d.ts +1 -1
  30. package/types/frames/serializer-decode.d.ts +49 -2
  31. package/types/index.d.ts +25 -15
  32. package/types/index.server.d.ts +35 -8
  33. package/types/jsx.d.ts +15 -4
  34. package/types/observe.d.ts +294 -0
  35. package/types/response.d.ts +18 -0
  36. package/types/serializer-decode.d.ts +49 -2
  37. package/types/server-functions/client.d.ts +32 -22
  38. package/types/server-functions/server.d.ts +55 -41
  39. package/types/server-functions/shared.d.ts +39 -9
  40. package/types/server-mock.d.ts +26 -4
  41. package/types/server-observe.d.ts +39 -0
  42. package/types/server.d.ts +105 -6
  43. package/types/trace.d.ts +79 -0
  44. package/dist/server.cjs +0 -3708
  45. package/dist/web.dev.cjs +0 -2285
  46. package/frames/dist/client.cjs +0 -2043
  47. package/frames/dist/server.dev.cjs +0 -4584
  48. package/serialization/dist/decode.cjs +0 -155
  49. package/serialization/dist/serialization.cjs +0 -275
  50. package/serialization/types-cjs/index.d.cts +0 -101
  51. package/serialization/types-cjs/package.json +0 -3
  52. package/serialization/types-cjs/serializer-decode.d.cts +0 -172
  53. package/serialization/types-cjs/serializer.d.cts +0 -101
  54. package/server-functions/dist/rich-args.cjs +0 -11
  55. package/server-functions/dist/server.dev.cjs +0 -2409
  56. package/storage/dist/storage.cjs +0 -12
  57. package/storage/types-cjs/index.d.cts +0 -28
  58. package/storage/types-cjs/package.json +0 -3
  59. package/types-cjs/client.d.cts +0 -197
  60. package/types-cjs/constants.d.cts +0 -20
  61. package/types-cjs/cookies.d.cts +0 -41
  62. package/types-cjs/frames/client.d.cts +0 -36
  63. package/types-cjs/frames/frame-client.d.cts +0 -370
  64. package/types-cjs/frames/frame-container-plugin.d.cts +0 -71
  65. package/types-cjs/frames/frame-sink.d.cts +0 -92
  66. package/types-cjs/frames/frame-transport.d.cts +0 -189
  67. package/types-cjs/frames/serializer-decode.d.cts +0 -172
  68. package/types-cjs/frames/serializer.d.cts +0 -101
  69. package/types-cjs/frames/server.d.cts +0 -52
  70. package/types-cjs/head.d.cts +0 -19
  71. package/types-cjs/index.d.cts +0 -191
  72. package/types-cjs/index.server.d.cts +0 -147
  73. package/types-cjs/jsx-properties.d.cts +0 -93
  74. package/types-cjs/jsx.d.cts +0 -4146
  75. package/types-cjs/package.json +0 -3
  76. package/types-cjs/reconcile.d.cts +0 -1
  77. package/types-cjs/render.d.cts +0 -6
  78. package/types-cjs/response.d.cts +0 -81
  79. package/types-cjs/serializer-decode.d.cts +0 -172
  80. package/types-cjs/serializer.d.cts +0 -101
  81. package/types-cjs/server-functions/client.d.cts +0 -184
  82. package/types-cjs/server-functions/flash.d.cts +0 -36
  83. package/types-cjs/server-functions/registry.d.cts +0 -100
  84. package/types-cjs/server-functions/rich-args.d.cts +0 -1
  85. package/types-cjs/server-functions/server.d.cts +0 -546
  86. package/types-cjs/server-functions/shared.d.cts +0 -283
  87. package/types-cjs/server-mock.d.cts +0 -337
  88. package/types-cjs/server.d.cts +0 -408
@@ -1,100 +0,0 @@
1
- export type { InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, ServerFunctionRPC } from "./shared.cjs";
2
- import type { InvokeOptions } from "./shared.cjs";
3
- export declare const SERVER_FUNCTION_METADATA: unique symbol;
4
- /**
5
- * Reads a server function reference's declaration metadata (e.g.
6
- * `method: "GET"` for `GET(fn)` references). Returns undefined when `fn`
7
- * is not a server function reference; plain references carry an empty
8
- * metadata object.
9
- */
10
- export declare function getServerFunctionMetadata(fn: any): any;
11
- /**
12
- * Whether `fn` is a server function reference (a client proxy or a
13
- * server-side registered callable). Detection is by the registered-symbol
14
- * metadata brand, so it holds across duplicated module instances.
15
- */
16
- export declare function isServerFunction(fn: any): boolean;
17
- /**
18
- * Attaches user-declared transport metadata to a server function reference
19
- * (client proxy or server-registered callable) and returns the reference.
20
- * Writes ride the same channel `GET` uses: later writes shallow-merge over
21
- * earlier ones, and `getServerFunctionMetadata(fn)` reads the merged bag —
22
- * so `withMeta` composes with `GET` in either order.
23
- *
24
- * The pattern is declare-on-function, react-in-hook: metadata declared
25
- * here is what `prepareRequest` receives as `context.meta`, letting
26
- * session-dynamic transport policy key on declarations instead of
27
- * comparing function ids:
28
- *
29
- * ```ts
30
- * export const chargeCard = withMeta(async (amount: number) => {
31
- * "use server";
32
- * // ...
33
- * }, { requiresAuth: true });
34
- *
35
- * configureServerFunctionsClient({
36
- * prepareRequest(init, { meta }) {
37
- * if (meta?.requiresAuth) {
38
- * return {
39
- * ...init,
40
- * headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
41
- * };
42
- * }
43
- * return init;
44
- * }
45
- * });
46
- * ```
47
- */
48
- export declare function withMeta(fn: any, meta: any): any;
49
- export declare const SERVER_FUNCTION_INVOKE: unique symbol;
50
- /**
51
- * Applies a server function once with per-call, invocation-scoped options —
52
- * `Function.prototype.call` for server functions, the options bag in the
53
- * `thisArg` slot (declaration wrappers like `GET` and `withMeta` are `bind`:
54
- * they return a new reference with context baked in; `invoke` applies one
55
- * call and leaves no residue on the reference).
56
- *
57
- * ```ts
58
- * import { invoke } from "@solidjs/web/server-functions";
59
- *
60
- * const user = await invoke(getUser, { signal: controller.signal }, id);
61
- * ```
62
- *
63
- * Options are strictly invocation-scoped — things that vary between calls
64
- * of the SAME function and cannot be declared or configured: `signal`
65
- * (the call's lifecycle; aborting rejects the call and cancels the
66
- * request), `keepalive` (calls made while the page unloads), `priority`
67
- * (fetch priority hint). Anything with a longer lifetime is refused with a
68
- * pointer to its home: session-dynamic transport policy → `prepareRequest`;
69
- * declaration-static shape → `GET`/`withMeta`; call policy (retries,
70
- * dedupe, deadlines) → the data layer that owns the call, wired through
71
- * `signal`.
72
- *
73
- * Dispatches through the reference's invocation channel
74
- * (`SERVER_FUNCTION_INVOKE`). Core's declaration wrappers forward it —
75
- * `GET` invokes over its query encoding, `live` ends its iteration on
76
- * abort. Wrappers that share calls (caches, channels) may adapt or decline
77
- * it; a data layer needs neither — it holds the reference below such
78
- * wrappers and invokes it directly with its own signal. On the server the
79
- * call runs in-process: `signal`
80
- * rejects the caller (the work, like a server behind HTTP, runs on unless
81
- * the function observes a signal itself) and the transport hints are
82
- * no-ops, since they describe a wire that does not exist.
83
- */
84
- export declare function invoke<A extends readonly any[], R>(fn: (...args: A) => R, options: InvokeOptions, ...args: A): R;
85
- export declare const LIVE_SOURCE: unique symbol;
86
- /**
87
- * Fills the RPC seam. Called by the transport halves (client fetch RPC,
88
- * server in-process dispatch) when the first server function reference is
89
- * created; first write wins — both halves register equivalent surfaces, and
90
- * a per-build half never coexists with the other build's.
91
- * @internal
92
- */
93
- export declare function provideServerFunctionRPC(rpc: any): void;
94
- /**
95
- * The registered RPC surface, or undefined when no server function exists
96
- * in this build's graph. Integration plumbing (routers): gate every use of
97
- * the transport/codec behind this read instead of importing it.
98
- * @internal
99
- */
100
- export declare function getServerFunctionRPC(): any;
@@ -1 +0,0 @@
1
- export declare function enableRichArguments(): void;
@@ -1,546 +0,0 @@
1
- export { ERROR_HEADER, FLASH_COOKIE, INSTANCE_HEADER, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, encodeErrorHeaderValue, getServerFunctionMetadata, hasFlashCookie, invoke, isServerFunction, subscribeFlightData, withMeta } from "./shared.cjs";
2
- export { decodeFlashCookie, encodeFlashCookie } from "./flash.cjs";
3
- import { ResponseEnvelope } from "../response.cjs";
4
- import { JSONCodecOptions } from "../serializer-decode.cjs";
5
- import { RequestEvent } from "../server.cjs";
6
- import type { ServerFunction, ServerFunctionMetadata } from "./shared.cjs";
7
- export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.cjs";
8
- export type { FlashSubmission } from "./flash.cjs";
9
- /**
10
- * The request event a server function call runs under: the base
11
- * `RequestEvent` (request + locals) with `serverOnly` added, set when the
12
- * call is an in-process SSR invocation whose result never serializes to a
13
- * client.
14
- */
15
- export interface ServerFunctionEvent extends RequestEvent {
16
- serverOnly?: boolean;
17
- }
18
- /**
19
- * What a server function call resolved to, as seen by the single-flight
20
- * hook — enough context for any data-production strategy without core
21
- * assuming one.
22
- */
23
- export interface ServerFunctionOutcome {
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).
61
- */
62
- revalidateKeys: string[] | undefined;
63
- /**
64
- * The request headers with the mutation's cookie effects applied: the
65
- * event response's `Set-Cookie`s (set during the call), then the
66
- * outcome's own (e.g. `redirect(to, { headers })`), later winning on
67
- * conflict, deletions honored. Build the data-collection request from
68
- * these so re-run reads observe post-mutation cookie state.
69
- */
70
- foldedHeaders: Headers;
71
- }
72
- /**
73
- * The single-flight server hook: given the request event and the function's
74
- * outcome, optionally produce a data payload (possibly async) to fold into
75
- * the response alongside the return value. Data production is a black box
76
- * to the protocol — render data-only, run route preloads, query a cache,
77
- * whatever the integration chooses; the payload just has to be
78
- * codec-serializable. Return undefined to send the response unchanged
79
- * (byte-identical to a call without the hook).
80
- *
81
- * Runs after `transformResult`, only for scripted calls that sent
82
- * `SINGLE_FLIGHT_HEADER` on the request, on returned results and thrown
83
- * `Response`/`ResponseEnvelope` control-flow signals alike (plain thrown
84
- * errors never collect, and neither do raw body-carrying `Response` values
85
- * — those are the caller's verbatim payload). The handler owns the
86
- * enveloping: contributed data ships as `{ value, data }` under the
87
- * single-flight response header. The generic halves of collection arrive
88
- * pre-digested on the outcome (`targetUrl`, `revalidateKeys`,
89
- * `foldedHeaders`); the hook supplies only the data strategy.
90
- */
91
- export type CollectFlightDataHook = (event: ServerFunctionEvent, outcome: ServerFunctionOutcome) => unknown | Promise<unknown>;
92
- /**
93
- * Wraps a server function execution — the per-invocation seam for
94
- * framework policies (per-function middleware, auth, logging, error
95
- * mapping). Called inside the call's event scope with the invocation
96
- * identity already established: `getServerFunctionInvocation()` answers
97
- * before, during and after `run()`. Must return (or resolve to) `run()`'s
98
- * result — replacing it replaces the function's result; throwing routes
99
- * through the handler's normal error encoding.
100
- *
101
- * The context carries the call's identity (`id`, parsed `args`), its
102
- * `event`, and how it arrived: `direct` is `true` for in-process SSR calls
103
- * (where `request` is absent) and `false` for HTTP dispatch. On the direct
104
- * path the wrapper must stay transparent for synchronous functions —
105
- * return `run()`'s value, not an unconditional promise, unless it needs to
106
- * be async.
107
- */
108
- export type WrapInvocationHook = (run: () => unknown, context: {
109
- id: string;
110
- args: unknown[];
111
- event: ServerFunctionEvent;
112
- request?: Request;
113
- direct: boolean;
114
- }) => unknown;
115
- /** Options for `createNoJSHandler`. */
116
- export interface NoJSHandlerOptions {
117
- /** The app's mount path, for resolving a relative redirect `Location`. */
118
- base?: string;
119
- }
120
- export type ServerFunctionOriginMatcher = string | readonly string[] | ((origin: string, request: Request) => boolean | Promise<boolean>);
121
- /** Same-origin validation options for server function requests. */
122
- export interface ServerFunctionCSRFOptions {
123
- /**
124
- * Expected public origin. Defaults to the incoming request URL's origin.
125
- * A function can validate origins dynamically for multi-tenant hosts.
126
- */
127
- origin?: ServerFunctionOriginMatcher;
128
- /**
129
- * Allows requests without `Sec-Fetch-Site`, `Origin`, or `Referer`.
130
- * Cross-origin metadata is still rejected.
131
- * @default false
132
- */
133
- allowRequestsWithoutOriginCheck?: boolean;
134
- /**
135
- * Applies the origin gate to GET-declared reads as well. By default the
136
- * gate is skipped for declared reads: same-origin policy already keeps a
137
- * cross-site caller from READING the response, and the gate's `Vary`
138
- * fragments (or, on CDNs that ignore Vary, poisons) the shared-cache
139
- * entries the `GET` helper exists to enable (#3071). The premise that
140
- * skip rests on is `GET()`'s safety contract — declared reads are safe
141
- * to EXECUTE from any origin (#3114). A deployment that does not rely
142
- * on shared caches can enable this to gate its reads too.
143
- * @default false
144
- */
145
- protectDeclaredReads?: boolean;
146
- }
147
- /** Options for `configureServerFunctionsServer`. */
148
- export interface ServerFunctionsServerConfig {
149
- /**
150
- * Establishes the request-event scope for a call — the function passed
151
- * runs with `event` visible to `getRequestEvent()`. Wire it to
152
- * `provideRequestEvent` from `@solidjs/web/storage` (or the framework's
153
- * equivalent). When omitted, falls back to the AsyncLocalStorage instance
154
- * an established request scope parks on the global.
155
- */
156
- provideEvent?: <T>(event: ServerFunctionEvent, fn: () => T) => T;
157
- /**
158
- * Wraps every server function execution — HTTP dispatch and direct SSR
159
- * calls alike — with the invocation identity already established (see
160
- * `WrapInvocationHook`). The per-invocation seam for framework policies:
161
- * per-function middleware, auth, logging, error mapping. A per-request
162
- * option overrides it for HTTP dispatch.
163
- */
164
- wrapInvocation?: WrapInvocationHook;
165
- /**
166
- * The unnamed single-flight hook: produces the data payload folded into
167
- * responses of calls that opted in (see `CollectFlightDataHook`).
168
- * Registered once by the integration that owns data production (a
169
- * router); per-handler `collectFlightData` options override it. Other
170
- * integrations contribute additively through
171
- * `registerFlightDataSource(id, hook)` instead of competing for this
172
- * slot.
173
- */
174
- collectFlightData?: CollectFlightDataHook;
175
- /**
176
- * Server-wide default for the handler's `transformResult` (same contract
177
- * — see `HandleServerFunctionRequestOptions`); a per-request option
178
- * overrides it. Registering it here makes result policies (e.g. frames'
179
- * `frameTransformResult`) work through generic dispatchers that call
180
- * `handleServerFunctionRequest(request)` with no options.
181
- */
182
- transformResult?(event: ServerFunctionEvent, result: unknown, context: {
183
- id: string;
184
- args: unknown[];
185
- instance: string | null;
186
- request: Request;
187
- thrown?: boolean;
188
- }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
189
- /**
190
- * `transformResult`'s counterpart for the single-flight fold: when a
191
- * call's flight payload needs a body only a policy knows how to build
192
- * (frames' `frameTransformFlightResult` — an invalidated entry is
193
- * markup), this gets first refusal on the `{ value, data }` outcome.
194
- * Return a `Response` to carry the outcome (call headers and cookies are
195
- * copied onto it), or `undefined` to decline and keep the plain
196
- * serialized envelope. A per-request option overrides it.
197
- */
198
- transformFlightResult?(event: ServerFunctionEvent, outcome: {
199
- value: unknown;
200
- data: unknown;
201
- }, context: {
202
- id: string;
203
- args: unknown[];
204
- instance: string | null;
205
- request: Request;
206
- }): Response | undefined | Promise<Response | undefined>;
207
- /**
208
- * The in-process mirror of `transformResult` for direct (same-server)
209
- * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
210
- */
211
- transformDirectResult?(value: unknown, options: {
212
- id: string;
213
- args: unknown[];
214
- event: ServerFunctionEvent;
215
- }): unknown;
216
- /**
217
- * Server-wide response builder for calls made without the client runtime
218
- * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
219
- * per-request option overrides it. Set it to `createNoJSHandler({ base })`
220
- * to apply the convention to every non-scripted call rather than only to
221
- * browser form posts, to a handler of your own to replace it, or to
222
- * `null` to disable the built-in convention and answer form posts with
223
- * the plain serialized response.
224
- */
225
- handleNoJS?: ((result: unknown, request: Request, args: unknown[], thrown?: boolean) => Response | Promise<Response>) | null;
226
- /**
227
- * Mount path the HTTP handler answers on. Must match the client
228
- * configuration — the id travels as the segment after it, a request whose
229
- * path does not start with it is not a call, and SSR'd reference `url`s
230
- * (e.g. form actions) derive from it. Prefix it when the app serves from
231
- * a base path (e.g. `` `${BASE_URL}_server` ``).
232
- * @default "/_server"
233
- */
234
- endpoint?: string;
235
- /**
236
- * Same-origin protection for HTTP server function calls. Enabled by
237
- * default. Set to `false` only when another trusted layer protects the
238
- * endpoint.
239
- */
240
- csrf?: boolean | ServerFunctionCSRFOptions;
241
- /**
242
- * Codec options (extra plugins etc.) for decoding arguments and encoding
243
- * results — must match the client's. Stored in the shared layer, so
244
- * `decodeResponse` sees them too. When `serializeErrorStacks` is omitted,
245
- * the server-function boundary defaults it from this module's compiled
246
- * development variant.
247
- */
248
- codec?: JSONCodecOptions;
249
- /**
250
- * Upper bound, in bytes, on a call's argument payload — the POST body,
251
- * or the `?args=` query encoding. The payload is buffered and decoded
252
- * before dispatch, so its cost is paid before application code can
253
- * decline it; the bound is enforced up front and a request over it is
254
- * refused with `413` before any decoding (#3115). Raise it for functions
255
- * that accept large uploads, or set `Infinity` to remove the bound.
256
- * @default 1_048_576 (1 MiB)
257
- */
258
- bodySizeLimit?: number;
259
- /**
260
- * Upper bound on the number of arguments a call may carry. The decoded
261
- * argument array is spread into the function call, so an unbounded list
262
- * forces a range error out of any function regardless of what it does;
263
- * past the bound the request is refused with `400` (#3115).
264
- * @default 1000
265
- */
266
- maxArguments?: number;
267
- /**
268
- * The DEPLOYMENT SECRET: one value per deployment, from which any feature
269
- * that needs a key derives its own (domain-separated, so per-purpose keys
270
- * share no material). Today one feature does — the no-JS flash cookie
271
- * (#3239): the flash carries the submitted form input — whatever the user
272
- * typed — so its payload is always AES-GCM encrypted; it never rides the
273
- * wire or rests in the cookie jar as plaintext. Every instance that can
274
- * serve the render after a form post must share the secret (behind a load
275
- * balancer, a per-instance secret would silently lose outcomes), so there
276
- * is no generated fallback here: when this is not set, the secret falls
277
- * back to the one the Solid bundler plugin injects into the server build
278
- * (a fresh value per build), and with neither present the outcome is
279
- * simply not flashed — the form post still redirects cleanly, and dev
280
- * builds warn once. Any non-empty string works; rotating it (or
281
- * redeploying with the plugin's value) invalidates in-flight flashes,
282
- * which are 60-second one-shot cookies — the next render reads "no
283
- * flash".
284
- */
285
- secret?: string;
286
- }
287
- /**
288
- * A registered server function: its build-stable id paired with the
289
- * original implementation. Returned by `registerServerReference` and
290
- * consumed by the server-side `createServerReference`.
291
- *
292
- * Compiler ABI shape; hand-written code rarely constructs these.
293
- * @internal
294
- */
295
- export interface ServerFunctionReference<T extends any[] = any[], R = any> {
296
- id: string;
297
- fn: (...args: T) => R;
298
- /**
299
- * The function's source name, emitted by development builds only —
300
- * `createServerReference` seeds the metadata channel with it.
301
- * @internal
302
- */
303
- name?: string;
304
- }
305
- /** Wire-state transitions a live call's iterable can report (client side).
306
- * `"closed"` carries the error when a definite rejection (4xx) ended the
307
- * call instead of the retry loop. */
308
- export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
309
- /**
310
- * Type-level mirror of the client's live answer shape so isomorphic code
311
- * assigning `onstatus` typechecks against either build's declarations. On
312
- * the server the hook is inert: in-process calls hand back the source's
313
- * own iterable — there is no connection to report on.
314
- */
315
- export type LiveSource<R> = R & {
316
- onstatus?: (state: LiveSourceStatus, error?: unknown) => void;
317
- };
318
- /** Identity of the currently executing server function call. */
319
- export interface ServerFunctionInvocation {
320
- id: string;
321
- }
322
- /**
323
- * Hooks layering framework policy onto `handleServerFunctionRequest`.
324
- * All are optional — the bare handler dispatches, scopes events, and
325
- * encodes results on its own.
326
- */
327
- export interface HandleServerFunctionOptions {
328
- /**
329
- * Builds the request event a call runs under (default: bare
330
- * `{ request, locals: {} }`). Integrations supply their richer event
331
- * (cookies, response helpers, platform handles).
332
- */
333
- createEvent?(request: Request): ServerFunctionEvent;
334
- /**
335
- * Overrides the configured event provider for this handler — same
336
- * contract as the `provideEvent` config option.
337
- */
338
- provideEvent?<T>(event: ServerFunctionEvent, fn: () => T): T;
339
- /**
340
- * Overrides the configured per-invocation wrap for this handler — same
341
- * contract as the `wrapInvocation` config option (see
342
- * `WrapInvocationHook`), except it is ENTRY-ONLY: it wraps exactly the
343
- * invocation the request addressed. Nested direct server-function calls
344
- * made by the dispatched body are not re-wrapped by it — they consult
345
- * only the configured hook, which is ambient and wraps every direct call
346
- * (a per-request option can't see direct SSR calls). Policy that must
347
- * cover every hop belongs on `configureServerFunctionsServer`'s
348
- * `wrapInvocation`, not here.
349
- */
350
- wrapInvocation?: WrapInvocationHook;
351
- /**
352
- * Observes or replaces the function's result before encoding — the
353
- * extension point for response metadata policies (headers, statuses,
354
- * substituted results). Runs for returned and thrown results alike
355
- * (`context.thrown` distinguishes); `context.instance` is null for no-JS
356
- * calls. The context carries the call's identity — the function `id` and
357
- * the parsed `args` the implementation was invoked with — matching the
358
- * direct-call mirror (`transformDirectResult`), so a policy keying state
359
- * by the call works over either dispatch path. Return the result
360
- * unchanged to pass through, or a `ResponseEnvelope` (exposed through
361
- * the core entry) to send HTTP metadata plus a structured payload. Runs
362
- * before `collectFlightData`, so the flight hook sees the transformed
363
- * outcome — use `collectFlightData`, not this, to fold data into the
364
- * response.
365
- */
366
- transformResult?(event: ServerFunctionEvent, result: unknown, context: {
367
- id: string;
368
- args: unknown[];
369
- instance: string | null;
370
- request: Request;
371
- thrown?: boolean;
372
- }): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
373
- /**
374
- * Overrides the configured single-flight hook for this handler — same
375
- * contract as the `collectFlightData` config option (see
376
- * `CollectFlightDataHook`).
377
- */
378
- collectFlightData?: CollectFlightDataHook;
379
- /**
380
- * Overrides the configured single-flight fold policy for this handler —
381
- * same contract as the `transformFlightResult` config option.
382
- */
383
- transformFlightResult?(event: ServerFunctionEvent, outcome: {
384
- value: unknown;
385
- data: unknown;
386
- }, context: {
387
- id: string;
388
- args: unknown[];
389
- instance: string | null;
390
- request: Request;
391
- }): Response | undefined | Promise<Response | undefined>;
392
- /**
393
- * Builds the response for calls made without the client runtime (no
394
- * instance header — no-JS form posts, direct HTTP). Receives the
395
- * (transformed) result, the request, and the decoded arguments; `thrown`
396
- * is set when the result was thrown rather than returned.
397
- *
398
- * Overrides the configured hook, which in turn overrides the built-in
399
- * `createNoJSHandler()` applied to browser form posts. Other
400
- * no-instance callers get the normal serialized response.
401
- */
402
- handleNoJS?(result: unknown, request: Request, args: unknown[], thrown?: boolean): Response | Promise<Response>;
403
- /**
404
- * Overrides same-origin protection for this handler. Set to `false` only
405
- * when another trusted layer protects the endpoint.
406
- */
407
- csrf?: boolean | ServerFunctionCSRFOptions;
408
- /** Overrides the configured codec options for this handler. */
409
- codec?: JSONCodecOptions;
410
- /**
411
- * Overrides the configured argument payload bound for this handler (see
412
- * `ServerFunctionsServerConfig.bodySizeLimit`).
413
- */
414
- bodySizeLimit?: number;
415
- /**
416
- * Overrides the configured argument count bound for this handler (see
417
- * `ServerFunctionsServerConfig.maxArguments`).
418
- */
419
- maxArguments?: number;
420
- }
421
- export interface ServerFunctionRequestCall {
422
- type: "request";
423
- id: string;
424
- instance: string;
425
- request: Request;
426
- meta: ServerFunctionMetadata | undefined;
427
- time: number;
428
- }
429
- export interface ServerFunctionResponseCall {
430
- type: "response";
431
- id: string;
432
- instance: string;
433
- response: Response;
434
- meta: ServerFunctionMetadata | undefined;
435
- time: number;
436
- }
437
- export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
438
- export declare function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
439
- export declare function registerFlightDataSource(source: string, hook: CollectFlightDataHook): () => void;
440
- export declare function registerServerFunction<T extends any[], R>(id: string, callback: (...args: T) => R): (...args: T) => R;
441
- export declare function getServerFunction<T extends any[], R>(id: string): (...args: T) => R;
442
- export declare function registerServerReference<T extends any[], R>(id: string, fn: (...args: T) => R, name?: string): ServerFunctionReference<T, R>;
443
- export declare function createServerReference<T extends any[], R>(reference: ServerFunctionReference<T, R>): (...args: T) => R;
444
- export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
445
- export declare function live<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, LiveSource<Awaited<R>>>;
446
- export declare function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
447
- export declare function getEventServerFunctionInvocation(event: RequestEvent | undefined): ServerFunctionInvocation | undefined;
448
- export declare function foldSetCookies(headers: Headers, setCookies: readonly string[]): Headers;
449
- export declare function createNoJSHandler(options?: NoJSHandlerOptions): (result: unknown, request: Request, args: unknown[], thrown?: boolean) => Promise<Response>;
450
- /** @internal */
451
- export declare function guardFailures(value: any, state: any): any;
452
- /**
453
- * The response-side codec stream: `serializeStream` (shared.js) hardened
454
- * with request-lifetime teardown. Server-only on purpose — the shared half
455
- * is re-exported into client bundles, where this plumbing is dead weight.
456
- *
457
- * An abort of `signal` (the platform fires request.signal when the caller's
458
- * fetch aborts or the tab goes away) or the consumer cancelling the
459
- * ReadableStream (how platforms surface a dropped connection to the body)
460
- * stops pending serialization and tears down EVERY async-iterable or
461
- * ReadableStream source in the result graph, nested ones included (#3125) —
462
- * each producer's `iterator.return()` / `reader.cancel()` runs, so
463
- * generator `finally` blocks execute instead of the server pumping streams
464
- * nobody is reading. The wiring rides guardFailures' walk: it already wraps
465
- * every channel before the codec sees the value, so the demand gate and the
466
- * teardown registry are threaded through its state (`{ items: rows() }` —
467
- * a cursor beside a total — gets the same two guarantees as `return rows()`).
468
- */
469
- export declare function serializeResponseStream(value: any, codecOptions: any, signal: any, scope: any): ReadableStream<any>;
470
- /** Message a sanitized (production) server error carries on the wire. */
471
- export declare const GENERIC_SERVER_ERROR_MESSAGE = "Internal Server Error";
472
- export declare function setServerFunctionsDev(dev: boolean): void;
473
- export declare function sanitizeServerError(value: unknown): unknown;
474
- export declare function observeServerFunctionCalls(observer: (call: ServerFunctionCall) => void): () => void;
475
- export declare function serverFunctionUrl(id: string, boundArgs?: readonly unknown[]): string;
476
- export declare function parseServerFunctionUrl(url: string): string | null;
477
- /**
478
- * Web-standard HTTP handler for server function calls: resolves the
479
- * function id from the request, enforces the method allowlist (POST always
480
- * dispatches; GET and HEAD dispatch only to functions that declared `GET`,
481
- * with HEAD returning the equivalent GET's status and headers minus the
482
- * body; every other method answers 405), decodes arguments, runs the
483
- * function under a request-event scope, and encodes the result (forwarding
484
- * redirect/revalidation metadata through headers). Mount it on the endpoint
485
- * the client transport targets (default `/_server`); platform adapters (h3,
486
- * express, ...) convert their request shape to a web `Request` around it.
487
- *
488
- * Requests are same-origin by default. The handler accepts browser requests
489
- * proven by `Sec-Fetch-Site`, `Origin`, or `Referer`, and rejects requests
490
- * without usable metadata unless explicitly configured otherwise. GET/HEAD
491
- * requests to `GET`-declared functions skip this gate: they are reads by
492
- * contract, cross-site response READING is already blocked by same-origin
493
- * policy, and skipping it keeps the `Vary: Sec-Fetch-Site, Origin, Referer`
494
- * it would impose off the responses shared caches are meant to store.
495
- *
496
- * Every response leaves with `Cache-Control: no-store` unless the function
497
- * set its own cache policy (via `respond()` headers or a returned
498
- * `Response`) — caching is opt-in on the wire, not just in prose.
499
- *
500
- * When the event carries a `response` head stub (`event.response`, see the
501
- * server entry's `ResponseStub`), the handler folds it onto every outgoing
502
- * response as the head freezes — its `Set-Cookie` values (cookies appended
503
- * during the call) append cookie-by-cookie alongside the result's own,
504
- * other stub headers fill gaps (the call's response metadata wins; the
505
- * protocol-owned family — the error/format/single-flight tags, `Location`,
506
- * `X-Revalidate` — never fills, and neither does `Content-Type`/`Content-
507
- * Length` onto a bodiless response) — and marks the stub `committed`, so
508
- * later cookie/header writes report instead of silently missing the wire.
509
- *
510
- * ## Thrown-error sanitization (security default)
511
- *
512
- * A thrown `Response`/envelope (`redirect`/`reload`/`respond`) is intentional
513
- * control flow and is forwarded untouched. A *plain* thrown value (a bare
514
- * `Error`, string, or object) is different: serialized verbatim it would ship
515
- * its `message` and every own-property to the client — a driver/ORM error's
516
- * failing query, connection string, or bound parameters included. So outside
517
- * the dev build a plain thrown value is replaced with a generic `Error`
518
- * before serialization; the client still receives *an* `Error` (the shape
519
- * `submission.error` etc. expect), just with no leaked content. The dev
520
- * build keeps full fidelity (message, stack, own-props) for DX and the dev
521
- * toolbar inspector. Dev/prod is the BUILD VARIANT, not `NODE_ENV`:
522
- * `@solidjs/web` publishes a dev copy of this entry behind the
523
- * `development` export condition (what Vite dev resolves) and the default
524
- * resolution sanitizes — as does importing the runtime source directly with
525
- * no bundler signal (fail-safe).
526
- *
527
- * Escape hatch: brand the value with `markSafeError` (`Symbol.for(
528
- * "solid.SafeError")`) to send its content intact in every environment.
529
- * A `wrapInvocation`/`transformResult` override that maps errors expresses
530
- * intent the same way — throw a `Response`/envelope, or brand the mapped
531
- * error safe; an unbranded plain error it lets propagate is sanitized like
532
- * any other, so a framework onError policy must brand its result to keep a
533
- * custom client-facing message in production.
534
- *
535
- * @example
536
- * ```ts
537
- * import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
538
- * import "virtual:solid-server-function-manifest";
539
- *
540
- * // in the server's request handling:
541
- * if (url.pathname.startsWith("/_server")) {
542
- * return handleServerFunctionRequest(request);
543
- * }
544
- * ```
545
- */
546
- export declare function handleServerFunctionRequest(request: Request, options?: HandleServerFunctionOptions): Promise<Response>;