@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.
- package/README.md +1 -1
- package/dist/server.dev.js +5065 -0
- package/dist/server.js +1757 -355
- package/dist/{server.cjs → server.observe.js} +1951 -558
- package/dist/{dev.cjs → web.dev.js} +945 -550
- package/dist/web.js +635 -332
- package/dist/{dev.js → web.observe.js} +688 -403
- package/frames/dist/assets.js +92 -0
- package/frames/dist/client.dev.js +1296 -1198
- package/frames/dist/client.js +1128 -1191
- package/frames/dist/client.observe.js +2041 -0
- package/frames/dist/regions.js +171 -0
- package/frames/dist/server.dev.js +2549 -0
- package/frames/dist/server.js +1688 -3005
- package/frames/dist/server.observe.js +2548 -0
- package/frames/dist/trace.js +45 -0
- package/frames/dist/wire.js +594 -0
- package/frames/package.json +2 -25
- package/package.json +244 -256
- package/performance-tracks/dist/performance-tracks.dev.js +679 -0
- package/performance-tracks/dist/performance-tracks.js +6 -0
- package/performance-tracks/dist/performance-tracks.observe.js +667 -0
- package/performance-tracks/package.json +7 -0
- package/performance-tracks/types/index.d.ts +69 -0
- package/serialization/decode/package.json +2 -15
- package/serialization/dist/decode.js +121 -25
- package/serialization/dist/serialization.js +242 -88
- package/serialization/package.json +2 -15
- package/serialization/types/index.d.ts +85 -158
- package/serialization/types/serializer-decode.d.ts +173 -114
- package/serialization/types/serializer.d.ts +109 -0
- package/server-functions/dist/client.dev.js +1462 -0
- package/server-functions/dist/client.js +667 -165
- package/server-functions/dist/client.observe.js +1441 -0
- package/server-functions/dist/rich-args.js +84 -1
- package/server-functions/dist/server.dev.js +2714 -297
- package/server-functions/dist/server.js +2595 -271
- package/server-functions/dist/server.observe.js +3594 -0
- package/server-functions/package.json +2 -35
- package/server-functions/rich-args/package.json +2 -15
- package/skills/server-components/SKILL.md +117 -0
- package/storage/package.json +2 -15
- package/types/client.d.ts +342 -288
- package/types/constants.d.ts +22 -0
- package/types/cookies.d.ts +32 -84
- package/types/diagnostics.d.ts +80 -0
- package/types/frames/assets-tier.d.ts +78 -0
- package/types/frames/client.d.ts +40 -1
- package/types/frames/frame-client.d.ts +443 -280
- package/types/frames/frame-container-plugin.d.ts +64 -0
- package/types/frames/frame-morph.d.ts +29 -0
- package/types/frames/frame-sink.d.ts +141 -161
- package/types/frames/frame-transport.d.ts +263 -184
- package/types/frames/regions-tier.d.ts +60 -0
- package/types/frames/serializer-decode.d.ts +241 -0
- package/types/frames/serializer.d.ts +85 -158
- package/types/frames/server.d.ts +2 -2
- package/types/frames/trace-tier.d.ts +2 -0
- package/types/frames/tree-rewrite.d.ts +39 -0
- package/types/frames/wire-tier.d.ts +169 -0
- package/types/head.d.ts +20 -0
- package/types/index.d.ts +98 -81
- package/types/index.server.d.ts +159 -0
- package/types/jsx.d.ts +49 -44
- package/types/observe.d.ts +535 -0
- package/types/reconcile.d.ts +1 -0
- package/types/render.d.ts +11 -0
- package/types/request-error-hook.d.ts +5 -0
- package/types/response.d.ts +95 -147
- package/types/serializer-decode.d.ts +173 -114
- package/types/serializer.d.ts +85 -158
- package/types/server-functions/argument-codec.d.ts +30 -0
- package/types/server-functions/client.d.ts +238 -223
- package/types/server-functions/flash.d.ts +28 -30
- package/types/server-functions/registry.d.ts +105 -0
- package/types/server-functions/rich-args.d.ts +1 -10
- package/types/server-functions/server.d.ts +539 -531
- package/types/server-functions/shared.d.ts +398 -425
- package/types/server-functions/uploads.d.ts +50 -0
- package/types/server-mock.d.ts +120 -13
- package/types/server-observe.d.ts +86 -0
- package/types/server.d.ts +571 -422
- package/types/trace.d.ts +127 -0
- package/LICENSE +0 -21
- package/dist/web.cjs +0 -2033
- package/frames/dist/client.cjs +0 -2002
- package/frames/dist/client.dev.cjs +0 -2022
- package/frames/dist/server.cjs +0 -3877
- package/serialization/dist/decode.cjs +0 -139
- package/serialization/dist/serialization.cjs +0 -261
- package/serialization/types-cjs/index.d.cts +0 -182
- package/serialization/types-cjs/package.json +0 -3
- package/serialization/types-cjs/serializer-decode.d.cts +0 -182
- package/server-functions/dist/client.cjs +0 -834
- package/server-functions/dist/rich-args.cjs +0 -11
- package/server-functions/dist/server.cjs +0 -1242
- package/server-functions/dist/server.dev.cjs +0 -1242
- package/storage/dist/storage.cjs +0 -12
- package/storage/types-cjs/index.d.cts +0 -28
- package/storage/types-cjs/package.json +0 -3
- package/types/core.d.ts +0 -9
- package/types-cjs/client.d.cts +0 -337
- package/types-cjs/cookies.d.cts +0 -93
- package/types-cjs/core.d.cts +0 -9
- package/types-cjs/frames/client.d.cts +0 -36
- package/types-cjs/frames/frame-client.d.cts +0 -356
- package/types-cjs/frames/frame-sink.d.cts +0 -194
- package/types-cjs/frames/frame-transport.d.cts +0 -222
- package/types-cjs/frames/serializer.d.cts +0 -182
- package/types-cjs/frames/server.d.cts +0 -52
- package/types-cjs/index.d.cts +0 -244
- package/types-cjs/jsx-properties.d.cts +0 -93
- package/types-cjs/jsx.d.cts +0 -4159
- package/types-cjs/package.json +0 -3
- package/types-cjs/response.d.cts +0 -174
- package/types-cjs/serializer-decode.d.cts +0 -182
- package/types-cjs/serializer.d.cts +0 -182
- package/types-cjs/server-functions/client.d.cts +0 -262
- package/types-cjs/server-functions/flash.d.cts +0 -38
- package/types-cjs/server-functions/rich-args.d.cts +0 -10
- package/types-cjs/server-functions/server.d.cts +0 -681
- package/types-cjs/server-functions/shared.d.cts +0 -523
- package/types-cjs/server-mock.d.cts +0 -286
- 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
|
-
|
|
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
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
-
|
|
176
|
-
|
|
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
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
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
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
context: {
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
value: unknown,
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
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
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
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,
|
|
572
|
-
*
|
|
573
|
-
*
|
|
574
|
-
*
|
|
575
|
-
*
|
|
576
|
-
*
|
|
577
|
-
*
|
|
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>;
|