@solidjs/web 2.0.0-rc.1 → 2.0.0-rc.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/server.dev.js +4472 -0
- package/dist/server.js +1301 -251
- package/dist/{server.cjs → server.observe.js} +1501 -452
- package/dist/{dev.cjs → web.dev.js} +699 -360
- package/dist/web.js +454 -139
- package/dist/{dev.js → web.observe.js} +505 -211
- package/frames/dist/client.dev.js +463 -71
- package/frames/dist/client.js +363 -70
- package/frames/dist/{client.dev.cjs → client.observe.js} +486 -133
- package/frames/dist/server.dev.js +1713 -0
- package/frames/dist/server.js +552 -2583
- package/frames/dist/server.observe.js +1713 -0
- package/frames/package.json +2 -25
- package/package.json +214 -255
- package/performance-tracks/dist/performance-tracks.dev.js +678 -0
- package/performance-tracks/dist/performance-tracks.js +6 -0
- package/performance-tracks/dist/performance-tracks.observe.js +666 -0
- package/performance-tracks/package.json +7 -0
- package/performance-tracks/types/index.d.ts +67 -0
- package/serialization/decode/package.json +2 -15
- package/serialization/dist/decode.js +92 -15
- package/serialization/dist/serialization.js +103 -23
- package/serialization/package.json +2 -15
- package/serialization/types/index.d.ts +76 -157
- package/serialization/types/serializer-decode.d.ts +149 -112
- package/serialization/types/serializer.d.ts +101 -0
- package/server-functions/dist/client.dev.js +1364 -0
- package/server-functions/dist/client.js +611 -97
- package/server-functions/dist/client.observe.js +1343 -0
- package/server-functions/dist/server.dev.js +2138 -202
- package/server-functions/dist/server.js +2042 -199
- package/server-functions/dist/server.observe.js +3043 -0
- package/server-functions/package.json +2 -35
- package/server-functions/rich-args/package.json +2 -15
- package/storage/package.json +2 -15
- package/types/client.d.ts +193 -288
- package/types/constants.d.ts +20 -0
- package/types/cookies.d.ts +32 -84
- package/types/diagnostics.d.ts +56 -0
- package/types/frames/client.d.ts +1 -1
- package/types/frames/frame-client.d.ts +323 -259
- package/types/frames/frame-container-plugin.d.ts +72 -0
- package/types/frames/frame-sink.d.ts +101 -158
- package/types/frames/frame-transport.d.ts +192 -190
- package/types/frames/serializer-decode.d.ts +219 -0
- package/types/frames/serializer.d.ts +76 -157
- package/types/frames/server.d.ts +1 -1
- package/types/head.d.ts +19 -0
- package/types/index.d.ts +52 -80
- package/types/index.server.d.ts +174 -0
- package/types/jsx.d.ts +33 -35
- package/types/observe.d.ts +358 -0
- package/types/reconcile.d.ts +1 -0
- package/types/render.d.ts +9 -0
- package/types/response.d.ts +75 -150
- package/types/serializer-decode.d.ts +149 -112
- package/types/serializer.d.ts +76 -157
- package/types/server-functions/client.d.ts +192 -194
- package/types/server-functions/flash.d.ts +28 -30
- package/types/server-functions/registry.d.ts +102 -0
- package/types/server-functions/rich-args.d.ts +1 -10
- package/types/server-functions/server.d.ts +511 -475
- package/types/server-functions/shared.d.ts +366 -425
- package/types/server-mock.d.ts +110 -13
- package/types/server-observe.d.ts +77 -0
- package/types/server.d.ts +425 -425
- package/types/trace.d.ts +127 -0
- package/LICENSE +0 -21
- package/dist/web.cjs +0 -2008
- package/frames/dist/client.cjs +0 -1916
- package/frames/dist/server.cjs +0 -3756
- package/serialization/dist/decode.cjs +0 -122
- package/serialization/dist/serialization.cjs +0 -244
- 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 -793
- package/server-functions/dist/rich-args.cjs +0 -11
- package/server-functions/dist/server.cjs +0 -1171
- package/server-functions/dist/server.dev.cjs +0 -1171
- 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 -6
- package/types-cjs/client.d.cts +0 -337
- package/types-cjs/cookies.d.cts +0 -93
- package/types-cjs/core.d.cts +0 -6
- package/types-cjs/frames/client.d.cts +0 -36
- package/types-cjs/frames/frame-client.d.cts +0 -338
- 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 -231
- 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 -616
- package/types-cjs/server-functions/shared.d.cts +0 -523
- package/types-cjs/server-mock.d.cts +0 -277
- package/types-cjs/server.d.cts +0 -523
|
@@ -1,94 +1,6 @@
|
|
|
1
|
+
export { LIVE_LOCAL, LIVE_RESUME_FROM, LIVE_SOURCE, SERVER_FUNCTION_INVOKE, SERVER_FUNCTION_METADATA, getServerFunctionMetadata, getServerFunctionRPC, invoke, isServerFunction, provideServerFunctionRPC, withMeta } from "./registry.js";
|
|
2
|
+
export { FLASH_COOKIE, clearFlashCookie, hasFlashCookie, matchFlashCookie } from "../cookies.js";
|
|
1
3
|
import { JSONCodecOptions } from "../serializer-decode.js";
|
|
2
|
-
|
|
3
|
-
export type { JSONCodecOptions };
|
|
4
|
-
|
|
5
|
-
/**
|
|
6
|
-
* Configures the codec options for the server function wire format (extra
|
|
7
|
-
* Seroval plugins, feature policy, depth limit). Both peers must configure
|
|
8
|
-
* identical options or payloads will not round-trip. Usually called
|
|
9
|
-
* indirectly through `configureServerFunctionsClient` /
|
|
10
|
-
* `configureServerFunctionsServer` (their `codec` option writes through to
|
|
11
|
-
* here); call it directly only from universal code configuring both sides
|
|
12
|
-
* at once.
|
|
13
|
-
*/
|
|
14
|
-
export function configureServerFunctionsCodec(codec: JSONCodecOptions | undefined): void;
|
|
15
|
-
|
|
16
|
-
/**
|
|
17
|
-
* The currently configured codec options (set through
|
|
18
|
-
* `configureServerFunctionsCodec` or the client/server `codec` option), or
|
|
19
|
-
* undefined when running on the defaults. Integrations pass this to
|
|
20
|
-
* lower-level codec helpers so custom plugins configured by the app apply.
|
|
21
|
-
*
|
|
22
|
-
* Integration plumbing; not meant for hand-written application code.
|
|
23
|
-
* @internal
|
|
24
|
-
*/
|
|
25
|
-
export function getServerFunctionsCodec(): JSONCodecOptions | undefined;
|
|
26
|
-
|
|
27
|
-
/**
|
|
28
|
-
* Request header carrying the server function id (`"X-Server-Function-Id"`).
|
|
29
|
-
* Integrations can read it to identify which function a request targets;
|
|
30
|
-
* the id also arrives as the `id` query parameter for GET calls and no-JS
|
|
31
|
-
* form posts.
|
|
32
|
-
*/
|
|
33
|
-
export const FUNCTION_HEADER: string;
|
|
34
|
-
|
|
35
|
-
/**
|
|
36
|
-
* Request header carrying a per-call instance id
|
|
37
|
-
* (`"X-Server-Function-Instance"`). Its presence tells the server the call
|
|
38
|
-
* came through the client runtime — its absence marks a no-JS form post or
|
|
39
|
-
* direct HTTP call, which receive plain responses instead of codec-encoded
|
|
40
|
-
* ones.
|
|
41
|
-
*/
|
|
42
|
-
export const INSTANCE_HEADER: string;
|
|
43
|
-
|
|
44
|
-
/**
|
|
45
|
-
* Response header marking a thrown server-function error
|
|
46
|
-
* (`"X-Server-Function-Error"`). The client transport rejects with the
|
|
47
|
-
* decoded body when it is present (unless redirect/revalidation metadata
|
|
48
|
-
* marks the response as control flow). The value carries the error's
|
|
49
|
-
* message — `"true"` for thrown control-flow responses and non-Error
|
|
50
|
-
* values — encoded with `encodeErrorHeaderValue`, so integrations reading
|
|
51
|
-
* it must pass it through `decodeErrorHeaderValue`.
|
|
52
|
-
*/
|
|
53
|
-
export const ERROR_HEADER: string;
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* Encodes an error message for the `ERROR_HEADER` value. HTTP header values
|
|
57
|
-
* are latin1 ByteStrings — `Headers.set` throws on code points above U+00FF
|
|
58
|
-
* — so plain printable-latin1 messages ride verbatim (ASCII stays
|
|
59
|
-
* byte-identical on the wire) and everything else (CJK, emoji, controls)
|
|
60
|
-
* travels percent-encoded behind a marker. `decodeErrorHeaderValue`
|
|
61
|
-
* round-trips the message exactly, astral-plane characters included (lone
|
|
62
|
-
* surrogates are replaced with U+FFFD — they cannot survive UTF-8 anyway).
|
|
63
|
-
*
|
|
64
|
-
* Transport wire detail; not meant for hand-written code.
|
|
65
|
-
* @internal
|
|
66
|
-
*/
|
|
67
|
-
export function encodeErrorHeaderValue(value: string): string;
|
|
68
|
-
|
|
69
|
-
/**
|
|
70
|
-
* Decodes an `ERROR_HEADER` value produced by `encodeErrorHeaderValue`:
|
|
71
|
-
* marked values are percent-decoded, everything else (including values from
|
|
72
|
-
* peers that never encode) passes through untouched.
|
|
73
|
-
*
|
|
74
|
-
* Integration plumbing for readers of `ERROR_HEADER`; not meant for
|
|
75
|
-
* hand-written application code.
|
|
76
|
-
* @internal
|
|
77
|
-
*/
|
|
78
|
-
export function decodeErrorHeaderValue(value: string): string;
|
|
79
|
-
|
|
80
|
-
/**
|
|
81
|
-
* Header driving the single-flight protocol on both legs
|
|
82
|
-
* (`"X-Single-Flight"`). On the request it opts the call into data
|
|
83
|
-
* collection — the transport sends it automatically on non-GET calls while
|
|
84
|
-
* a flight-data consumer is subscribed (subscribing IS the opt-in). On the
|
|
85
|
-
* response it marks a body carrying the standardized `SingleFlightPayload`.
|
|
86
|
-
* How the data is produced (a data-only render, running route preloads,
|
|
87
|
-
* anything else) and what it means is entirely the integration's business —
|
|
88
|
-
* the protocol only standardizes the wire shape and the delivery.
|
|
89
|
-
*/
|
|
90
|
-
export const SINGLE_FLIGHT_HEADER: string;
|
|
91
|
-
|
|
92
4
|
/**
|
|
93
5
|
* The standardized body of a single-flight response (a response tagged with
|
|
94
6
|
* `SINGLE_FLIGHT_HEADER`): the function's return `value` plus the
|
|
@@ -96,112 +8,90 @@ export const SINGLE_FLIGHT_HEADER: string;
|
|
|
96
8
|
* HTTP handler. Integrations decoding passthrough responses themselves (no
|
|
97
9
|
* registered consumer) see this shape from `decodeResponse`. The top level
|
|
98
10
|
* is reserved for the protocol — integration payload lives entirely under
|
|
99
|
-
* `data`,
|
|
11
|
+
* `data`, the envelope keyed by source id (the unnamed registration's
|
|
12
|
+
* slice rides under the reserved id "true"); each slice can be any
|
|
13
|
+
* codec-serializable value.
|
|
100
14
|
*/
|
|
101
15
|
export interface SingleFlightPayload<T = unknown, D = unknown> {
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
16
|
+
/** The server function's return (or thrown) value. */
|
|
17
|
+
value: T;
|
|
18
|
+
/** The integration-produced data payload, keyed by source id. */
|
|
19
|
+
data: D;
|
|
106
20
|
}
|
|
107
|
-
|
|
108
21
|
/**
|
|
109
22
|
* Envelope context delivered alongside single-flight data: the transport
|
|
110
|
-
* response, whose headers carry the integration metadata (
|
|
111
|
-
* redirect-with-data, `X-Revalidate` keys) and status. The
|
|
112
|
-
* consumed — read `data` and `value` from the delivery,
|
|
23
|
+
* response, whose headers carry the integration metadata (the redirect
|
|
24
|
+
* carrier for redirect-with-data, `X-Revalidate` keys) and status. The
|
|
25
|
+
* body is already consumed — read `data` and `value` from the delivery,
|
|
26
|
+
* not from here.
|
|
113
27
|
*/
|
|
114
28
|
export interface FlightDataContext {
|
|
115
|
-
|
|
116
|
-
|
|
29
|
+
/** The HTTP response the data arrived on (metadata only). */
|
|
30
|
+
response: Response;
|
|
117
31
|
}
|
|
118
|
-
|
|
119
32
|
/**
|
|
120
33
|
* Consumer receiving single-flight data on the client: `data` is the
|
|
121
34
|
* integration-produced payload (opaque to the protocol), `context` carries
|
|
122
|
-
* the envelope metadata.
|
|
123
|
-
*
|
|
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.
|
|
124
40
|
*/
|
|
125
|
-
export type FlightDataConsumer<D = unknown> = (
|
|
126
|
-
data: D,
|
|
127
|
-
context: FlightDataContext
|
|
128
|
-
) => void | Promise<void>;
|
|
129
|
-
|
|
130
|
-
/**
|
|
131
|
-
* Registers the consumer the client transport delivers single-flight data
|
|
132
|
-
* to. Subscribing is the single-flight opt-in: while a consumer is
|
|
133
|
-
* registered the transport sends the request-leg `SINGLE_FLIGHT_HEADER` on
|
|
134
|
-
* non-GET calls (GET reads stay plain and cacheable), asking the server's
|
|
135
|
-
* collection hook to fold data into the response. When a single-flight
|
|
136
|
-
* response arrives, the transport decodes the standardized
|
|
137
|
-
* `{ value, data }` payload, delivers `data` (with the response as
|
|
138
|
-
* envelope context — redirect location, revalidation keys), and returns
|
|
139
|
-
* `value` to the caller as if the call were plain. What to do with the
|
|
140
|
-
* data (seed caches, navigate, ...) is entirely the consumer's business.
|
|
141
|
-
* One active consumer at a time — a later registration replaces the
|
|
142
|
-
* current one; returns an unsubscribe function. With no consumer
|
|
143
|
-
* registered, no header is sent and the server does no collection work;
|
|
144
|
-
* responses an integration opted in manually still pass through to the
|
|
145
|
-
* caller whole, exactly like other integration responses.
|
|
146
|
-
*/
|
|
147
|
-
export function subscribeFlightData<D = unknown>(consumer: FlightDataConsumer<D>): () => void;
|
|
148
|
-
|
|
149
|
-
/**
|
|
150
|
-
* Name of the cookie carrying the outcome of a call made without the client
|
|
151
|
-
* runtime (`"flash"`). A no-JS form post has no way to receive a value —
|
|
152
|
-
* the browser follows the redirect and renders the next page — so the
|
|
153
|
-
* handler stashes the outcome here for the render after it to pick up,
|
|
154
|
-
* which is how a form submitted without JavaScript still shows its result.
|
|
155
|
-
*
|
|
156
|
-
* The name, detection and clearing are isomorphic (integrations read the
|
|
157
|
-
* cookie from code that also ships to the browser); the codec that fills it
|
|
158
|
-
* is server-only and lives behind the server entry.
|
|
159
|
-
*/
|
|
160
|
-
export const FLASH_COOKIE: string;
|
|
161
|
-
|
|
162
|
-
/**
|
|
163
|
-
* Whether a Cookie header carries a flash cookie, readable or not. Cheap
|
|
164
|
-
* enough to call on every render so the clear can be queued before the
|
|
165
|
-
* response headers flush.
|
|
166
|
-
*/
|
|
167
|
-
export function hasFlashCookie(cookieHeader: string | null): boolean;
|
|
168
|
-
|
|
169
|
-
/**
|
|
170
|
-
* The `Set-Cookie` value clearing the flash cookie. The outcome is
|
|
171
|
-
* one-shot: append this as soon as the cookie is detected, whether or not
|
|
172
|
-
* it decodes, so a stale outcome cannot resurface on a later request.
|
|
173
|
-
*/
|
|
174
|
-
export function clearFlashCookie(): string;
|
|
175
|
-
|
|
176
|
-
/**
|
|
177
|
-
* The raw encoded flash payload out of a Cookie header, if present — the
|
|
178
|
-
* codec's own accessor.
|
|
179
|
-
*
|
|
180
|
-
* @internal
|
|
181
|
-
*/
|
|
182
|
-
export function matchFlashCookie(cookieHeader: string | null): string | undefined;
|
|
183
|
-
|
|
184
|
-
/**
|
|
185
|
-
* The currently registered single-flight consumer.
|
|
186
|
-
*
|
|
187
|
-
* Transport building block; not meant for hand-written code.
|
|
188
|
-
* @internal
|
|
189
|
-
*/
|
|
190
|
-
export function getFlightDataConsumer(): FlightDataConsumer | undefined;
|
|
191
|
-
|
|
41
|
+
export type FlightDataConsumer<D = unknown> = (data: D | undefined, context: FlightDataContext) => void | Promise<void>;
|
|
192
42
|
/**
|
|
193
43
|
* The public contract of a server function reference — what a `"use
|
|
194
44
|
* server"` import is at runtime on either side: an async callable plus its
|
|
195
45
|
* build-stable identity.
|
|
196
46
|
*/
|
|
197
47
|
export interface ServerFunction<A extends readonly any[] = any[], T = any> {
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
48
|
+
(...args: A): Promise<T>;
|
|
49
|
+
/** The build-stable function id (stable across the client and server builds). */
|
|
50
|
+
readonly id: string;
|
|
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
|
+
*/
|
|
57
|
+
readonly url: string;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Per-call, invocation-scoped options for `invoke` — things that vary
|
|
61
|
+
* between calls of the SAME function and cannot be declared (`GET`,
|
|
62
|
+
* `withMeta`) or configured (`prepareRequest`). On the server the call is
|
|
63
|
+
* in-process: `signal` still rejects the caller, the transport hints are
|
|
64
|
+
* no-ops (they describe a wire that does not exist).
|
|
65
|
+
*/
|
|
66
|
+
export interface InvokeOptions {
|
|
67
|
+
/**
|
|
68
|
+
* The call's lifecycle. Aborting rejects the call with the signal's
|
|
69
|
+
* reason and cancels the request (firing `request.signal` server-side);
|
|
70
|
+
* a live source's iteration ends across reconnects. When provided, the
|
|
71
|
+
* signal owns the wire — timeouts compose through it
|
|
72
|
+
* (`AbortSignal.timeout`, `AbortSignal.any`).
|
|
73
|
+
*/
|
|
74
|
+
signal?: AbortSignal;
|
|
75
|
+
/**
|
|
76
|
+
* Lets the request outlive the page — fire-and-forget calls during
|
|
77
|
+
* unload (`pagehide`). Maps to fetch's `keepalive`, body-size caps
|
|
78
|
+
* included.
|
|
79
|
+
*/
|
|
80
|
+
keepalive?: boolean;
|
|
81
|
+
/** Fetch priority hint — speculative prefetch vs. interaction fetch. */
|
|
82
|
+
priority?: "high" | "low" | "auto";
|
|
203
83
|
}
|
|
204
|
-
|
|
84
|
+
/**
|
|
85
|
+
* A reference's invocation channel, carried under `SERVER_FUNCTION_INVOKE`:
|
|
86
|
+
* applies one call with per-call options. Declaration wrappers (`GET`,
|
|
87
|
+
* `live`) forward it mechanically — they keep the call mapping 1:1. A
|
|
88
|
+
* wrapper that shares calls (a deduping cache, a multicast channel) opts
|
|
89
|
+
* in deliberately, deciding first what a caller's abort means for shared
|
|
90
|
+
* work — or declines, leaving `invoke` to answer with a directed error.
|
|
91
|
+
* Options arrive already validated — `invoke` admits only
|
|
92
|
+
* invocation-scoped keys.
|
|
93
|
+
*/
|
|
94
|
+
export type ServerFunctionInvoker<A extends readonly any[] = any[], R = any> = (args: A, options?: InvokeOptions) => R;
|
|
205
95
|
/**
|
|
206
96
|
* Declaration-static metadata attached to a server function reference
|
|
207
97
|
* through declaration wrappers (`GET`, `withMeta`). Read it with
|
|
@@ -211,78 +101,19 @@ export interface ServerFunction<A extends readonly any[] = any[], T = any> {
|
|
|
211
101
|
* over earlier ones.
|
|
212
102
|
*/
|
|
213
103
|
export interface ServerFunctionMetadata {
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
104
|
+
/** The declared HTTP method. Undeclared references call over POST. */
|
|
105
|
+
readonly method?: "GET" | "POST";
|
|
106
|
+
/**
|
|
107
|
+
* A human-readable label for the function, seeded by development builds
|
|
108
|
+
* from the compiled function's source name (dev tooling — inspectors,
|
|
109
|
+
* logs). Dev-only: production builds emit no name. Not unique and not an
|
|
110
|
+
* identity key — use `id` for identity. Seeded as a default: an explicit
|
|
111
|
+
* `withMeta` write wins.
|
|
112
|
+
*/
|
|
113
|
+
readonly name?: string;
|
|
114
|
+
/** User-declared transport metadata attached with `withMeta`. */
|
|
115
|
+
readonly [key: string]: unknown;
|
|
226
116
|
}
|
|
227
|
-
|
|
228
|
-
/**
|
|
229
|
-
* Reads a server function reference's declaration metadata — e.g.
|
|
230
|
-
* `getServerFunctionMetadata(fn)?.method === "GET"` detects a `GET(fn)`
|
|
231
|
-
* declaration. Returns undefined when `fn` is not a server function
|
|
232
|
-
* reference; plain references carry an empty metadata object. Works on
|
|
233
|
-
* client proxies and server-side references alike, across duplicated
|
|
234
|
-
* module instances (registered-symbol brand).
|
|
235
|
-
*/
|
|
236
|
-
export function getServerFunctionMetadata(fn: unknown): ServerFunctionMetadata | undefined;
|
|
237
|
-
|
|
238
|
-
/**
|
|
239
|
-
* Whether `fn` is a server function reference (a client proxy or a
|
|
240
|
-
* server-side registered callable). Detection is structural — a
|
|
241
|
-
* registered-symbol metadata brand — so it holds across duplicated module
|
|
242
|
-
* instances and both sides of the directive boundary.
|
|
243
|
-
*/
|
|
244
|
-
export function isServerFunction(fn: unknown): fn is ServerFunction;
|
|
245
|
-
|
|
246
|
-
/**
|
|
247
|
-
* Attaches user-declared transport metadata to a server function reference
|
|
248
|
-
* (client proxy or server-registered callable) and returns the reference.
|
|
249
|
-
* Writes ride the same channel `GET` uses: later writes shallow-merge over
|
|
250
|
-
* earlier ones, and `getServerFunctionMetadata(fn)` reads the merged bag —
|
|
251
|
-
* so `withMeta` composes with `GET` in either order
|
|
252
|
-
* (`GET(withMeta(fn, meta))` ≡ `withMeta(GET(fn), meta)`).
|
|
253
|
-
*
|
|
254
|
-
* The pattern is declare-on-function, react-in-hook: metadata declared
|
|
255
|
-
* here reaches `prepareRequest` as `context.meta`, letting session-dynamic
|
|
256
|
-
* transport policy key on declarations instead of comparing function ids:
|
|
257
|
-
*
|
|
258
|
-
* ```ts
|
|
259
|
-
* export const chargeCard = withMeta(async (amount: number) => {
|
|
260
|
-
* "use server";
|
|
261
|
-
* // ...
|
|
262
|
-
* }, { requiresAuth: true });
|
|
263
|
-
*
|
|
264
|
-
* configureServerFunctionsClient({
|
|
265
|
-
* prepareRequest(init, { meta }) {
|
|
266
|
-
* if (meta?.requiresAuth) {
|
|
267
|
-
* return {
|
|
268
|
-
* ...init,
|
|
269
|
-
* headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
|
|
270
|
-
* };
|
|
271
|
-
* }
|
|
272
|
-
* return init;
|
|
273
|
-
* }
|
|
274
|
-
* });
|
|
275
|
-
* ```
|
|
276
|
-
*/
|
|
277
|
-
export function withMeta<F extends (...args: any[]) => any>(fn: F, meta: ServerFunctionMetadata): F;
|
|
278
|
-
|
|
279
|
-
/**
|
|
280
|
-
* The registered symbol branding server function references with their
|
|
281
|
-
* declaration metadata. Use the typed accessors instead.
|
|
282
|
-
* @internal
|
|
283
|
-
*/
|
|
284
|
-
export const SERVER_FUNCTION_METADATA: unique symbol;
|
|
285
|
-
|
|
286
117
|
/**
|
|
287
118
|
* The transport surface integrations consume through the late-bound RPC
|
|
288
119
|
* seam (server-functions/registry.js) — filled by the transport halves when
|
|
@@ -291,233 +122,343 @@ export const SERVER_FUNCTION_METADATA: unique symbol;
|
|
|
291
122
|
* by routers so they never import the transport/codec statically.
|
|
292
123
|
*/
|
|
293
124
|
export interface ServerFunctionRPC {
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
125
|
+
/**
|
|
126
|
+
* The build's `GET` declaration wrapper (client fetch transport or
|
|
127
|
+
* server in-process dispatch — see the respective entries).
|
|
128
|
+
*/
|
|
129
|
+
GET<A extends readonly any[], R>(fn: (...args: A) => R): ServerFunction<A, Awaited<R>>;
|
|
130
|
+
/**
|
|
131
|
+
* `decodeResponse` bound to the configured codec: decodes a server
|
|
132
|
+
* function response body the transport handed over whole (redirects,
|
|
133
|
+
* revalidation). Resolves undefined for empty bodies and bodies without
|
|
134
|
+
* a recognized encoding (e.g. a raw user Response).
|
|
135
|
+
*/
|
|
136
|
+
decodeResponse<T = unknown>(response: Response): Promise<T | undefined>;
|
|
306
137
|
}
|
|
307
|
-
|
|
308
138
|
/**
|
|
309
|
-
*
|
|
310
|
-
* function reference is created; first write wins.
|
|
139
|
+
* Transport wire detail; not meant for hand-written code.
|
|
311
140
|
* @internal
|
|
312
141
|
*/
|
|
313
|
-
export
|
|
314
|
-
|
|
142
|
+
export type BodyFormatValue = (typeof BodyFormat)[keyof typeof BodyFormat];
|
|
143
|
+
export declare function configureServerFunctionsCodec(codec: JSONCodecOptions | undefined): void;
|
|
144
|
+
export declare function getServerFunctionsCodec(): JSONCodecOptions | undefined;
|
|
315
145
|
/**
|
|
316
|
-
*
|
|
317
|
-
*
|
|
318
|
-
*
|
|
319
|
-
*
|
|
320
|
-
*
|
|
321
|
-
*
|
|
146
|
+
* Validates a flight data source id (both registration halves share the
|
|
147
|
+
* rule): ids travel the `SINGLE_FLIGHT_HEADER` as a comma-separated list,
|
|
148
|
+
* so they cannot be empty or contain commas, and "true" is reserved for
|
|
149
|
+
* the unnamed registration.
|
|
150
|
+
*
|
|
151
|
+
* Transport building block; not meant for hand-written code.
|
|
322
152
|
* @internal
|
|
323
153
|
*/
|
|
324
|
-
export function
|
|
325
|
-
|
|
154
|
+
export declare function assertFlightSource(source: string): void;
|
|
155
|
+
export declare function subscribeFlightData<D = unknown>(consumer: FlightDataConsumer<D>): () => void;
|
|
156
|
+
export declare function subscribeFlightData<D = unknown>(source: string, consumer: FlightDataConsumer<D>): () => void;
|
|
157
|
+
export declare function getFlightDataConsumer(source?: string): FlightDataConsumer | undefined;
|
|
158
|
+
export declare function getFlightDataSourceIds(): string[];
|
|
326
159
|
/**
|
|
327
|
-
*
|
|
328
|
-
* `
|
|
160
|
+
* Whether a mutation response carries integration metadata — the redirect
|
|
161
|
+
* carrier or `X-Revalidate` keys. Metadata is envelope-level (it describes
|
|
162
|
+
* what the mutation did to every cache on the page), so a response carrying
|
|
163
|
+
* it is delivered to every registered flight consumer, folded or not.
|
|
329
164
|
*
|
|
330
|
-
* Transport
|
|
165
|
+
* Transport building block; not meant for hand-written code.
|
|
331
166
|
* @internal
|
|
332
167
|
*/
|
|
333
|
-
export
|
|
334
|
-
|
|
168
|
+
export declare function hasFlightMetadata(response: Response): boolean;
|
|
335
169
|
/**
|
|
336
|
-
*
|
|
170
|
+
* Delivers a decoded single-flight envelope's `data` to the registered
|
|
171
|
+
* consumers — THE delivery path, shared by every transport that can carry
|
|
172
|
+
* the envelope (the plain server-function client and the frames client's
|
|
173
|
+
* flight application), so a mutation reads identically whichever body
|
|
174
|
+
* shape it arrived in.
|
|
337
175
|
*
|
|
338
|
-
*
|
|
176
|
+
* `data` is the keyed envelope, `{ [source]: slice }` (the unnamed
|
|
177
|
+
* registration's slice under the reserved id "true"); `response` is the
|
|
178
|
+
* envelope context, whose `SINGLE_FLIGHT_HEADER` names the folded sources.
|
|
179
|
+
* Each registered consumer receives its own slice, in registration order,
|
|
180
|
+
* awaited sequentially so caches are seeded before the caller sees the
|
|
181
|
+
* value. A consumer whose source was not folded is skipped — unless the
|
|
182
|
+
* response carries integration metadata, in which case it runs with `data`
|
|
183
|
+
* `undefined` to apply the metadata. Consumers are looked up per delivery:
|
|
184
|
+
* an awaited consumer may unsubscribe another (a provider tearing down
|
|
185
|
+
* under a navigation).
|
|
186
|
+
*
|
|
187
|
+
* Transport building block; not meant for hand-written code.
|
|
339
188
|
* @internal
|
|
340
189
|
*/
|
|
341
|
-
export
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
190
|
+
export declare function deliverFlightData(response: Response, data: unknown): Promise<void>;
|
|
191
|
+
export declare function frameAddress(id: string, args?: readonly unknown[]): string;
|
|
192
|
+
export declare function serverFunctionAddress(endpoint: string, id: string): string;
|
|
193
|
+
export declare function serverFunctionDataAddress(endpoint: string, id: string): string;
|
|
194
|
+
export declare function serverFunctionLiveAddress(endpoint: string, id: string): string;
|
|
195
|
+
export declare function parseServerFunctionAddress(pathname: string, endpoint: string): {
|
|
196
|
+
id: string;
|
|
197
|
+
data: boolean;
|
|
198
|
+
live: boolean;
|
|
199
|
+
} | null;
|
|
200
|
+
/**
|
|
201
|
+
* The longest url a `GET()` call goes out as. Longer, the call dispatches
|
|
202
|
+
* over POST instead — a cache miss rather than a 414 from whichever proxy in
|
|
203
|
+
* the chain draws the line first — so no url describes it (`serverFunctionUrl`
|
|
204
|
+
* refuses to render one).
|
|
348
205
|
* @internal
|
|
349
206
|
*/
|
|
350
|
-
export const
|
|
351
|
-
readonly Serialized: "0";
|
|
352
|
-
readonly String: "1";
|
|
353
|
-
readonly FormData: "2";
|
|
354
|
-
readonly URLSearchParams: "3";
|
|
355
|
-
readonly Blob: "4";
|
|
356
|
-
readonly File: "5";
|
|
357
|
-
readonly ArrayBuffer: "6";
|
|
358
|
-
readonly Uint8Array: "7";
|
|
359
|
-
/**
|
|
360
|
-
* Plain `JSON.stringify` — the fast path for JSON-safe payloads on both
|
|
361
|
-
* legs: argument lists on the request, results on the response.
|
|
362
|
-
*/
|
|
363
|
-
readonly Json: "8";
|
|
364
|
-
};
|
|
365
|
-
|
|
207
|
+
export declare const MAX_GET_URL_LENGTH = 2000;
|
|
366
208
|
/**
|
|
367
|
-
*
|
|
209
|
+
* Body of both entries' `serverFunctionActionUrl`: the plain-HTTP address of
|
|
210
|
+
* a function, `<endpoint>/<id>[?args=...]`.
|
|
368
211
|
* @internal
|
|
369
212
|
*/
|
|
370
|
-
export
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
*
|
|
374
|
-
*
|
|
375
|
-
*
|
|
376
|
-
*
|
|
377
|
-
*
|
|
378
|
-
*
|
|
379
|
-
*
|
|
213
|
+
export declare function serverFunctionActionUrlFor(endpoint: string, target: ServerFunction | string, boundArgs: readonly unknown[]): string;
|
|
214
|
+
/**
|
|
215
|
+
* Body of both entries' `serverFunctionUrl`: the url a `GET()` reference's
|
|
216
|
+
* own call requests — `<endpoint>/data/<id>[?args=...]`, or for a live
|
|
217
|
+
* reference `<endpoint>/live/<id>[?args=...]` — built the way the transport
|
|
218
|
+
* builds it (JSON arguments in `args`; see `GET`'s client half) so a fetch
|
|
219
|
+
* of it is the call. For a live reference that call is a standing event
|
|
220
|
+
* stream: the url is for fetching by hand (`curl -N`), not for a preload
|
|
221
|
+
* or prefetch, which would open a stream nothing reads. Refuses — rather
|
|
222
|
+
* than answering with an address nothing would request — when the
|
|
223
|
+
* reference is not a declared read (the default transport POSTs, and a
|
|
224
|
+
* POST is not described by its url), when the arguments need the codec
|
|
225
|
+
* (the transport encodes those asynchronously, and a url rendered as a
|
|
226
|
+
* value cannot wait), and when the url would be long enough for the call
|
|
227
|
+
* to fall back to POST.
|
|
228
|
+
* @internal
|
|
380
229
|
*/
|
|
381
|
-
export function
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
*
|
|
385
|
-
*
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
230
|
+
export declare function serverFunctionUrlFor(endpoint: string, fn: ServerFunction, args: readonly unknown[]): string;
|
|
231
|
+
/**
|
|
232
|
+
* Response header marking a thrown server-function error. The value is the
|
|
233
|
+
* error's message (the structured error itself travels in the body); `"true"`
|
|
234
|
+
* for thrown control-flow responses and non-Error values.
|
|
235
|
+
*/
|
|
236
|
+
export declare const ERROR_HEADER = "X-Server-Function-Error";
|
|
237
|
+
export declare function encodeErrorHeaderValue(value: string): string;
|
|
238
|
+
export declare function decodeErrorHeaderValue(value: string): string;
|
|
239
|
+
/** Header carrying the body format tag (a `BodyFormat` value). */
|
|
240
|
+
export declare const BODY_FORMAT_HEADER = "X-Server-Function-Format";
|
|
241
|
+
/**
|
|
242
|
+
* The position a `live` loop reconnects from, on the request to a live
|
|
243
|
+
* address — the header `EventSource` sends for the same purpose, so a cursor
|
|
244
|
+
* source written against either reader reads one name. Its value is the
|
|
245
|
+
* `id:` of the last event the loop received: a cursor the source named, or
|
|
246
|
+
* the runtime's digest of a value-shaped yield (see `positionDigest`), which
|
|
247
|
+
* lets the server skip re-sending a first emission the client already
|
|
248
|
+
* holds. Rides only on the live address, which is `no-store` and never
|
|
249
|
+
* preloaded — a position must never become an argument, where it would
|
|
250
|
+
* change a read's url identity.
|
|
390
251
|
* @internal
|
|
391
252
|
*/
|
|
392
|
-
export
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
*
|
|
398
|
-
*
|
|
399
|
-
*
|
|
400
|
-
* stream
|
|
401
|
-
*
|
|
402
|
-
*
|
|
253
|
+
export declare const LAST_EVENT_ID_HEADER = "Last-Event-ID";
|
|
254
|
+
/**
|
|
255
|
+
* Per-iteration slot the `live` loop threads through its invoke options
|
|
256
|
+
* (never a public option; process-local symbol): the reader records each
|
|
257
|
+
* event's `id:` in `position`, the next connect sends it back as
|
|
258
|
+
* `Last-Event-ID`, and the loop asks the reference for the LIVE address
|
|
259
|
+
* when this is present. `open` builds the event-stream reader — installed
|
|
260
|
+
* by `live()` itself, so a client that never imports `live` carries no
|
|
261
|
+
* event-stream parser (the `provideRPC` pattern). `connection` is the slot
|
|
262
|
+
* for the connection being made: the decoder sets `connection.ended`, a
|
|
263
|
+
* promise for the body's end carrying how many deferreds were still open
|
|
264
|
+
* (the lifetime signal — death or completion), the error the body ended
|
|
265
|
+
* with, and the sweep the loop may run over the open ones.
|
|
403
266
|
* @internal
|
|
404
267
|
*/
|
|
405
|
-
export
|
|
406
|
-
source: Request | Response,
|
|
407
|
-
codecOptions?: JSONCodecOptions
|
|
408
|
-
): Promise<unknown>;
|
|
409
|
-
|
|
268
|
+
export declare const LIVE_WIRE: unique symbol;
|
|
410
269
|
/**
|
|
411
|
-
*
|
|
412
|
-
*
|
|
413
|
-
*
|
|
414
|
-
* the
|
|
415
|
-
*
|
|
416
|
-
*
|
|
417
|
-
* @internal
|
|
270
|
+
* Header labelling the unknown-id 404: the address was well-formed but its
|
|
271
|
+
* id is not registered in the deployment that answered (#3110). This is the
|
|
272
|
+
* ordinary shape of version skew — a tab holding the previous build's ids
|
|
273
|
+
* across a deploy — and the label is what lets an integration recover
|
|
274
|
+
* (e.g. reload the document) instead of surfacing a generic failed call.
|
|
275
|
+
* Nothing distinguishes it otherwise: a CDN 404 and a skew 404 look alike.
|
|
418
276
|
*/
|
|
419
|
-
export
|
|
420
|
-
value: unknown,
|
|
421
|
-
codecOptions?: JSONCodecOptions
|
|
422
|
-
): ReadableStream<Uint8Array>;
|
|
423
|
-
|
|
277
|
+
export declare const UNKNOWN_HEADER = "X-Server-Function-Unknown";
|
|
424
278
|
/**
|
|
425
|
-
*
|
|
279
|
+
* Header carrying a redirect to scripted callers. fetch FOLLOWS redirect
|
|
280
|
+
* statuses before the transport can read them, so a scripted answer masks
|
|
281
|
+
* the 3xx to 200 and this header carries what the mask erases: the author's
|
|
282
|
+
* status and the target RESOLVED against the request url — exactly the
|
|
283
|
+
* meaning HTTP assigns the `Location` a form post would have received.
|
|
284
|
+
* Value: `<status> <absolute-url>`, decode with `decodeRedirectHeaderValue`.
|
|
426
285
|
*
|
|
427
|
-
*
|
|
428
|
-
*
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
286
|
+
* Carrying the resolved absolute form is the point (#3102, #3107): the
|
|
287
|
+
* reader never guesses navigation strategy from how the author spelled the
|
|
288
|
+
* target — `redirect("/")` and `redirect(new URL("/", url).href)` arrive
|
|
289
|
+
* identical by construction, and same-origin vs cross-origin is a real URL
|
|
290
|
+
* comparison, not a `startsWith("http")` coin toss. `Location` itself never
|
|
291
|
+
* rides a masked answer: on a 200 it has no HTTP meaning, and it collided
|
|
292
|
+
* with authored Locations on statuses that forward (a 201's created-at is
|
|
293
|
+
* data, not navigation).
|
|
294
|
+
*/
|
|
295
|
+
export declare const REDIRECT_HEADER = "X-Server-Function-Redirect";
|
|
296
|
+
/**
|
|
297
|
+
* Decodes a `REDIRECT_HEADER` value into the author's status and the
|
|
298
|
+
* resolved absolute target. Integration plumbing for readers of the header
|
|
299
|
+
* (routers); the wire format is the runtime's own, not a contract to parse
|
|
300
|
+
* by hand.
|
|
301
|
+
*
|
|
302
|
+
* The documented output — a resolved ABSOLUTE http(s) target and a redirect
|
|
303
|
+
* status — is enforced, not assumed (#3175): the absoluteness used to be a
|
|
304
|
+
* property of the server having resolved it, and a hostile or buggy peer
|
|
305
|
+
* could ride a `javascript:` target straight into the `location.href =
|
|
306
|
+
* decoded.url` an integration reasonably writes. A value that does not
|
|
307
|
+
* parse as an absolute http(s) url, or whose status is not one the runtime
|
|
308
|
+
* masks, decodes to `undefined` — the same answer a missing header gives.
|
|
309
|
+
*/
|
|
310
|
+
export declare function decodeRedirectHeaderValue(value: string | null | undefined): {
|
|
311
|
+
status: number;
|
|
312
|
+
url: string;
|
|
313
|
+
} | undefined;
|
|
314
|
+
/**
|
|
315
|
+
* Header driving the single-flight protocol on both legs: on the request it
|
|
316
|
+
* opts the call into flight-data collection (the integration sends it on
|
|
317
|
+
* calls whose response should fold in data), on the response it marks a
|
|
318
|
+
* body carrying the standardized `{ value, data }` payload. How the data
|
|
319
|
+
* is produced (and what it means) is entirely the integration's business —
|
|
320
|
+
* core only owns the wire shape and the delivery.
|
|
321
|
+
*/
|
|
322
|
+
export declare const SINGLE_FLIGHT_HEADER = "X-Single-Flight";
|
|
323
|
+
/** FormData key used when a lone File is sent as the argument. */
|
|
324
|
+
export declare const FILE_FORM_KEY = "__server_function_file__";
|
|
325
|
+
export declare const BodyFormat: {
|
|
326
|
+
Serialized: string;
|
|
327
|
+
String: string;
|
|
328
|
+
FormData: string;
|
|
329
|
+
URLSearchParams: string;
|
|
330
|
+
Blob: string;
|
|
331
|
+
File: string;
|
|
332
|
+
ArrayBuffer: string;
|
|
333
|
+
Uint8Array: string;
|
|
334
|
+
/**
|
|
335
|
+
* Plain `JSON.stringify` — the fast path for JSON-safe payloads on both
|
|
336
|
+
* legs: argument lists on the request, results (single-flight envelopes
|
|
337
|
+
* included) on the response.
|
|
338
|
+
*/
|
|
339
|
+
Json: string;
|
|
340
|
+
/**
|
|
341
|
+
* No body at all — a function that returned nothing. It marks the response
|
|
342
|
+
* as one the runtime encoded, which separates a void result with a status
|
|
343
|
+
* on it from a refusal answered by something else. Decoding falls through
|
|
344
|
+
* to `undefined`, which is what a peer predating the tag reads too.
|
|
345
|
+
*/
|
|
346
|
+
Void: string;
|
|
347
|
+
};
|
|
348
|
+
export declare function isJSONSafe(value: unknown): boolean;
|
|
349
|
+
export declare function getHeadersAndBody(body: unknown): {
|
|
350
|
+
headers?: Record<string, string>;
|
|
351
|
+
body: BodyInit;
|
|
352
|
+
} | undefined;
|
|
353
|
+
export declare function extractBody(source: Request | Response, codecOptions?: JSONCodecOptions, wire?: unknown): Promise<unknown>;
|
|
354
|
+
export declare function createChunk(data: string): Uint8Array;
|
|
355
|
+
export declare class ChunkReader {
|
|
356
|
+
constructor(stream: any);
|
|
357
|
+
readChunk(): Promise<void>;
|
|
358
|
+
next(): Promise<{
|
|
359
|
+
done: boolean;
|
|
360
|
+
value: string;
|
|
361
|
+
}>;
|
|
362
|
+
drain(interpret: any): Promise<void>;
|
|
363
|
+
/** End the read: the body is cancelled through the lock this reader
|
|
364
|
+
* holds, and a pending `next()` resolves done. */
|
|
365
|
+
cancel(reason: any): any;
|
|
366
|
+
}
|
|
432
367
|
/**
|
|
433
|
-
*
|
|
434
|
-
*
|
|
435
|
-
*
|
|
368
|
+
* Frame one payload as a server-sent event — the framing a live address
|
|
369
|
+
* answers in. The same codec payloads `createChunk` frames ride one per
|
|
370
|
+
* event so buffering middleboxes, trained on `text/event-stream`, pass them
|
|
371
|
+
* through unbuffered; `id` (when given) rides as the event's `id:` field,
|
|
372
|
+
* which is what a reconnecting loop echoes back as `Last-Event-ID`.
|
|
373
|
+
*
|
|
374
|
+
* Payloads are `JSON.stringify` output and so carry no raw CR/LF, but the
|
|
375
|
+
* split is done regardless: a payload IS one `data:` line per line, and
|
|
376
|
+
* the reader joins them back with `\n`, so the framing is correct for any
|
|
377
|
+
* string rather than for the strings it happens to see.
|
|
436
378
|
*
|
|
437
|
-
* Transport
|
|
379
|
+
* Transport wire detail; not meant for hand-written code.
|
|
438
380
|
* @internal
|
|
439
381
|
*/
|
|
440
|
-
export function
|
|
441
|
-
source: Request | Response,
|
|
442
|
-
codecOptions?: JSONCodecOptions
|
|
443
|
-
): Promise<T>;
|
|
444
|
-
|
|
382
|
+
export declare function createEventChunk(data: string, id?: string): Uint8Array;
|
|
445
383
|
/**
|
|
446
|
-
*
|
|
447
|
-
*
|
|
448
|
-
*
|
|
384
|
+
* The heartbeat a live response writes while idle: an event-stream comment,
|
|
385
|
+
* invisible to the reader, that keeps proxies with idle timeouts from
|
|
386
|
+
* closing a connection that is merely waiting.
|
|
449
387
|
* @internal
|
|
450
388
|
*/
|
|
451
|
-
export
|
|
452
|
-
text: string,
|
|
453
|
-
codecOptions?: JSONCodecOptions
|
|
454
|
-
): Promise<T>;
|
|
455
|
-
|
|
389
|
+
export declare const EVENT_STREAM_HEARTBEAT: Uint8Array<ArrayBuffer>;
|
|
456
390
|
/**
|
|
457
|
-
*
|
|
458
|
-
*
|
|
459
|
-
*
|
|
460
|
-
* payloads — to recover the structured value inside. Resolves undefined for
|
|
461
|
-
* empty bodies and bodies without a recognized encoding (e.g. a raw user
|
|
462
|
-
* Response). Renderer- and platform-neutral: safe to use from universal
|
|
463
|
-
* code.
|
|
464
|
-
*
|
|
465
|
-
* @param response the transport response; its body is read from a clone,
|
|
466
|
-
* so the original stays readable
|
|
467
|
-
* @param codecOptions overrides the configured codec for this call
|
|
391
|
+
* Whether a Request/Response body is framed as an event stream (by content
|
|
392
|
+
* type — the framing a live address answers in).
|
|
393
|
+
* @internal
|
|
468
394
|
*/
|
|
469
|
-
export function
|
|
470
|
-
response: Response,
|
|
471
|
-
codecOptions?: JSONCodecOptions
|
|
472
|
-
): Promise<T | undefined>;
|
|
473
|
-
|
|
395
|
+
export declare function isEventStream(source: Request | Response): boolean;
|
|
474
396
|
/**
|
|
475
|
-
*
|
|
476
|
-
*
|
|
477
|
-
*
|
|
478
|
-
*
|
|
479
|
-
*
|
|
480
|
-
*
|
|
397
|
+
* The reader for what `createEventChunk` writes — `ChunkReader`'s
|
|
398
|
+
* counterpart for the event-stream framing, same `next()`/`drain()` shape
|
|
399
|
+
* so `deserializeStream` runs unchanged over either. Only `data:` and `id:`
|
|
400
|
+
* are read; `event:`, `retry:` and unknown fields are ignored (the
|
|
401
|
+
* transport carries one kind of event and owns its own backoff), comments
|
|
402
|
+
* are heartbeats. An event dispatches on its blank line; an event the body
|
|
403
|
+
* ends inside is discarded, as the spec says, and the drain's end-of-body
|
|
404
|
+
* sweep fails whatever it left open.
|
|
405
|
+
*
|
|
406
|
+
* Each dispatched event's `id:` is recorded on `wire.position` — the value
|
|
407
|
+
* the loop sends as `Last-Event-ID` on its next connect.
|
|
481
408
|
*
|
|
482
|
-
*
|
|
409
|
+
* Transport wire detail; not meant for hand-written code.
|
|
483
410
|
* @internal
|
|
484
411
|
*/
|
|
485
|
-
export
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
):
|
|
489
|
-
|
|
412
|
+
export declare class EventStreamReader {
|
|
413
|
+
constructor(stream: any, wire: any);
|
|
414
|
+
read(): Promise<void>;
|
|
415
|
+
takeLine(): any;
|
|
416
|
+
next(): Promise<{
|
|
417
|
+
done: boolean;
|
|
418
|
+
value: any;
|
|
419
|
+
}>;
|
|
420
|
+
drain(interpret: any): Promise<void>;
|
|
421
|
+
/** End the read (see `ChunkReader.cancel`). */
|
|
422
|
+
cancel(reason: any): any;
|
|
423
|
+
}
|
|
490
424
|
/**
|
|
491
|
-
*
|
|
492
|
-
*
|
|
493
|
-
*
|
|
425
|
+
* The runtime's position for a value-shaped yield: a digest of the value's
|
|
426
|
+
* JSON form, carried as the event's `id:` and echoed back on reconnect so
|
|
427
|
+
* the server can skip re-sending a first emission the client already holds
|
|
428
|
+
* (the data-tier analog of a frame's hole digest). Over `JSON.stringify` of
|
|
429
|
+
* the VALUE, not over the codec record that carries it — a record's
|
|
430
|
+
* reference ids depend on what the stream sent before it, so the same value
|
|
431
|
+
* encodes differently on a fresh connection. `undefined` for a yield that
|
|
432
|
+
* is not JSON-safe: such a yield carries no id and is never skipped.
|
|
494
433
|
*
|
|
495
|
-
*
|
|
434
|
+
* FNV-1a in two 32-bit lanes (a second seed, not a 64-bit arithmetic that
|
|
435
|
+
* JavaScript lacks) → 16 hex characters. Not a security boundary: an equal
|
|
436
|
+
* digest only elides a re-send the client would have discarded as equal.
|
|
496
437
|
* @internal
|
|
497
438
|
*/
|
|
498
|
-
export function
|
|
499
|
-
|
|
439
|
+
export declare function positionDigest(value: unknown): string | undefined;
|
|
500
440
|
/**
|
|
501
|
-
*
|
|
502
|
-
*
|
|
503
|
-
*
|
|
504
|
-
*
|
|
505
|
-
*
|
|
441
|
+
* The digest behind `positionDigest`, over a string as-is: the frame tier's
|
|
442
|
+
* hole/fragment digest (RFC 11 §9.5, Hole hashes) — minted by the server
|
|
443
|
+
* over the html it emits, stored by the client per hole, echoed back on a
|
|
444
|
+
* resume as the have-list. Same lanes, same width, same non-goal (a
|
|
445
|
+
* collision elides a re-send, nothing more).
|
|
506
446
|
* @internal
|
|
507
447
|
*/
|
|
508
|
-
export
|
|
509
|
-
constructor(stream: ReadableStream<Uint8Array>);
|
|
510
|
-
next(): Promise<{ done: boolean; value: string | undefined }>;
|
|
511
|
-
}
|
|
512
|
-
|
|
448
|
+
export declare function textDigest(text: string): string;
|
|
513
449
|
/**
|
|
514
|
-
*
|
|
515
|
-
*
|
|
516
|
-
* Both peers derive it independently — the server names flight regions with
|
|
517
|
-
* it, the client routes them by it — so it must stay deterministic across
|
|
518
|
-
* realms and releases.
|
|
519
|
-
*
|
|
450
|
+
* Encodes a terminal error-trailer frame payload. The value is expected to
|
|
451
|
+
* be already sanitized by the caller; only `name` and `message` travel.
|
|
520
452
|
* Transport wire detail; not meant for hand-written code.
|
|
521
453
|
* @internal
|
|
522
454
|
*/
|
|
523
|
-
export function
|
|
455
|
+
export declare function encodeErrorTrailer(error: unknown): string;
|
|
456
|
+
export declare function serializeStream(value: unknown, codecOptions?: JSONCodecOptions): ReadableStream<Uint8Array>;
|
|
457
|
+
export declare function serializeString(value: unknown, codecOptions?: JSONCodecOptions): Promise<string>;
|
|
458
|
+
export declare function deserializeStream<T = unknown>(source: Request | Response, codecOptions?: JSONCodecOptions, wire?: unknown): Promise<T>;
|
|
459
|
+
export declare function deserializeString<T = unknown>(text: string, codecOptions?: JSONCodecOptions): Promise<T>;
|
|
460
|
+
export declare function decodeResponse<T = unknown>(response: Response, codecOptions?: JSONCodecOptions): Promise<T | undefined>;
|
|
461
|
+
export declare function decodeResponsePayload<T = unknown, D = unknown>(response: Response, codecOptions?: JSONCodecOptions): Promise<{
|
|
462
|
+
value: T | undefined;
|
|
463
|
+
flightData?: D;
|
|
464
|
+
}>;
|