@solidjs/web 2.0.0-rc.8 → 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.
- package/dist/server.dev.js +626 -125
- package/dist/server.js +433 -95
- package/dist/server.observe.js +3980 -0
- package/dist/web.dev.js +208 -60
- package/dist/web.js +175 -58
- package/dist/web.observe.js +175 -58
- package/frames/dist/client.dev.js +103 -4
- package/frames/dist/client.js +5 -2
- package/frames/dist/client.observe.js +2123 -0
- package/frames/dist/server.dev.js +521 -79
- package/frames/dist/server.js +352 -52
- package/frames/dist/server.observe.js +4946 -0
- package/frames/package.json +12 -0
- package/package.json +87 -3
- package/server-functions/dist/client.dev.js +1102 -0
- package/server-functions/dist/client.js +74 -69
- package/server-functions/dist/client.observe.js +1102 -0
- package/server-functions/dist/server.dev.js +402 -31
- package/server-functions/dist/server.js +339 -30
- package/server-functions/dist/server.observe.js +2726 -0
- package/server-functions/package.json +12 -0
- package/types/client.d.ts +22 -1
- package/types/diagnostics.d.ts +24 -0
- package/types/frames/frame-transport.d.ts +1 -1
- package/types/index.d.ts +25 -15
- package/types/index.server.d.ts +35 -8
- package/types/jsx.d.ts +15 -4
- package/types/observe.d.ts +294 -0
- package/types/response.d.ts +18 -0
- package/types/server-functions/client.d.ts +32 -22
- package/types/server-functions/server.d.ts +28 -37
- package/types/server-functions/shared.d.ts +39 -9
- package/types/server-mock.d.ts +26 -4
- package/types/server-observe.d.ts +39 -0
- package/types/server.d.ts +104 -5
- package/types/trace.d.ts +79 -0
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ServerFunction, ServerFunctionMetadata } from "./shared.js";
|
|
2
|
-
export { ChunkReader, ERROR_HEADER, FLASH_COOKIE,
|
|
2
|
+
export { ChunkReader, ERROR_HEADER, FLASH_COOKIE, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, createChunk, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, deserializeStream, encodeErrorHeaderValue, frameAddress, getFlightDataConsumer, getFlightDataSourceIds, getServerFunctionMetadata, getServerFunctionsCodec, hasFlashCookie, invoke, isServerFunction, serializeString, subscribeFlightData, withMeta } from "./shared.js";
|
|
3
3
|
export { REVALIDATE_HEADER } from "../response.js";
|
|
4
4
|
import { JSONCodecOptions } from "../serializer-decode.js";
|
|
5
5
|
export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.js";
|
|
@@ -44,7 +44,7 @@ export interface ServerFunctionsClientConfig {
|
|
|
44
44
|
* Sends every server-function request — retries, telemetry, a test
|
|
45
45
|
* double, or an app's own route. Always called as `(address, init)`, the
|
|
46
46
|
* address relative to the document as the global one receives it, so
|
|
47
|
-
* `
|
|
47
|
+
* `parseServerFunctionActionUrl` reads the id back out for telemetry. `null`
|
|
48
48
|
* restores the global.
|
|
49
49
|
*
|
|
50
50
|
* ```ts
|
|
@@ -116,23 +116,6 @@ export interface ServerFunctionsClientConfig {
|
|
|
116
116
|
*/
|
|
117
117
|
serializeArgs?(args: unknown[]): string | Promise<string>;
|
|
118
118
|
}
|
|
119
|
-
export interface ServerFunctionRequestCall {
|
|
120
|
-
type: "request";
|
|
121
|
-
id: string;
|
|
122
|
-
instance: string;
|
|
123
|
-
request: Request;
|
|
124
|
-
meta: ServerFunctionMetadata | undefined;
|
|
125
|
-
time: number;
|
|
126
|
-
}
|
|
127
|
-
export interface ServerFunctionResponseCall {
|
|
128
|
-
type: "response";
|
|
129
|
-
id: string;
|
|
130
|
-
instance: string;
|
|
131
|
-
response: Response;
|
|
132
|
-
meta: ServerFunctionMetadata | undefined;
|
|
133
|
-
time: number;
|
|
134
|
-
}
|
|
135
|
-
export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
|
|
136
119
|
/** Wire-state transitions a live call's iterable can report. */
|
|
137
120
|
export type LiveSourceStatus = "connected" | "reconnecting" | "closed";
|
|
138
121
|
/**
|
|
@@ -154,9 +137,36 @@ export type LiveSource<R> = R & {
|
|
|
154
137
|
export interface ServerFunctionInvocation {
|
|
155
138
|
id: string;
|
|
156
139
|
}
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
140
|
+
/**
|
|
141
|
+
* The url a `GET()` reference's own call requests — the address to preload
|
|
142
|
+
* (`<link rel="preload" as="fetch">`), prefetch, warm in a service worker, or
|
|
143
|
+
* fetch by hand — built the way the transport builds it, so a fetch of it IS
|
|
144
|
+
* the call and matches the reference's later call in every cache that keys
|
|
145
|
+
* on the url. Arguments ride the query as they do on the wire (`?args=`,
|
|
146
|
+
* JSON), and must be JSON-safe here: the codec's encoding is asynchronous,
|
|
147
|
+
* and a url rendered as a value cannot wait for it. Resolved against the
|
|
148
|
+
* configured endpoint. The answer at this url is the transport's (codec
|
|
149
|
+
* shape) — read one by hand with `decodeResponse`.
|
|
150
|
+
*
|
|
151
|
+
* Defined for declared reads only. A reference on the default transport
|
|
152
|
+
* POSTs, and a POST is not described by its url; this throws with a pointer
|
|
153
|
+
* (declare `GET(fn)`, or start the call with `invoke(fn, { priority: "low"
|
|
154
|
+
* }, ...args)`). Also throws when the url would be long enough for the call
|
|
155
|
+
* to fall back to POST — a url you hold is always one the transport would
|
|
156
|
+
* request.
|
|
157
|
+
*
|
|
158
|
+
* ```tsx
|
|
159
|
+
* const getUser = GET(async (id: string) => { "use server"; ... });
|
|
160
|
+
* <link rel="preload" as="fetch" crossorigin href={serverFunctionUrl(getUser, id)} />
|
|
161
|
+
* ```
|
|
162
|
+
*
|
|
163
|
+
* The form-post address is a different url — `fn.url`, or
|
|
164
|
+
* `serverFunctionActionUrl` for one with bound arguments. The server entry
|
|
165
|
+
* exports the same function so isomorphic imports resolve.
|
|
166
|
+
*/
|
|
167
|
+
export declare function serverFunctionUrl<A extends readonly unknown[]>(fn: ServerFunction<A, any>, ...args: A): string;
|
|
168
|
+
export declare function serverFunctionActionUrl(fn: ServerFunction | string, ...boundArgs: readonly unknown[]): string;
|
|
169
|
+
export declare function parseServerFunctionActionUrl(url: string): string | null;
|
|
160
170
|
export declare function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
|
|
161
171
|
export declare function createServerReference(id: string, name?: string, base?: string): ServerFunction;
|
|
162
172
|
export declare function GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
|
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
export { ERROR_HEADER, FLASH_COOKIE,
|
|
1
|
+
export { ERROR_HEADER, FLASH_COOKIE, REDIRECT_HEADER, SERVER_FUNCTION_INVOKE, SINGLE_FLIGHT_HEADER, UNKNOWN_HEADER, clearFlashCookie, decodeErrorHeaderValue, decodeRedirectHeaderValue, decodeResponse, decodeResponsePayload, encodeErrorHeaderValue, getServerFunctionMetadata, hasFlashCookie, invoke, isServerFunction, subscribeFlightData, withMeta } from "./shared.js";
|
|
2
2
|
export { decodeFlashCookie, encodeFlashCookie } from "./flash.js";
|
|
3
3
|
import { ResponseEnvelope } from "../response.js";
|
|
4
4
|
import { JSONCodecOptions } from "../serializer-decode.js";
|
|
5
|
-
import { RequestEvent } from "../server.js";
|
|
6
|
-
import type { ServerFunction
|
|
5
|
+
import { RequestEvent, ServerErrorHook } from "../server.js";
|
|
6
|
+
import type { ServerFunction } from "./shared.js";
|
|
7
7
|
export type { FlightDataConsumer, FlightDataContext, InvokeOptions, ServerFunction, ServerFunctionInvoker, ServerFunctionMetadata, SingleFlightPayload } from "./shared.js";
|
|
8
8
|
export type { FlashSubmission } from "./flash.js";
|
|
9
9
|
/**
|
|
@@ -57,7 +57,9 @@ export interface ServerFunctionOutcome {
|
|
|
57
57
|
/**
|
|
58
58
|
* The outcome's `X-Revalidate` keys, split — the invalidation scope the
|
|
59
59
|
* mutation declared. Undefined when the outcome carries none (integrations
|
|
60
|
-
* typically collect everything for the target in that case)
|
|
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.
|
|
61
63
|
*/
|
|
62
64
|
revalidateKeys: string[] | undefined;
|
|
63
65
|
/**
|
|
@@ -182,7 +184,6 @@ export interface ServerFunctionsServerConfig {
|
|
|
182
184
|
transformResult?(event: ServerFunctionEvent, result: unknown, context: {
|
|
183
185
|
id: string;
|
|
184
186
|
args: unknown[];
|
|
185
|
-
instance: string | null;
|
|
186
187
|
request: Request;
|
|
187
188
|
thrown?: boolean;
|
|
188
189
|
}): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
|
|
@@ -201,7 +202,6 @@ export interface ServerFunctionsServerConfig {
|
|
|
201
202
|
}, context: {
|
|
202
203
|
id: string;
|
|
203
204
|
args: unknown[];
|
|
204
|
-
instance: string | null;
|
|
205
205
|
request: Request;
|
|
206
206
|
}): Response | undefined | Promise<Response | undefined>;
|
|
207
207
|
/**
|
|
@@ -371,15 +371,25 @@ export interface HandleServerFunctionOptions {
|
|
|
371
371
|
* `wrapInvocation`, not here.
|
|
372
372
|
*/
|
|
373
373
|
wrapInvocation?: WrapInvocationHook;
|
|
374
|
+
/**
|
|
375
|
+
* This request's server error hook, ahead of `configureServerErrors`' (see
|
|
376
|
+
* `ServerErrorHook` in `@solidjs/web`): the function's throw
|
|
377
|
+
* (`handling: "thrown"`) and a failure escaping through its result graph
|
|
378
|
+
* (`"channel"`), once per error, before the wire policy applies. Entry-only
|
|
379
|
+
* like `wrapInvocation`: a direct call the body makes during a render
|
|
380
|
+
* reports through the ambient hook.
|
|
381
|
+
*/
|
|
382
|
+
onError?: ServerErrorHook;
|
|
374
383
|
/**
|
|
375
384
|
* Observes or replaces the function's result before encoding — the
|
|
376
385
|
* extension point for response metadata policies (headers, statuses,
|
|
377
386
|
* substituted results). Runs for returned and thrown results alike
|
|
378
|
-
* (`context.thrown` distinguishes)
|
|
379
|
-
*
|
|
380
|
-
*
|
|
381
|
-
*
|
|
382
|
-
*
|
|
387
|
+
* (`context.thrown` distinguishes). The context carries the call's
|
|
388
|
+
* identity — the function `id` and the parsed `args` the implementation
|
|
389
|
+
* was invoked with — matching the direct-call mirror
|
|
390
|
+
* (`transformDirectResult`), so a policy keying state by the call works
|
|
391
|
+
* over either dispatch path; `context.request` tells a scripted call (the
|
|
392
|
+
* `/data/` address) from a bare-address one. Return the result
|
|
383
393
|
* unchanged to pass through, or a `ResponseEnvelope` (exposed through
|
|
384
394
|
* the core entry) to send HTTP metadata plus a structured payload. Runs
|
|
385
395
|
* before `collectFlightData`, so the flight hook sees the transformed
|
|
@@ -389,7 +399,6 @@ export interface HandleServerFunctionOptions {
|
|
|
389
399
|
transformResult?(event: ServerFunctionEvent, result: unknown, context: {
|
|
390
400
|
id: string;
|
|
391
401
|
args: unknown[];
|
|
392
|
-
instance: string | null;
|
|
393
402
|
request: Request;
|
|
394
403
|
thrown?: boolean;
|
|
395
404
|
}): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
|
|
@@ -409,18 +418,17 @@ export interface HandleServerFunctionOptions {
|
|
|
409
418
|
}, context: {
|
|
410
419
|
id: string;
|
|
411
420
|
args: unknown[];
|
|
412
|
-
instance: string | null;
|
|
413
421
|
request: Request;
|
|
414
422
|
}): Response | undefined | Promise<Response | undefined>;
|
|
415
423
|
/**
|
|
416
|
-
* Builds the response for calls made without the client runtime (
|
|
417
|
-
*
|
|
424
|
+
* Builds the response for calls made without the client runtime (at
|
|
425
|
+
* the bare address — no-JS form posts, direct HTTP). Receives the
|
|
418
426
|
* (transformed) result, the request, and the decoded arguments; `thrown`
|
|
419
427
|
* is set when the result was thrown rather than returned.
|
|
420
428
|
*
|
|
421
429
|
* Overrides the configured hook, which in turn overrides the built-in
|
|
422
430
|
* `createNoJSHandler()` applied to browser form posts. Other
|
|
423
|
-
*
|
|
431
|
+
* bare-address callers get the normal serialized response.
|
|
424
432
|
*/
|
|
425
433
|
handleNoJS?(result: unknown, request: Request, args: unknown[], thrown?: boolean): Response | Promise<Response>;
|
|
426
434
|
/**
|
|
@@ -441,23 +449,6 @@ export interface HandleServerFunctionOptions {
|
|
|
441
449
|
*/
|
|
442
450
|
maxArguments?: number;
|
|
443
451
|
}
|
|
444
|
-
export interface ServerFunctionRequestCall {
|
|
445
|
-
type: "request";
|
|
446
|
-
id: string;
|
|
447
|
-
instance: string;
|
|
448
|
-
request: Request;
|
|
449
|
-
meta: ServerFunctionMetadata | undefined;
|
|
450
|
-
time: number;
|
|
451
|
-
}
|
|
452
|
-
export interface ServerFunctionResponseCall {
|
|
453
|
-
type: "response";
|
|
454
|
-
id: string;
|
|
455
|
-
instance: string;
|
|
456
|
-
response: Response;
|
|
457
|
-
meta: ServerFunctionMetadata | undefined;
|
|
458
|
-
time: number;
|
|
459
|
-
}
|
|
460
|
-
export type ServerFunctionCall = ServerFunctionRequestCall | ServerFunctionResponseCall;
|
|
461
452
|
export declare function configureServerFunctionsServer(config?: ServerFunctionsServerConfig): void;
|
|
462
453
|
export declare function registerFlightDataSource(source: string, hook: CollectFlightDataHook): () => void;
|
|
463
454
|
export declare function registerServerFunction<T extends any[], R>(id: string, callback: (...args: T) => R): (...args: T) => R;
|
|
@@ -494,9 +485,9 @@ export declare function serializeResponseStream(value: any, codecOptions: any, s
|
|
|
494
485
|
export declare const GENERIC_SERVER_ERROR_MESSAGE = "Internal Server Error";
|
|
495
486
|
export declare function setServerFunctionsDev(dev: boolean): void;
|
|
496
487
|
export declare function sanitizeServerError(value: unknown): unknown;
|
|
497
|
-
export declare function
|
|
498
|
-
export declare function
|
|
499
|
-
export declare function
|
|
488
|
+
export declare function serverFunctionUrl<A extends readonly unknown[]>(fn: ServerFunction<A, any>, ...args: A): string;
|
|
489
|
+
export declare function serverFunctionActionUrl(fn: ServerFunction | string, ...boundArgs: readonly unknown[]): string;
|
|
490
|
+
export declare function parseServerFunctionActionUrl(url: string): string | null;
|
|
500
491
|
/**
|
|
501
492
|
* Web-standard HTTP handler for server function calls: resolves the
|
|
502
493
|
* function id from the request, enforces the method allowlist (POST always
|
|
@@ -557,7 +548,7 @@ export declare function parseServerFunctionUrl(url: string): string | null;
|
|
|
557
548
|
*
|
|
558
549
|
* @example
|
|
559
550
|
* ```ts
|
|
560
|
-
* import { handleServerFunctionRequest } from "@solidjs/web/server-functions";
|
|
551
|
+
* import { handleServerFunctionRequest } from "@solidjs/web/server-functions/server";
|
|
561
552
|
* import "virtual:solid-server-function-manifest";
|
|
562
553
|
*
|
|
563
554
|
* // in the server's request handling:
|
|
@@ -32,10 +32,13 @@ export interface FlightDataContext {
|
|
|
32
32
|
/**
|
|
33
33
|
* Consumer receiving single-flight data on the client: `data` is the
|
|
34
34
|
* integration-produced payload (opaque to the protocol), `context` carries
|
|
35
|
-
* the envelope metadata.
|
|
36
|
-
*
|
|
35
|
+
* the envelope metadata. `data` is `undefined` when the response carried
|
|
36
|
+
* integration metadata (a redirect, revalidation keys) but the server
|
|
37
|
+
* folded no slice for this source — the consumer still runs, to apply the
|
|
38
|
+
* metadata. Async consumers are awaited before the function value is
|
|
39
|
+
* returned to the caller, so caches are seeded first.
|
|
37
40
|
*/
|
|
38
|
-
export type FlightDataConsumer<D = unknown> = (data: D, context: FlightDataContext) => void | Promise<void>;
|
|
41
|
+
export type FlightDataConsumer<D = unknown> = (data: D | undefined, context: FlightDataContext) => void | Promise<void>;
|
|
39
42
|
/**
|
|
40
43
|
* The public contract of a server function reference — what a `"use
|
|
41
44
|
* server"` import is at runtime on either side: an async callable plus its
|
|
@@ -45,7 +48,12 @@ export interface ServerFunction<A extends readonly any[] = any[], T = any> {
|
|
|
45
48
|
(...args: A): Promise<T>;
|
|
46
49
|
/** The build-stable function id (stable across the client and server builds). */
|
|
47
50
|
readonly id: string;
|
|
48
|
-
/**
|
|
51
|
+
/**
|
|
52
|
+
* The plain-HTTP address of this function — what a `<form action>` posts
|
|
53
|
+
* to without the runtime (the integration behind `action={fn}` reads it).
|
|
54
|
+
* Not where the reference's own call goes: that is `serverFunctionUrl(fn,
|
|
55
|
+
* ...args)`, for a `GET()` reference — the url to preload or fetch.
|
|
56
|
+
*/
|
|
49
57
|
readonly url: string;
|
|
50
58
|
}
|
|
51
59
|
/**
|
|
@@ -155,6 +163,33 @@ export declare function parseServerFunctionAddress(pathname: string, endpoint: s
|
|
|
155
163
|
id: string;
|
|
156
164
|
data: boolean;
|
|
157
165
|
} | null;
|
|
166
|
+
/**
|
|
167
|
+
* The longest url a `GET()` call goes out as. Longer, the call dispatches
|
|
168
|
+
* over POST instead — a cache miss rather than a 414 from whichever proxy in
|
|
169
|
+
* the chain draws the line first — so no url describes it (`serverFunctionUrl`
|
|
170
|
+
* refuses to render one).
|
|
171
|
+
* @internal
|
|
172
|
+
*/
|
|
173
|
+
export declare const MAX_GET_URL_LENGTH = 2000;
|
|
174
|
+
/**
|
|
175
|
+
* Body of both entries' `serverFunctionActionUrl`: the plain-HTTP address of
|
|
176
|
+
* a function, `<endpoint>/<id>[?args=...]`.
|
|
177
|
+
* @internal
|
|
178
|
+
*/
|
|
179
|
+
export declare function serverFunctionActionUrlFor(endpoint: string, target: ServerFunction | string, boundArgs: readonly unknown[]): string;
|
|
180
|
+
/**
|
|
181
|
+
* Body of both entries' `serverFunctionUrl`: the url a `GET()` reference's
|
|
182
|
+
* own call requests, `<endpoint>/data/<id>[?args=...]`, built the way the
|
|
183
|
+
* transport builds it (JSON arguments in `args`; see `GET`'s client half)
|
|
184
|
+
* so a fetch of it is the call. Refuses — rather than answering with an
|
|
185
|
+
* address nothing would request — when the reference is not a declared
|
|
186
|
+
* read (the default transport POSTs, and a POST is not described by its
|
|
187
|
+
* url), when the arguments need the codec (the transport encodes those
|
|
188
|
+
* asynchronously, and a url rendered as a value cannot wait), and when the
|
|
189
|
+
* url would be long enough for the call to fall back to POST.
|
|
190
|
+
* @internal
|
|
191
|
+
*/
|
|
192
|
+
export declare function serverFunctionUrlFor(endpoint: string, fn: ServerFunction, args: readonly unknown[]): string;
|
|
158
193
|
/**
|
|
159
194
|
* Response header marking a thrown server-function error. The value is the
|
|
160
195
|
* error's message (the structured error itself travels in the body); `"true"`
|
|
@@ -163,11 +198,6 @@ export declare function parseServerFunctionAddress(pathname: string, endpoint: s
|
|
|
163
198
|
export declare const ERROR_HEADER = "X-Server-Function-Error";
|
|
164
199
|
export declare function encodeErrorHeaderValue(value: string): string;
|
|
165
200
|
export declare function decodeErrorHeaderValue(value: string): string;
|
|
166
|
-
/**
|
|
167
|
-
* Header carrying a per-call instance id. Its presence tells the server a
|
|
168
|
-
* scripted client is on the other end (vs. a no-JS form post).
|
|
169
|
-
*/
|
|
170
|
-
export declare const INSTANCE_HEADER = "X-Server-Function-Instance";
|
|
171
201
|
/** Header carrying the body format tag (a `BodyFormat` value). */
|
|
172
202
|
export declare const BODY_FORMAT_HEADER = "X-Server-Function-Format";
|
|
173
203
|
/**
|
package/types/server-mock.d.ts
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
import type { RequestEvent, RequestEventLocals, ResponseStub } from "./client.js";
|
|
2
2
|
import type { JSX } from "./jsx.js";
|
|
3
|
+
import type { ServerErrorSite } from "solid-js";
|
|
4
|
+
/**
|
|
5
|
+
* Where a server-side failure was met, as the server error hook hears it —
|
|
6
|
+
* the client's view of the server entry's type (see `configureServerErrors`
|
|
7
|
+
* there). `kind: "render"`: `fallback`/`client`/`failed`; `kind:
|
|
8
|
+
* "server-function"`: `thrown`/`channel`.
|
|
9
|
+
*/
|
|
10
|
+
export interface ServerErrorContext extends Omit<ServerErrorSite, "event"> {
|
|
11
|
+
event?: RequestEvent;
|
|
12
|
+
}
|
|
13
|
+
/** The server error hook (see the server entry's `configureServerErrors`). Its return is the wire value; nothing for the default. */
|
|
14
|
+
export type ServerErrorHook = (error: unknown, context: ServerErrorContext) => unknown | void;
|
|
15
|
+
export interface ServerErrorsConfig {
|
|
16
|
+
onError?: ServerErrorHook;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Registers the ambient server error hook. Server-only; on the client this
|
|
20
|
+
* is a no-op so isomorphic setup code can call it unguarded.
|
|
21
|
+
*/
|
|
22
|
+
export declare function configureServerErrors(_config: ServerErrorsConfig): void;
|
|
3
23
|
type PreloadLinkAttributes = {
|
|
4
24
|
type?: string;
|
|
5
25
|
crossorigin?: JSX.HTMLCrossorigin;
|
|
@@ -118,7 +138,8 @@ export declare function renderToString<T>(fn: () => T, options?: {
|
|
|
118
138
|
noScripts?: boolean;
|
|
119
139
|
plugins?: any[];
|
|
120
140
|
manifest?: AssetManifest | AssetResolver | AssetResolverFn;
|
|
121
|
-
|
|
141
|
+
/** This render's server error hook, ahead of `configureServerErrors`' (see the server entry). */
|
|
142
|
+
onError?: ServerErrorHook;
|
|
122
143
|
/**
|
|
123
144
|
* Embedded-render contract for hosts that own the document. When the
|
|
124
145
|
* render output contains no `</head>`, everything head-bound (resolved
|
|
@@ -169,7 +190,8 @@ export declare function renderToStream<T>(fn: () => T, options?: {
|
|
|
169
190
|
onCompleteAll?: (info: {
|
|
170
191
|
write: (v: string) => void;
|
|
171
192
|
}) => void;
|
|
172
|
-
|
|
193
|
+
/** This render's server error hook, ahead of `configureServerErrors`' (see the server entry). */
|
|
194
|
+
onError?: ServerErrorHook;
|
|
173
195
|
/**
|
|
174
196
|
* Embedded-render contract for hosts that own the document. When the
|
|
175
197
|
* shell contains no `</head>`, everything head-bound at first flush
|
|
@@ -279,7 +301,7 @@ export declare function ssr(template: string[] | string, ...nodes: any[]): {
|
|
|
279
301
|
* output. Not meant for hand-written code.
|
|
280
302
|
* @internal
|
|
281
303
|
*/
|
|
282
|
-
export declare function ssrElement(name: string, props: any, children: any, needsId: boolean): {
|
|
304
|
+
export declare function ssrElement(name: string, props: any | any[] | (() => any | any[]), children: any, needsId: boolean, skip?: (key: string) => boolean): {
|
|
283
305
|
t: string;
|
|
284
306
|
};
|
|
285
307
|
/**
|
|
@@ -327,7 +349,7 @@ export declare function ssrHydrationKey(): string;
|
|
|
327
349
|
* Not meant for hand-written code.
|
|
328
350
|
* @internal
|
|
329
351
|
*/
|
|
330
|
-
export declare function resolveSSRNode(node: any, result?: any, top?: boolean): any;
|
|
352
|
+
export declare function resolveSSRNode(node: any, result?: any, top?: boolean, nested?: boolean): any;
|
|
331
353
|
/**
|
|
332
354
|
* Escapes a string for safe inclusion in HTML output. Used by the SSR
|
|
333
355
|
* runtime; not generally part of user code.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { type FrameProducedEvent } from "./observe.js";
|
|
2
|
+
import type { RequestEvent } from "./server.js";
|
|
3
|
+
/** What the runtime passes an observation from either dispatch leg. */
|
|
4
|
+
export interface InvocationContext {
|
|
5
|
+
id: string;
|
|
6
|
+
direct: boolean;
|
|
7
|
+
event: RequestEvent;
|
|
8
|
+
request?: Request;
|
|
9
|
+
args: unknown[];
|
|
10
|
+
}
|
|
11
|
+
/** What the frame producer hands an observation: the stream's identity. */
|
|
12
|
+
export interface FrameObservation {
|
|
13
|
+
/** Counts the chunk — call for every chunk written after `start`. */
|
|
14
|
+
chunk(chunk: {
|
|
15
|
+
type: string;
|
|
16
|
+
id: string;
|
|
17
|
+
}): void;
|
|
18
|
+
/** Delivers the record. `error` is the value thrown on the synchronous failure path. */
|
|
19
|
+
settle(outcome: FrameProducedEvent["outcome"], error?: unknown): void;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Opens the observation of one frame stream, at its `start`; the producer
|
|
23
|
+
* feeds it every chunk and settles it at `complete`. `undefined` with no
|
|
24
|
+
* listener or outside observe builds — the producer then does nothing
|
|
25
|
+
* extra, not even read the clock.
|
|
26
|
+
*/
|
|
27
|
+
export declare function observeFrame(frame: {
|
|
28
|
+
id: string;
|
|
29
|
+
version: number;
|
|
30
|
+
}): FrameObservation | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* Runs `execute` — the wrapped server-function execution — and reports it
|
|
33
|
+
* as an `"invocation"` record once it settles: synchronously for a sync
|
|
34
|
+
* return or throw, at resolution/rejection for a promise. Returns
|
|
35
|
+
* `execute`'s value (a promise is re-wrapped, still a native Promise);
|
|
36
|
+
* throws what it throws. With no listener, or outside observe builds, it
|
|
37
|
+
* is `execute()` and nothing else.
|
|
38
|
+
*/
|
|
39
|
+
export declare function observeInvocation<T>(context: InvocationContext, execute: () => T): T;
|
package/types/server.d.ts
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
|
-
import { sharedConfig, getOwner, createComponent, untrack, merge as mergeProps
|
|
1
|
+
import { sharedConfig, getOwner, createComponent, untrack, merge as mergeProps } from "solid-js";
|
|
2
|
+
import { ssrScope as scope } from "solid-js/internal";
|
|
3
|
+
import type { ServerErrorSite } from "solid-js/internal";
|
|
2
4
|
import { effect, memo } from "./render.js";
|
|
5
|
+
import { type TraceContext } from "./trace.js";
|
|
3
6
|
export { parseCookieHeader, serializeCookie } from "./cookies.js";
|
|
4
7
|
export { clearFlashCookie, hasFlashCookie } from "./cookies.js";
|
|
5
8
|
export { getServerFunctionMetadata, getServerFunctionRPC, isServerFunction } from "./server-functions/registry.js";
|
|
@@ -223,7 +226,14 @@ export declare function renderToString<T>(fn: () => T, options?: {
|
|
|
223
226
|
noScripts?: boolean;
|
|
224
227
|
plugins?: SerializerPlugin[];
|
|
225
228
|
manifest?: AssetManifest | AssetResolver | AssetResolverFn;
|
|
226
|
-
|
|
229
|
+
/**
|
|
230
|
+
* This render's server error hook, ahead of `configureServerErrors`'
|
|
231
|
+
* (see `ServerErrorHook`): every failure the render handles — an
|
|
232
|
+
* `<Errored>` fallback (`handling: "fallback"`), a hydration value that
|
|
233
|
+
* would not serialize (`"serialize"`) — once per error, with where it
|
|
234
|
+
* was met. A one-argument listener still works; it hears them all.
|
|
235
|
+
*/
|
|
236
|
+
onError?: ServerErrorHook;
|
|
227
237
|
/**
|
|
228
238
|
* Embedded-render contract for hosts that own the document. When the
|
|
229
239
|
* render output contains no `</head>`, everything head-bound (resolved
|
|
@@ -248,7 +258,18 @@ export declare function renderToStream<T>(fn: () => T, options?: {
|
|
|
248
258
|
onCompleteAll?: (info: {
|
|
249
259
|
write: (v: string) => void;
|
|
250
260
|
}) => void;
|
|
251
|
-
|
|
261
|
+
/**
|
|
262
|
+
* This render's server error hook, ahead of `configureServerErrors`'
|
|
263
|
+
* (see `ServerErrorHook`): every failure the render handles — an
|
|
264
|
+
* `<Errored>` fallback (`handling: "fallback"`), a rejected fragment
|
|
265
|
+
* (`"client"`), a hydration value that would not serialize
|
|
266
|
+
* (`"serialize"`) — and the one that fails the request (`"failed"`),
|
|
267
|
+
* once per error, with where it was met. A one-argument listener still
|
|
268
|
+
* works; it hears them all — filter on `context.handling` for the
|
|
269
|
+
* request-failing ones alone. Without a hook (here or ambient) a
|
|
270
|
+
* failure that fails the request goes to `console.error`.
|
|
271
|
+
*/
|
|
272
|
+
onError?: ServerErrorHook;
|
|
252
273
|
/**
|
|
253
274
|
* Embedded-render contract for hosts that own the document. When the
|
|
254
275
|
* shell contains no `</head>`, everything head-bound at first flush
|
|
@@ -358,7 +379,7 @@ export declare function ssrStyle(value: string | {
|
|
|
358
379
|
[k: string]: string;
|
|
359
380
|
}): string;
|
|
360
381
|
export declare function ssrStyleProperty(name: string, value: any): string;
|
|
361
|
-
export declare function ssrElement(name: string, props: any, children: any, needsId: boolean): {
|
|
382
|
+
export declare function ssrElement(name: string, props: any | any[] | (() => any | any[]), children: any, needsId: boolean, skip?: (key: string) => boolean): {
|
|
362
383
|
t: string;
|
|
363
384
|
};
|
|
364
385
|
export declare function ssrAttribute(key: string, value: any): string;
|
|
@@ -376,20 +397,98 @@ export declare function generateHydrationScript(options?: {
|
|
|
376
397
|
nonce?: string;
|
|
377
398
|
eventNames?: string[];
|
|
378
399
|
}): string;
|
|
379
|
-
export declare function resolveSSRNode(node: any, result?: any, top?: boolean): any;
|
|
400
|
+
export declare function resolveSSRNode(node: any, result?: any, top?: boolean, nested?: boolean): any;
|
|
380
401
|
export declare const RequestContext: unique symbol; /**
|
|
402
|
+
* Where a server-side failure was met, as the server error hook hears it.
|
|
403
|
+
*
|
|
404
|
+
* `kind: "render"` — `fallback`: an `<Errored>` rendered its fallback;
|
|
405
|
+
* `client`: a `<Loading>` fragment rejected and the client re-renders the
|
|
406
|
+
* subtree; `failed`: nothing contained it and the request fails;
|
|
407
|
+
* `serialize`: a hydration value would not serialize and the render went on
|
|
408
|
+
* without it (a render that passed `onError`). `kind: "server-function"` — `thrown`:
|
|
409
|
+
* the body threw; `channel`: a rejection or throw escaping through the
|
|
410
|
+
* result graph (a promise, an iterable, a stream) with the head already
|
|
411
|
+
* committed. `boundary` is the hydration id the boundary records and
|
|
412
|
+
* findings use; `ownerPath` is where the error was THROWN — the component
|
|
413
|
+
* labels root-first up the owner chain it escaped, when the compiler emitted
|
|
414
|
+
* them — and `boundaryPath` where it was MET, the same labels up the
|
|
415
|
+
* boundary's chain (what broke, and what the user saw); `functionId`/`direct`
|
|
416
|
+
* name the server function and whether it was an in-process call during
|
|
417
|
+
* SSR; `event` the request, when the failure happened inside one.
|
|
418
|
+
*/
|
|
419
|
+
export interface ServerErrorContext extends Omit<ServerErrorSite, "event"> {
|
|
420
|
+
event?: RequestEvent;
|
|
421
|
+
}
|
|
422
|
+
/**
|
|
423
|
+
* The server error hook (see `configureServerErrors`): every failure the
|
|
424
|
+
* server runtime handles or fails on, once per error object, with where it
|
|
425
|
+
* was met. Return the value the client should receive in place of the error
|
|
426
|
+
* — rendered into the fallback, serialized for hydration, sent as the RPC
|
|
427
|
+
* error — or nothing for the default policy (a generic `Error` outside the
|
|
428
|
+
* dev build, the error itself in it; `markSafeError` still passes through).
|
|
429
|
+
* A returned value is taken as intended client-facing content and is not
|
|
430
|
+
* sanitized again. Ignored for `handling: "failed"`, which has no wire.
|
|
431
|
+
*
|
|
432
|
+
* One road a mapping does not reach: a rejected async source's serialized
|
|
433
|
+
* rejection is encoded the moment the source rejects, ahead of the boundary
|
|
434
|
+
* that meets the failure, and carries the default policy's value there. The
|
|
435
|
+
* hydrating client renders from the boundary's record, which carries the
|
|
436
|
+
* mapping; no tick is added to the error path to make the two agree.
|
|
437
|
+
*/
|
|
438
|
+
export type ServerErrorHook = (error: unknown, context: ServerErrorContext) => unknown | void;
|
|
439
|
+
export interface ServerErrorsConfig {
|
|
440
|
+
/** The hook, or `undefined` to clear it. */
|
|
441
|
+
onError?: ServerErrorHook;
|
|
442
|
+
}
|
|
443
|
+
/**
|
|
444
|
+
* Registers the ambient server error hook — the one call a server
|
|
445
|
+
* `init()` makes to see every failure the runtime handles in production:
|
|
446
|
+
* an `<Errored>` fallback rendered, a `<Loading>` fragment rejected, a
|
|
447
|
+
* server-function throw (HTTP dispatch or an in-process call during SSR),
|
|
448
|
+
* the failure that fails a request. Called once per error object, at first
|
|
449
|
+
* sight, wherever the runtime met it; its return, when given, is the wire
|
|
450
|
+
* value (see `ServerErrorHook`). A per-request hook — `renderToStream`'s
|
|
451
|
+
* `onError`, the server-function handler's — overrides it for that
|
|
452
|
+
* request. Registered on `globalThis` under a registered symbol, so a
|
|
453
|
+
* bundled server build and an instrumented `--import`ed module share it.
|
|
454
|
+
*
|
|
455
|
+
* ```ts
|
|
456
|
+
* configureServerErrors({
|
|
457
|
+
* onError: (error, { kind, handling, boundary, functionId }) => {
|
|
458
|
+
* Sentry.captureException(error, {
|
|
459
|
+
* mechanism: { type: `solid.${kind}.${handling}`, handled: handling !== "failed" }
|
|
460
|
+
* });
|
|
461
|
+
* }
|
|
462
|
+
* });
|
|
463
|
+
* ```
|
|
464
|
+
*/
|
|
465
|
+
export declare function configureServerErrors(config: ServerErrorsConfig): void;
|
|
466
|
+
/**
|
|
381
467
|
* The current request event, when called on the server inside a request
|
|
382
468
|
* scope (established by `provideRequestEvent` from `@solidjs/web/storage`
|
|
383
469
|
* or by the framework). Undefined on the client and outside a request.
|
|
384
470
|
* Read it above `await` boundaries in partially-polyfilled environments.
|
|
385
471
|
*/
|
|
386
472
|
export declare function getRequestEvent(): RequestEvent | undefined;
|
|
473
|
+
/**
|
|
474
|
+
* The trace the current request belongs to — continued from the incoming
|
|
475
|
+
* W3C `traceparent` when there was one, originated by the runtime
|
|
476
|
+
* otherwise; in observe/dev builds, merged with the installed provider's
|
|
477
|
+
* answer (`OBSERVE.server.trace`). Same object for every read within the
|
|
478
|
+
* request, direct server-function calls included. For a render outside a
|
|
479
|
+
* request scope, the render's own trace. `undefined` outside both, and on
|
|
480
|
+
* the client. Forward it downstream from a server function with
|
|
481
|
+
* `getTraceContext()?.entries.traceparent`.
|
|
482
|
+
*/
|
|
483
|
+
export declare function getTraceContext(): TraceContext | undefined;
|
|
484
|
+
/** A fresh, uncommitted response head. */
|
|
387
485
|
export declare function createResponseStub(): ResponseStub;
|
|
388
486
|
export declare function createRequestEvent<T extends object = {}>(request: Request, init?: T): RequestEvent & {
|
|
389
487
|
response: ResponseStub;
|
|
390
488
|
} & T;
|
|
391
489
|
export declare function commitResponseStub(stub: ResponseStub, options?: {
|
|
392
490
|
allowLateLocation?: boolean;
|
|
491
|
+
event?: RequestEvent;
|
|
393
492
|
}): ResponseStub;
|
|
394
493
|
export declare function getExpectedRedirectStatus(response: ResponseStub): number;
|
|
395
494
|
export declare function commitEventResponse(response: Response, event?: RequestEvent): Response;
|
package/types/trace.d.ts
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { type ServerTrace } from "solid-js";
|
|
2
|
+
/**
|
|
3
|
+
* The trace the current request belongs to — continued from the incoming
|
|
4
|
+
* W3C `traceparent` when there was one, originated by the runtime
|
|
5
|
+
* otherwise. Read with `getTraceContext()`.
|
|
6
|
+
*/
|
|
7
|
+
export interface TraceContext {
|
|
8
|
+
/** 32 lowercase hex — the whole trace. */
|
|
9
|
+
traceId: string;
|
|
10
|
+
/** 16 lowercase hex — this request's span: runtime-generated unless a provider supplied it. */
|
|
11
|
+
spanId: string;
|
|
12
|
+
/** The incoming parent span, when the request continued a trace. */
|
|
13
|
+
parentId?: string;
|
|
14
|
+
/** The incoming `traceparent` sampled flag (bit 0); `undefined` when the runtime originated. */
|
|
15
|
+
sampled?: boolean;
|
|
16
|
+
/** The incoming `tracestate` header, verbatim. */
|
|
17
|
+
state?: string;
|
|
18
|
+
/** The incoming `baggage` header, verbatim. */
|
|
19
|
+
baggage?: string;
|
|
20
|
+
/**
|
|
21
|
+
* Named entries handed to the browser on the first response — emitted
|
|
22
|
+
* both as `Server-Timing` entries (`<name>;desc="<value>"`) and, for HTML
|
|
23
|
+
* documents, as `<meta name="<name>" content="<value>">` in the shell.
|
|
24
|
+
* The runtime fills `traceparent`; a provider adds its vendor pair
|
|
25
|
+
* (`sentry-trace`, `baggage`). Also what application code forwards
|
|
26
|
+
* downstream: `fetch(url, { headers: { traceparent: entries.traceparent } })`.
|
|
27
|
+
*/
|
|
28
|
+
entries: Record<string, string>;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* An observer's answer for the trace a request belongs to, merged over the
|
|
32
|
+
* runtime's default derivation: fields it returns replace the derived
|
|
33
|
+
* ones (`traceId`/`spanId` from an APM's active span), its `entries` merge
|
|
34
|
+
* by name over the runtime's. Called once per request (or per render, for
|
|
35
|
+
* a render outside a request scope — `request` is then `undefined`), at
|
|
36
|
+
* shell flush or the first `getTraceContext()`, whichever comes first.
|
|
37
|
+
* Return `undefined` to leave the derivation alone.
|
|
38
|
+
*/
|
|
39
|
+
export type TraceProvider = (request: Request | undefined) => Partial<TraceContext> | undefined;
|
|
40
|
+
declare module "solid-js" {
|
|
41
|
+
interface ServerTrace {
|
|
42
|
+
/** Installs `provider`, replacing any current one. Returns the uninstall. */
|
|
43
|
+
provide(provider: TraceProvider): () => void;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
/** The provider slot's type, as this package names it — `solid-js`'s `ServerTrace`, filled in above. */
|
|
47
|
+
export type TraceSlot = ServerTrace;
|
|
48
|
+
/** A derived trace plus whether the browser is told about it (see the header note). */
|
|
49
|
+
export interface TraceRecord {
|
|
50
|
+
context: TraceContext;
|
|
51
|
+
emit: boolean;
|
|
52
|
+
}
|
|
53
|
+
/** `00-<traceId>-<spanId>-<flags>` for a context. */
|
|
54
|
+
export declare function formatTraceparent(context: TraceContext): string;
|
|
55
|
+
/**
|
|
56
|
+
* The trace record for `key`, derived once: incoming `traceparent` /
|
|
57
|
+
* `tracestate` / `baggage` from `request`, origination when absent, then
|
|
58
|
+
* (observe/dev) the installed provider's answer merged over it.
|
|
59
|
+
*/
|
|
60
|
+
export declare function traceFor(key: object, request: Request | undefined): TraceRecord;
|
|
61
|
+
/**
|
|
62
|
+
* Appends the record's entries to `headers` as `Server-Timing`
|
|
63
|
+
* metrics — `<name>;desc="<value>"` — never duplicating a name the app
|
|
64
|
+
* already wrote. Nothing when the browser is not told (see `TraceRecord`).
|
|
65
|
+
* Must run before the response head commits.
|
|
66
|
+
*/
|
|
67
|
+
export declare function appendTraceServerTiming(headers: Headers, record: TraceRecord): void;
|
|
68
|
+
/**
|
|
69
|
+
* Folds a `Server-Timing` header value onto `target` entry by entry,
|
|
70
|
+
* skipping names already present — the header is a list, so a stub's
|
|
71
|
+
* trace entries and a response's own metrics (`db;dur=53`) coexist
|
|
72
|
+
* instead of one replacing the other.
|
|
73
|
+
*/
|
|
74
|
+
export declare function mergeServerTiming(target: Headers, value: string): void;
|
|
75
|
+
/**
|
|
76
|
+
* The record's entries as `<meta name content>` tags for the HTML shell's
|
|
77
|
+
* prelude (after charset/base). Empty when the browser is not told.
|
|
78
|
+
*/
|
|
79
|
+
export declare function traceMetaMarkup(record: TraceRecord): string;
|