@workerstack/clients 1.0.0-rc.30 → 1.0.0-rc.31
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 +175 -21
- package/bin/clients.js +5 -6
- package/bin/installgen.js +5 -9
- package/dist/cli.js +3 -1
- package/dist/emit/csharp/sdk-method.d.ts +18 -1
- package/dist/emit/csharp/sdk-method.js +14 -3
- package/dist/emit/csharp/sdk.js +4 -1
- package/dist/emit/go/sdk-method.d.ts +9 -0
- package/dist/emit/go/sdk-method.js +10 -1
- package/dist/emit/go/sdk.js +4 -3
- package/dist/emit/java/sdk-client.js +1 -0
- package/dist/emit/java/sdk-op.d.ts +6 -1
- package/dist/emit/java/sdk-op.js +15 -3
- package/dist/emit/java/sdk.js +7 -1
- package/dist/emit/python/sdk-method.d.ts +11 -0
- package/dist/emit/python/sdk-method.js +15 -0
- package/dist/emit/python/sdk.js +5 -1
- package/dist/emit/rust/sdk-method.d.ts +12 -1
- package/dist/emit/rust/sdk-method.js +10 -2
- package/dist/emit/rust/sdk.js +4 -1
- package/dist/emit/ts/http.d.ts +8 -0
- package/dist/emit/ts/http.js +48 -3
- package/dist/emit/ts/package.js +1 -0
- package/dist/emit/ts/sdk-types-preamble.js +10 -2
- package/dist/emit/ts/sdk-types.d.ts +0 -5
- package/dist/emit/ts/sdk-types.js +52 -8
- package/dist/emit/ts/sdk.d.ts +3 -1
- package/dist/emit/ts/sdk.js +40 -8
- package/dist/emit/ts/service-map.d.ts +5 -0
- package/dist/emit/ts/service-map.js +10 -1
- package/dist/emit/ts/single-flight-text.d.ts +3 -0
- package/dist/emit/ts/single-flight-text.js +38 -0
- package/dist/emit/ts/tanstack-query.d.ts +3 -2
- package/dist/emit/ts/tanstack-query.js +54 -29
- package/dist/gen/process.js +2 -1
- package/dist/gen/switch-on.constants.d.ts +2 -0
- package/dist/gen/switch-on.constants.js +2 -0
- package/dist/gen/targets.d.ts +4 -3
- package/dist/gen/targets.js +4 -3
- package/dist/ir/invalidate-reads.d.ts +17 -0
- package/dist/ir/invalidate-reads.js +104 -0
- package/dist/ir/load.d.ts +10 -0
- package/dist/ir/load.js +62 -14
- package/dist/ir/read-method.constants.d.ts +2 -0
- package/dist/ir/read-method.constants.js +2 -0
- package/dist/release/load.js +1 -1
- package/dist/runtime/csharp/Config.cs +9 -1
- package/dist/runtime/csharp/Exchange.cs +56 -4
- package/dist/runtime/csharp/Hooks.cs +9 -0
- package/dist/runtime/csharp/Operation.cs +6 -1
- package/dist/runtime/csharp/WsDial.cs +3 -1
- package/dist/runtime/go/config.go +5 -0
- package/dist/runtime/go/hooks.go +70 -0
- package/dist/runtime/go/request.go +6 -2
- package/dist/runtime/go/stream.go +4 -1
- package/dist/runtime/go/ws.go +3 -1
- package/dist/runtime/java/ClientConfig.java +11 -0
- package/dist/runtime/java/Flight.java +2 -12
- package/dist/runtime/java/Hooks.java +45 -0
- package/dist/runtime/java/InvalidateEvent.java +10 -0
- package/dist/runtime/java/InvalidateHook.java +12 -0
- package/dist/runtime/java/InvalidateTarget.java +7 -0
- package/dist/runtime/java/Operation.java +23 -3
- package/dist/runtime/java/Realtime.java +3 -1
- package/dist/runtime/java/WsDial.java +3 -0
- package/dist/runtime/python/config.py +8 -2
- package/dist/runtime/python/exchange.py +3 -1
- package/dist/runtime/python/hooks.py +110 -5
- package/dist/runtime/python/operation.py +2 -0
- package/dist/runtime/python/send_async.py +14 -2
- package/dist/runtime/python/send_sync.py +4 -2
- package/dist/runtime/python/ws.py +5 -1
- package/dist/runtime/rust/config.rs +6 -1
- package/dist/runtime/rust/exchange.rs +15 -3
- package/dist/runtime/rust/hooks.rs +127 -2
- package/dist/runtime/rust/log.rs +11 -3
- package/dist/runtime/rust/request.rs +17 -0
- package/dist/runtime/rust/ws.rs +9 -1
- package/dist/runtime/ts/config.ts +69 -0
- package/dist/runtime/ts/http.ts +12 -10
- package/dist/runtime/ts/request.ts +2 -0
- package/dist/runtime/ts/response.ts +7 -0
- package/dist/runtime/ts/sdk-invalidate.ts +82 -0
- package/dist/runtime/ts/sdk-single-flight.constants.ts +25 -0
- package/dist/runtime/ts/sdk-single-flight.ts +203 -0
- package/dist/runtime/ts/sdk-sse.ts +5 -1
- package/dist/runtime/ts/sdk-ws.ts +9 -3
- package/dist/runtime/ts/sdk.ts +55 -31
- package/dist/runtime/ts/single-flight-batch.ts +184 -0
- package/dist/runtime/ts/single-flight-body.ts +59 -0
- package/dist/runtime/ts/single-flight-run.ts +160 -0
- package/dist/runtime/ts/single-flight.constants.ts +31 -0
- package/dist/runtime/ts/single-flight.ts +158 -0
- package/dist/runtime/ts-tanstack-query/invalidate.ts +96 -92
- package/dist/runtime/ts-tanstack-query/query.ts +140 -168
- package/package.json +10 -18
- package/references/INDEX.md +31 -0
- package/references/cli.md +33 -0
- package/references/configuring.md +29 -0
- package/references/documentation.md +15 -0
- package/references/errors.md +23 -0
- package/references/flags.md +104 -0
- package/references/gates.md +46 -0
- package/references/generate.md +29 -0
- package/references/install-scripts.md +28 -0
- package/references/install.md +38 -0
- package/references/license.md +8 -0
- package/references/mcp.md +76 -0
- package/references/output.md +45 -0
- package/references/overview.md +14 -0
- package/references/release-tooling.md +34 -0
- package/references/release.md +305 -0
- package/references/sdks.md +393 -0
- package/references/start.md +22 -0
- package/references/tdd.md +16 -0
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
import type { FreshReads, SingleFlightBatch, SingleFlightConfig } from "./config.ts"
|
|
2
|
+
import { ClientError, DecodeError } from "./error.ts"
|
|
3
|
+
import { AUTH_TOKEN, type HTTPClient, REFRESH_AUTH } from "./http.ts"
|
|
4
|
+
import { isJsonMediaType, parseMediaType } from "./media-type.ts"
|
|
5
|
+
import { requestSignal } from "./request.ts"
|
|
6
|
+
import type { Sent } from "./response.ts"
|
|
7
|
+
import { targetsOf } from "./sdk-invalidate.ts"
|
|
8
|
+
import {
|
|
9
|
+
BATCH_VERSION,
|
|
10
|
+
DEFAULT_FLIGHT_PATH,
|
|
11
|
+
DEFAULT_MAX_READS,
|
|
12
|
+
MAX_WRITE_STATUS,
|
|
13
|
+
MIN_WRITE_STATUS,
|
|
14
|
+
NO_BODY_STATUSES,
|
|
15
|
+
REFUSED,
|
|
16
|
+
REFUSED_STATUS,
|
|
17
|
+
UNAUTHORIZED_STATUS,
|
|
18
|
+
WRITE_METHODS,
|
|
19
|
+
} from "./sdk-single-flight.constants.ts"
|
|
20
|
+
import type { CallInput, ServiceEntry } from "./sdk.ts"
|
|
21
|
+
|
|
22
|
+
/** The input a call keeps to itself: a write sent with any goes direct. */
|
|
23
|
+
const DIRECT_KEYS = ["baseURL", "body", "cookies", "form", "headers"] as const
|
|
24
|
+
|
|
25
|
+
/** One eligible write: its config and the batch it sends. */
|
|
26
|
+
export type Flight = { batch: SingleFlightBatch; config: SingleFlightConfig }
|
|
27
|
+
|
|
28
|
+
/** The client a write is sent by: its single-flight config, its HTTP client and its dispose signal. */
|
|
29
|
+
export type FlightClient = { config: SingleFlightConfig | undefined; disposal: AbortSignal; http: HTTPClient }
|
|
30
|
+
|
|
31
|
+
/** One eligible write as it is sent: the client, the batch and the call's input. */
|
|
32
|
+
type FlightCall = { disposal: AbortSignal; flight: Flight; http: HTTPClient; input: CallInput }
|
|
33
|
+
|
|
34
|
+
/** What a batch brought back: the write's answer, rebuilt, and the reads, by id. */
|
|
35
|
+
export type Flown = { fresh: FreshReads; sent: Sent }
|
|
36
|
+
|
|
37
|
+
/** Whether `entry` never goes in a batch under `config`: no REST JSON write with reads, or one it excludes. */
|
|
38
|
+
function isDirectEntry(config: SingleFlightConfig, entry: ServiceEntry): boolean {
|
|
39
|
+
if (!WRITE_METHODS.includes(entry.method) || entry.accept !== undefined || entry.call !== undefined) return true
|
|
40
|
+
return entry.empty === true || config.exclude?.includes(entry.id) === true || (entry.reads?.length ?? 0) === 0
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Whether a call with `input` goes direct: it opts out, wants the raw answer, or sets what a batch cannot carry. */
|
|
44
|
+
function isDirectInput(input: CallInput): boolean {
|
|
45
|
+
if (input.singleFlight === false || input.raw === true) return true
|
|
46
|
+
return DIRECT_KEYS.some((key) => input[key] !== undefined)
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** The write's input as a batch carries it: only what the handler takes, an idempotent write's key included. */
|
|
50
|
+
function batchInput(entry: ServiceEntry, input: CallInput): SingleFlightBatch["input"] {
|
|
51
|
+
const out: SingleFlightBatch["input"] = {}
|
|
52
|
+
if (input.params !== undefined) out.params = input.params
|
|
53
|
+
if (input.search !== undefined) out.search = input.search
|
|
54
|
+
if (input.json !== undefined) out.json = input.json
|
|
55
|
+
if (entry.idempotent === true && input.idempotencyKey !== undefined) out.idempotencyKey = input.idempotencyKey
|
|
56
|
+
return out
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** The batch `entry` called with `input` sends under `config`, or none when it goes direct. */
|
|
60
|
+
function flightOf(config: SingleFlightConfig | undefined, entry: ServiceEntry, input: CallInput): Flight | undefined {
|
|
61
|
+
if (config === undefined || isDirectEntry(config, entry) || isDirectInput(input)) return undefined
|
|
62
|
+
const picked = config.select(targetsOf(entry.reads ?? [], input.params))
|
|
63
|
+
const reads = picked.slice(0, Math.max(config.maxReads ?? DEFAULT_MAX_READS, 0))
|
|
64
|
+
if (reads.length === 0) return undefined
|
|
65
|
+
return { batch: { input: batchInput(entry, input), op: entry.id, reads, v: BATCH_VERSION }, config }
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Whether `value` is an object whose keys can be read. */
|
|
69
|
+
function isObject(value: unknown): value is object {
|
|
70
|
+
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** Whether `value` is text. */
|
|
74
|
+
function isString(value: unknown): value is string {
|
|
75
|
+
return typeof value === "string"
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Whether `body` is a handler's refusal problem. */
|
|
79
|
+
function isRefusal(body: unknown): body is { type: typeof REFUSED } {
|
|
80
|
+
return isObject(body) && "type" in body && body.type === REFUSED
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** `promise`, or the abort of `signal` first. */
|
|
84
|
+
function raced<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
|
|
85
|
+
if (signal === undefined) return promise
|
|
86
|
+
return new Promise<T>((resolve, reject) => {
|
|
87
|
+
function onAbort(): void {
|
|
88
|
+
reject(signal?.reason)
|
|
89
|
+
}
|
|
90
|
+
signal.addEventListener("abort", onAbort, { once: true })
|
|
91
|
+
promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort))
|
|
92
|
+
})
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** What `send` resolves: what the batch got back, a stand-in Response its read errors carry. */
|
|
96
|
+
async function sentBy(send: NonNullable<SingleFlightConfig["send"]>, call: FlightCall) {
|
|
97
|
+
const { done, signal } = requestSignal([call.input.signal, call.disposal], call.input.timeout)
|
|
98
|
+
try {
|
|
99
|
+
signal?.throwIfAborted()
|
|
100
|
+
return { response: new Response(null), value: await raced(send(call.flight.batch), signal) }
|
|
101
|
+
} finally {
|
|
102
|
+
done()
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** What one sending of the batch got back, and its response; undefined for a refusal. */
|
|
107
|
+
async function sendOnce(call: FlightCall) {
|
|
108
|
+
const { config, batch } = call.flight
|
|
109
|
+
if (config.send !== undefined) return sentBy(config.send, call)
|
|
110
|
+
const opts = { json: batch, signal: call.input.signal, timeout: call.input.timeout }
|
|
111
|
+
try {
|
|
112
|
+
const answer = await call.http.requestOperation({ method: "POST", opts, path: config.path ?? DEFAULT_FLIGHT_PATH })
|
|
113
|
+
return { response: answer.response, value: answer.data }
|
|
114
|
+
} catch (e) {
|
|
115
|
+
if (e instanceof ClientError && e.status === REFUSED_STATUS && isRefusal(e.body)) return undefined
|
|
116
|
+
throw e
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** The write's answer of an envelope. */
|
|
121
|
+
type EnvelopeWrite = { body: unknown; headers: Readonly<Record<string, string>>; status: number }
|
|
122
|
+
|
|
123
|
+
/** An envelope as the client reads it: the write's answer and each read's entry, still unread. */
|
|
124
|
+
type Envelope = { reads: readonly unknown[]; write: EnvelopeWrite }
|
|
125
|
+
|
|
126
|
+
/** One read's entry that came back with data. */
|
|
127
|
+
type AnsweredRead = { data: unknown; id: string }
|
|
128
|
+
|
|
129
|
+
/** Whether `value` is the write's answer: a status 200 to 599, headers of strings, and a body. */
|
|
130
|
+
function isWrite(value: unknown): value is EnvelopeWrite {
|
|
131
|
+
if (!isObject(value) || !("body" in value) || !("headers" in value) || !("status" in value)) return false
|
|
132
|
+
const { headers, status } = value
|
|
133
|
+
if (typeof status !== "number" || !Number.isInteger(status)) return false
|
|
134
|
+
if (status < MIN_WRITE_STATUS || status > MAX_WRITE_STATUS) return false
|
|
135
|
+
return isObject(headers) && Object.values(headers).every(isString)
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** Whether `value` is an envelope of the one batch version. */
|
|
139
|
+
function isEnvelope(value: unknown): value is Envelope {
|
|
140
|
+
if (!isObject(value) || !("v" in value) || !("write" in value) || !("reads" in value)) return false
|
|
141
|
+
return value.v === BATCH_VERSION && isWrite(value.write) && Array.isArray(value.reads)
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Whether `value` is a read's entry that came back with data. */
|
|
145
|
+
function isAnswered(value: unknown): value is AnsweredRead {
|
|
146
|
+
return isObject(value) && "data" in value && "id" in value && isString(value.id)
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/** What came back as an envelope; a DecodeError, carrying `response`, when it is none. */
|
|
150
|
+
function envelopeOf(got: { response: Response; value: unknown }): Envelope {
|
|
151
|
+
if (isEnvelope(got.value)) return got.value
|
|
152
|
+
const { response } = got
|
|
153
|
+
const message = "Single-flight answer is no version 1 envelope"
|
|
154
|
+
throw new DecodeError({ body: null, message, response, status: response.status })
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** The reads `flight` asked for that `envelope` brought back by id, and those it did not. */
|
|
158
|
+
function freshOf(envelope: Envelope, flight: Flight): FreshReads {
|
|
159
|
+
const data = new Map<string, unknown>()
|
|
160
|
+
for (const read of envelope.reads) if (isAnswered(read)) data.set(read.id, read.data)
|
|
161
|
+
const failed = new Set(flight.batch.reads.map((read) => read.id).filter((id) => !data.has(id)))
|
|
162
|
+
return { data, failed }
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** The write's answer as the Response a direct call would have read. */
|
|
166
|
+
function responseOf(write: EnvelopeWrite): Response {
|
|
167
|
+
const isJson = isJsonMediaType(parseMediaType(write.headers["content-type"]))
|
|
168
|
+
let body: string | null = null
|
|
169
|
+
if (!NO_BODY_STATUSES.includes(write.status) && write.body !== null)
|
|
170
|
+
body = isString(write.body) && !isJson ? write.body : JSON.stringify(write.body)
|
|
171
|
+
return new Response(body, { headers: write.headers, status: write.status })
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/** What a batch brought back, the write's answer as a Sent with nothing to release. */
|
|
175
|
+
function flownOf(envelope: Envelope, flight: Flight): Flown {
|
|
176
|
+
const response = responseOf(envelope.write)
|
|
177
|
+
const sent = {
|
|
178
|
+
done: () => undefined,
|
|
179
|
+
exemptFromTimeout: () => undefined,
|
|
180
|
+
failed: (cause: unknown) => cause,
|
|
181
|
+
response,
|
|
182
|
+
}
|
|
183
|
+
return { fresh: freshOf(envelope, flight), sent }
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Send `entry` called with `input` in a single-flight batch when it is eligible, and read its envelope: the write's
|
|
188
|
+
* answer and the reads brought back. Undefined when the call goes direct, or the handler refused the batch. A write's
|
|
189
|
+
* 401 refreshes the token once, as a direct call's does, and sends the batch again.
|
|
190
|
+
*/
|
|
191
|
+
export async function fly(client: FlightClient, entry: ServiceEntry, input: CallInput): Promise<Flown | undefined> {
|
|
192
|
+
const flight = flightOf(client.config, entry, input)
|
|
193
|
+
if (flight === undefined) return undefined
|
|
194
|
+
const call = { disposal: client.disposal, flight, http: client.http, input }
|
|
195
|
+
const token = client.http[AUTH_TOKEN]
|
|
196
|
+
const got = await sendOnce(call)
|
|
197
|
+
if (got === undefined) return undefined
|
|
198
|
+
const envelope = envelopeOf(got)
|
|
199
|
+
if (envelope.write.status !== UNAUTHORIZED_STATUS || !(await client.http[REFRESH_AUTH](token)))
|
|
200
|
+
return flownOf(envelope, flight)
|
|
201
|
+
const again = await sendOnce(call)
|
|
202
|
+
return again === undefined ? undefined : flownOf(envelopeOf(again), flight)
|
|
203
|
+
}
|
|
@@ -43,7 +43,10 @@ function mapEvents(
|
|
|
43
43
|
}
|
|
44
44
|
}
|
|
45
45
|
|
|
46
|
-
/**
|
|
46
|
+
/**
|
|
47
|
+
* An SSE op opened: its stale view for the hooks, and its `x-invalidate` targets marked once the answer is ok, when
|
|
48
|
+
* the `onInvalidate` hooks are called detached: the open is sync, so nothing waits on them.
|
|
49
|
+
*/
|
|
47
50
|
async function open(core: SdkCore, entry: ServiceEntry, input: RequestOptions): Promise<Answer> {
|
|
48
51
|
const opts = optionsFor(entry, input)
|
|
49
52
|
const template = templateOf(entry)
|
|
@@ -58,6 +61,7 @@ async function open(core: SdkCore, entry: ServiceEntry, input: RequestOptions):
|
|
|
58
61
|
}
|
|
59
62
|
const onOpen = () => {
|
|
60
63
|
if (selector !== undefined) core.mark(entry, input.params, selector)
|
|
64
|
+
void core.invalidated(entry, input.params)
|
|
61
65
|
}
|
|
62
66
|
const { data, response } = await openStream(core.http, { meta, method: entry.method, onOpen, opts, path: template })
|
|
63
67
|
return { data: eventsOf(data, entry.sse), response }
|
|
@@ -6,7 +6,10 @@ import { createTypedWebSocket, type TypedWebSocket, wsUrl } from "./ws.ts"
|
|
|
6
6
|
/** A WebSocket call's input: the request's options, the subprotocols, and a resume token. */
|
|
7
7
|
type WsInput = RequestOptions & { protocols?: string | string[]; reconnectToken?: string }
|
|
8
8
|
|
|
9
|
-
/**
|
|
9
|
+
/**
|
|
10
|
+
* A WebSocket op: one socket per call, its `x-invalidate` targets marked once it opens, when the `onInvalidate` hooks
|
|
11
|
+
* are called detached: the `open` listener is sync, so nothing waits on them.
|
|
12
|
+
*/
|
|
10
13
|
export const wsOp: OperationCall =
|
|
11
14
|
(core, entry) =>
|
|
12
15
|
(input: WsInput = {}): TypedWebSocket => {
|
|
@@ -14,9 +17,12 @@ export const wsOp: OperationCall =
|
|
|
14
17
|
if (input.reconnectToken) url.searchParams.append("reconnect_token", input.reconnectToken)
|
|
15
18
|
const { decode, dispatch, encode } = entry
|
|
16
19
|
const socket = createTypedWebSocket(url.toString(), { decode, dispatch, encode, protocols: input.protocols })
|
|
17
|
-
if (entry.
|
|
20
|
+
if (entry.reads?.length) {
|
|
18
21
|
const selector = `WS ${interpolatePath(templateOf(entry), input.params)}`
|
|
19
|
-
socket.on("open", () =>
|
|
22
|
+
socket.on("open", () => {
|
|
23
|
+
core.mark(entry, input.params, selector)
|
|
24
|
+
void core.invalidated(entry, input.params)
|
|
25
|
+
})
|
|
20
26
|
}
|
|
21
27
|
return socket
|
|
22
28
|
}
|
package/dist/runtime/ts/sdk.ts
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
|
-
import type { ClientConfig, RequestMeta } from "./config.ts"
|
|
1
|
+
import type { ClientConfig, FreshReads, RequestMeta, SingleFlightConfig } from "./config.ts"
|
|
2
2
|
import { ClientError, DecodeError } from "./error.ts"
|
|
3
3
|
import { HTTPClient } from "./http.ts"
|
|
4
4
|
import { interpolatePath, PathParamError } from "./path.ts"
|
|
5
5
|
import { newClientRequestId, type RequestOptions } from "./request.ts"
|
|
6
|
-
import { type Answer, resultOf } from "./response.ts"
|
|
6
|
+
import { type Answer, finishRequest, resultOf } from "./response.ts"
|
|
7
|
+
import { runInvalidateHooks, type ServiceRead } from "./sdk-invalidate.ts"
|
|
8
|
+
import { fly } from "./sdk-single-flight.ts"
|
|
7
9
|
import { resolveInvalidationTargets, StaleIndex } from "./stale.ts"
|
|
8
10
|
|
|
9
11
|
/** One operation as the service map holds it: where it goes and how its answer is read. */
|
|
@@ -14,12 +16,16 @@ export type ServiceEntry = {
|
|
|
14
16
|
empty?: boolean
|
|
15
17
|
/** the declared response headers, lower case (A2) */
|
|
16
18
|
headers?: readonly string[]
|
|
19
|
+
/** the operationId: what `onInvalidate` names a write by, whatever member path it is renamed to */
|
|
20
|
+
id: string
|
|
17
21
|
idempotent?: boolean
|
|
18
22
|
invalidate?: readonly string[]
|
|
19
23
|
method: string
|
|
20
24
|
params?: readonly string[]
|
|
21
25
|
/** the OpenAPI path template, `{param}` kept */
|
|
22
26
|
path: string
|
|
27
|
+
/** the reads a successful call makes stale, resolved from `invalidate` at generation */
|
|
28
|
+
reads?: readonly ServiceRead[]
|
|
23
29
|
realtime?: boolean
|
|
24
30
|
/** an event stream; `"json"` when its events carry JSON `data` the client parses, or the names of the events that
|
|
25
31
|
do when the operation names its events (an unnamed one is `message`) */
|
|
@@ -50,7 +56,11 @@ export type InvalidationConfig = {
|
|
|
50
56
|
staleTime: number
|
|
51
57
|
}
|
|
52
58
|
|
|
53
|
-
export type SDKConfig = ClientConfig & {
|
|
59
|
+
export type SDKConfig = ClientConfig & {
|
|
60
|
+
invalidation?: InvalidationConfig
|
|
61
|
+
/** send eligible writes to a single-flight handler with the reads they make stale; see `SingleFlightConfig` */
|
|
62
|
+
singleFlight?: SingleFlightConfig
|
|
63
|
+
}
|
|
54
64
|
|
|
55
65
|
/** What a REST call takes; a stream, WebSocket or realtime operation's own call types its input further. */
|
|
56
66
|
export type CallInput = RequestOptions
|
|
@@ -75,14 +85,15 @@ export function templateOf(entry: ServiceEntry): string {
|
|
|
75
85
|
return entry.wildcard === undefined ? entry.path : entry.path.replace(`{${entry.wildcard}}`, `*${entry.wildcard}`)
|
|
76
86
|
}
|
|
77
87
|
|
|
78
|
-
/**
|
|
79
|
-
function
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
88
|
+
/** `template` filled with `params`; params that cannot form a path throw a status-0 ClientError, no request sent. */
|
|
89
|
+
function pathOf(entry: ServiceEntry, template: string, params: CallInput["params"]): string {
|
|
90
|
+
try {
|
|
91
|
+
return interpolatePath(template, params)
|
|
92
|
+
} catch (e) {
|
|
93
|
+
if (!(e instanceof PathParamError)) throw e
|
|
94
|
+
const message = `${e.message} for ${entry.method} ${entry.path}`
|
|
95
|
+
throw new ClientError({ body: null, message, response: Response.error(), status: 0 })
|
|
96
|
+
}
|
|
86
97
|
}
|
|
87
98
|
|
|
88
99
|
/** The per-call options an entry adds: its `Accept` and an `Idempotency-Key`. */
|
|
@@ -109,13 +120,6 @@ export class SdkCore {
|
|
|
109
120
|
this.#stale = this.#newIndex()
|
|
110
121
|
}
|
|
111
122
|
|
|
112
|
-
#newIndex(): StaleIndex | null {
|
|
113
|
-
const invalidation = this.#config.invalidation
|
|
114
|
-
if (!invalidation || invalidation.staleTime <= 0) return null
|
|
115
|
-
const maxSources = Math.max(invalidation.maxSourcesPerTarget ?? 16, 1)
|
|
116
|
-
return new StaleIndex({ maxEntries: invalidation.staleMaxEntries ?? 1000, maxSources })
|
|
117
|
-
}
|
|
118
|
-
|
|
119
123
|
dispose(): void {
|
|
120
124
|
this.#disposal.abort(new Error("The client was disposed"))
|
|
121
125
|
this.#stale = this.#newIndex()
|
|
@@ -136,33 +140,53 @@ export class SdkCore {
|
|
|
136
140
|
for (const target of resolveInvalidationTargets(entry.invalidate, params)) this.#stale.mark(target, selector, at)
|
|
137
141
|
}
|
|
138
142
|
|
|
139
|
-
/**
|
|
140
|
-
|
|
143
|
+
/** Tell the `onInvalidate` hooks what the successful call `entry` with `params` made stale; it never rejects. */
|
|
144
|
+
invalidated(entry: ServiceEntry, params: RequestOptions["params"], fresh?: FreshReads): Promise<void> {
|
|
145
|
+
const operation = `${entry.method} ${entry.path}`
|
|
146
|
+
return runInvalidateHooks(this.#config, { by: entry.id, fresh, operation, params, reads: entry.reads })
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* A REST op's answer, its `x-invalidate` targets marked and its stale mark cleared once it is a 2xx; it resolves
|
|
151
|
+
* after the `onInvalidate` hooks settle. An eligible write goes in a single-flight batch, its key made first so a
|
|
152
|
+
* refused batch's direct resend carries the same one.
|
|
153
|
+
*/
|
|
154
|
+
async request(entry: ServiceEntry, call: CallInput): Promise<Answer> {
|
|
155
|
+
const key = entry.idempotent === true ? { idempotencyKey: call.idempotencyKey ?? newClientRequestId() } : {}
|
|
156
|
+
const input = { ...call, ...key }
|
|
141
157
|
const template = templateOf(entry)
|
|
142
|
-
|
|
143
|
-
try {
|
|
144
|
-
path = interpolatePath(template, input.params)
|
|
145
|
-
} catch (e) {
|
|
146
|
-
throw e instanceof PathParamError ? pathError(e, entry) : e
|
|
147
|
-
}
|
|
158
|
+
const path = pathOf(entry, template, input.params)
|
|
148
159
|
const selector = `${entry.method} ${path}`
|
|
149
160
|
const meta = this.meta(selector, path, entry.method)
|
|
150
|
-
const
|
|
151
|
-
|
|
161
|
+
const reading = { declared: entry.empty === true ? null : entry.accept, limits: this.#config, method: entry.method }
|
|
162
|
+
let fresh: FreshReads | undefined
|
|
152
163
|
const settle = () => {
|
|
153
164
|
this.mark(entry, input.params, selector)
|
|
154
165
|
if (meta?.isStale) this.#stale?.clear(selector, path, entry.method, meta.seqSnapshot)
|
|
166
|
+
return this.invalidated(entry, input.params, fresh)
|
|
155
167
|
}
|
|
156
168
|
try {
|
|
157
|
-
const
|
|
158
|
-
|
|
169
|
+
const client = { config: this.#config.singleFlight, disposal: this.#disposal.signal, http: this.http }
|
|
170
|
+
const flown = await fly(client, entry, input)
|
|
171
|
+
fresh = flown?.fresh
|
|
172
|
+
const op = { ...reading, meta, opts: optionsFor(entry, input), path: template }
|
|
173
|
+
const answer =
|
|
174
|
+
flown === undefined ? await this.http.requestOperation(op) : await finishRequest(flown.sent, reading)
|
|
175
|
+
await settle()
|
|
159
176
|
return answer
|
|
160
177
|
} catch (e) {
|
|
161
178
|
/* a 2xx whose body does not decode still changed what it invalidates */
|
|
162
|
-
if (e instanceof DecodeError) settle()
|
|
179
|
+
if (e instanceof DecodeError) await settle()
|
|
163
180
|
throw e
|
|
164
181
|
}
|
|
165
182
|
}
|
|
183
|
+
|
|
184
|
+
#newIndex(): StaleIndex | null {
|
|
185
|
+
const invalidation = this.#config.invalidation
|
|
186
|
+
if (!invalidation || invalidation.staleTime <= 0) return null
|
|
187
|
+
const maxSources = Math.max(invalidation.maxSourcesPerTarget ?? 16, 1)
|
|
188
|
+
return new StaleIndex({ maxEntries: invalidation.staleMaxEntries ?? 1000, maxSources })
|
|
189
|
+
}
|
|
166
190
|
}
|
|
167
191
|
|
|
168
192
|
/** The function an entry is called through, named by its member path; a safe one's REST answer a Result. */
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
import type { CallInput, ServiceEntry, ServiceMap, ServiceMapNode } from "./sdk.ts"
|
|
2
|
+
import { BATCH_VERSION, WRITE_METHODS } from "./sdk-single-flight.constants.ts"
|
|
3
|
+
import { READ_METHOD } from "./single-flight.constants.ts"
|
|
4
|
+
|
|
5
|
+
/** A JSON value, as a parsed body holds it. */
|
|
6
|
+
export type Json = null | boolean | number | string | readonly Json[] | JsonObject
|
|
7
|
+
|
|
8
|
+
/** A JSON object, as a parsed body holds it. */
|
|
9
|
+
export type JsonObject = { readonly [key: string]: Json }
|
|
10
|
+
|
|
11
|
+
/** One operation of the service map: its entry, and the member path the SDK calls it by. */
|
|
12
|
+
export type FlightOp = { entry: ServiceEntry; path: readonly string[] }
|
|
13
|
+
|
|
14
|
+
/** One read a batch asks for: the caller's name for it, its operation and its input. */
|
|
15
|
+
export type FlightRead = { id: string; input: CallInput; op: FlightOp }
|
|
16
|
+
|
|
17
|
+
/** A batch the service map allows: the write and its input, then the reads. */
|
|
18
|
+
export type FlightBatch = { input: CallInput; reads: readonly FlightRead[]; write: FlightOp }
|
|
19
|
+
|
|
20
|
+
/** What `parseBatch` answers: the batch, or why it was refused. */
|
|
21
|
+
export type ParsedBatch = { batch: FlightBatch } | { refused: string }
|
|
22
|
+
|
|
23
|
+
/** The input keys a write may carry; a read carries only params and search. */
|
|
24
|
+
type InputKey = "idempotencyKey" | "json" | "params" | "search"
|
|
25
|
+
const WRITE_KEYS: readonly InputKey[] = ["idempotencyKey", "json", "params", "search"]
|
|
26
|
+
const READ_KEYS: readonly InputKey[] = ["params", "search"]
|
|
27
|
+
|
|
28
|
+
/** Whether `node` is an operation, not a namespace of them. */
|
|
29
|
+
function isEntry(node: ServiceMapNode): node is ServiceEntry {
|
|
30
|
+
return Object.hasOwn(node, "method") && typeof node["method"] === "string"
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** Every operation of `map` by its operationId. */
|
|
34
|
+
export function operationsOf(map: ServiceMap): ReadonlyMap<string, FlightOp> {
|
|
35
|
+
const out = new Map<string, FlightOp>()
|
|
36
|
+
function walk(node: ServiceMapNode, path: readonly string[]): void {
|
|
37
|
+
if (isEntry(node)) out.set(node.id, { entry: node, path })
|
|
38
|
+
else for (const [key, child] of Object.entries(node)) walk(child, [...path, key])
|
|
39
|
+
}
|
|
40
|
+
walk(map, [])
|
|
41
|
+
return out
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Whether `value` is a JSON object, not an array or null. */
|
|
45
|
+
function isObject(value: Json | undefined): value is JsonObject {
|
|
46
|
+
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Whether `value` is a string. */
|
|
50
|
+
function isString(value: Json | undefined): value is string {
|
|
51
|
+
return typeof value === "string"
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** Whether `value` is what a path param may be: a string, or a finite number. */
|
|
55
|
+
function isParam(value: Json): value is number | string {
|
|
56
|
+
return isString(value) || (typeof value === "number" && Number.isFinite(value))
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Whether `value` is a JSON scalar: no array or object. */
|
|
60
|
+
function isScalar(value: Json): value is boolean | null | number | string {
|
|
61
|
+
return value === null || typeof value !== "object"
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Whether `value` is a JSON array. */
|
|
65
|
+
function isList(value: Json): value is readonly Json[] {
|
|
66
|
+
return Array.isArray(value)
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Whether `value` is what a query param may be: a scalar, or a list of them. */
|
|
70
|
+
function isSearchValue(value: Json): boolean {
|
|
71
|
+
return isList(value) ? value.every(isScalar) : isScalar(value)
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Whether `entry` is a plain REST call: no event stream, socket or realtime adapter. */
|
|
75
|
+
function isRest(entry: ServiceEntry): boolean {
|
|
76
|
+
return (
|
|
77
|
+
entry.call === undefined &&
|
|
78
|
+
[entry.sse, entry.ws, entry.realtime].every((flag) => flag === undefined || flag === false)
|
|
79
|
+
)
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Whether `key` is one of `keys`. */
|
|
83
|
+
function isInputKey(key: string, keys: readonly InputKey[]): key is InputKey {
|
|
84
|
+
return keys.some((allowed) => allowed === key)
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Refuse the batch: `parseBatch` turns this into its answer. */
|
|
88
|
+
function refuse(why: string): never {
|
|
89
|
+
throw new RangeError(why)
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** `value`'s path params, each one `entry` declares and a string or a number. */
|
|
93
|
+
function paramsOf(entry: ServiceEntry, value: Json): CallInput["params"] {
|
|
94
|
+
if (!isObject(value)) return refuse("params is not an object")
|
|
95
|
+
const declared = entry.params ?? []
|
|
96
|
+
for (const [key, param] of Object.entries(value)) {
|
|
97
|
+
if (!declared.includes(key)) refuse(`${entry.id} declares no param ${key}`)
|
|
98
|
+
if (!isParam(param)) refuse(`param ${key} is not a string or a number`)
|
|
99
|
+
}
|
|
100
|
+
return value /* interpolatePath writes a number as its digits, as a generated number param */ as CallInput["params"]
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** One input key's field put on `input`, once it is what `entry` takes there. */
|
|
104
|
+
type Field = (input: CallInput, field: Json, entry: ServiceEntry) => void
|
|
105
|
+
|
|
106
|
+
function setIdempotencyKey(input: CallInput, field: Json, entry: ServiceEntry): void {
|
|
107
|
+
if (!isString(field) || entry.idempotent !== true) refuse(`${entry.id} takes no idempotencyKey`)
|
|
108
|
+
input.idempotencyKey = field
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function setJson(input: CallInput, field: Json): void {
|
|
112
|
+
input.json = field
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function setParams(input: CallInput, field: Json, entry: ServiceEntry): void {
|
|
116
|
+
input.params = paramsOf(entry, field)
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
function setSearch(input: CallInput, field: Json): void {
|
|
120
|
+
if (!isObject(field) || !Object.values(field).every(isSearchValue)) refuse("search is not an object of scalars")
|
|
121
|
+
input.search = field
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
const FIELDS = {
|
|
125
|
+
idempotencyKey: setIdempotencyKey,
|
|
126
|
+
json: setJson,
|
|
127
|
+
params: setParams,
|
|
128
|
+
search: setSearch,
|
|
129
|
+
} satisfies { readonly [K in InputKey]: Field }
|
|
130
|
+
|
|
131
|
+
/** `value` as the input `entry` is called with, holding only `keys`. */
|
|
132
|
+
function inputOf(entry: ServiceEntry, value: Json | undefined, keys: readonly InputKey[]): CallInput {
|
|
133
|
+
if (value === undefined) return {}
|
|
134
|
+
if (!isObject(value)) return refuse("input is not an object")
|
|
135
|
+
const input: CallInput = {}
|
|
136
|
+
for (const [key, field] of Object.entries(value)) {
|
|
137
|
+
if (!isInputKey(key, keys)) refuse(`input key ${key} is not allowed here`)
|
|
138
|
+
FIELDS[key](input, field, entry)
|
|
139
|
+
}
|
|
140
|
+
return input
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** The write `body` names: a REST operation sent with a write method. */
|
|
144
|
+
function writeOf(ops: ReadonlyMap<string, FlightOp>, body: JsonObject): FlightOp {
|
|
145
|
+
const name = body["op"]
|
|
146
|
+
const op = isString(name) ? ops.get(name) : undefined
|
|
147
|
+
if (op === undefined || !WRITE_METHODS.includes(op.entry.method) || !isRest(op.entry)) refuse("op is no write")
|
|
148
|
+
return op
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/** A read's id: a non-empty string no other read of the batch has. */
|
|
152
|
+
function idOf(value: JsonObject, seen: Set<string>): string {
|
|
153
|
+
const { id } = value
|
|
154
|
+
if (!isString(id) || id === "" || seen.has(id)) refuse("a read has no id of its own")
|
|
155
|
+
seen.add(id)
|
|
156
|
+
return id
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** One read of a batch: a REST GET with a JSON answer, named by an id no other read has. */
|
|
160
|
+
function readOf(ops: ReadonlyMap<string, FlightOp>, value: Json, seen: Set<string>): FlightRead {
|
|
161
|
+
if (!isObject(value)) return refuse("a read is not an object")
|
|
162
|
+
const id = idOf(value, seen)
|
|
163
|
+
const { operationId } = value
|
|
164
|
+
const op = isString(operationId) ? ops.get(operationId) : undefined
|
|
165
|
+
if (op === undefined || op.entry.method !== READ_METHOD || !isRest(op.entry)) refuse(`${id} is no read`)
|
|
166
|
+
if (op.entry.accept !== undefined || op.entry.empty === true) refuse(`${id} answers no JSON`)
|
|
167
|
+
return { id, input: inputOf(op.entry, value["input"], READ_KEYS), op }
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** `body` as a batch of `ops`: a version 1 batch of one write and at most `maxReads` reads, or why it is refused. */
|
|
171
|
+
export function parseBatch(ops: ReadonlyMap<string, FlightOp>, body: Json, maxReads: number): ParsedBatch {
|
|
172
|
+
try {
|
|
173
|
+
if (!isObject(body) || body["v"] !== BATCH_VERSION) return refuse("the body is no version 1 batch")
|
|
174
|
+
const write = writeOf(ops, body)
|
|
175
|
+
const input = inputOf(write.entry, body["input"], WRITE_KEYS)
|
|
176
|
+
const reads = body["reads"] ?? []
|
|
177
|
+
if (!isList(reads) || reads.length > maxReads) refuse(`reads is not a list of at most ${maxReads}`)
|
|
178
|
+
const seen = new Set<string>()
|
|
179
|
+
return { batch: { input, reads: reads.map((read) => readOf(ops, read, seen)), write } }
|
|
180
|
+
} catch (e) {
|
|
181
|
+
if (e instanceof RangeError) return { refused: e.message }
|
|
182
|
+
throw e
|
|
183
|
+
}
|
|
184
|
+
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A body to read whole: each chunk is offered to `take` first; the read stops once it refuses one or `signal`
|
|
3
|
+
* aborts.
|
|
4
|
+
*/
|
|
5
|
+
export type BodySource = {
|
|
6
|
+
body: ReadableStream<Uint8Array> | null
|
|
7
|
+
signal?: AbortSignal
|
|
8
|
+
take: (chunk: Uint8Array) => boolean
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/** A body being read: its reader, the chunks kept so far, and what decides whether the next is kept. */
|
|
12
|
+
type Drain = { chunks: Uint8Array[]; reader: ReadableStreamDefaultReader<Uint8Array>; take: BodySource["take"] }
|
|
13
|
+
|
|
14
|
+
/** A settled cancel: a body is given up on whether or not its cancel succeeds. */
|
|
15
|
+
function nothing(): undefined {
|
|
16
|
+
return undefined
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** `chunks` as one buffer. */
|
|
20
|
+
function joined(chunks: readonly Uint8Array[]): Uint8Array<ArrayBuffer> {
|
|
21
|
+
let size = 0
|
|
22
|
+
for (const chunk of chunks) size += chunk.byteLength
|
|
23
|
+
const out = new Uint8Array(size)
|
|
24
|
+
let at = 0
|
|
25
|
+
for (const chunk of chunks) {
|
|
26
|
+
out.set(chunk, at)
|
|
27
|
+
at += chunk.byteLength
|
|
28
|
+
}
|
|
29
|
+
return out
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Read `drain` to its end: false, with the body cancelled, once `take` refuses a chunk. */
|
|
33
|
+
async function drained(drain: Drain): Promise<boolean> {
|
|
34
|
+
const next = await drain.reader.read()
|
|
35
|
+
if (next.done) return true
|
|
36
|
+
if (!drain.take(next.value)) {
|
|
37
|
+
/* not awaited: the refusal stands whether or not the body cancels cleanly */
|
|
38
|
+
void drain.reader.cancel().catch(nothing)
|
|
39
|
+
return false
|
|
40
|
+
}
|
|
41
|
+
drain.chunks.push(next.value)
|
|
42
|
+
return drained(drain)
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** `source`'s body read whole, or undefined once `take` refused a chunk; an abort cancels it where it stands. */
|
|
46
|
+
export async function bodyOf(source: BodySource): Promise<Uint8Array<ArrayBuffer> | undefined> {
|
|
47
|
+
if (source.body === null) return new Uint8Array(0)
|
|
48
|
+
const reader = source.body.getReader()
|
|
49
|
+
function stop(): void {
|
|
50
|
+
void reader.cancel().catch(nothing)
|
|
51
|
+
}
|
|
52
|
+
source.signal?.addEventListener("abort", stop, { once: true })
|
|
53
|
+
try {
|
|
54
|
+
const drain: Drain = { chunks: [], reader, take: source.take }
|
|
55
|
+
return (await drained(drain)) ? joined(drain.chunks) : undefined
|
|
56
|
+
} finally {
|
|
57
|
+
source.signal?.removeEventListener("abort", stop)
|
|
58
|
+
}
|
|
59
|
+
}
|