@tinyshed/tinystore 0.1.0-rc.1
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/LICENSE +202 -0
- package/README.md +262 -0
- package/bin/tinystore.js +50 -0
- package/dist/background.d.ts +30 -0
- package/dist/background.js +93 -0
- package/dist/blobs.d.ts +98 -0
- package/dist/blobs.js +299 -0
- package/dist/cancel.d.ts +14 -0
- package/dist/cancel.js +22 -0
- package/dist/clock.d.ts +21 -0
- package/dist/clock.js +35 -0
- package/dist/config.d.ts +60 -0
- package/dist/config.js +417 -0
- package/dist/connection.d.ts +78 -0
- package/dist/connection.js +405 -0
- package/dist/console.d.ts +48 -0
- package/dist/console.js +195 -0
- package/dist/errors.d.ts +103 -0
- package/dist/errors.js +158 -0
- package/dist/handles.d.ts +28 -0
- package/dist/handles.js +37 -0
- package/dist/index.d.ts +21 -0
- package/dist/index.js +7 -0
- package/dist/jobs.d.ts +304 -0
- package/dist/jobs.js +684 -0
- package/dist/kv.d.ts +283 -0
- package/dist/kv.js +815 -0
- package/dist/limiter.d.ts +45 -0
- package/dist/limiter.js +68 -0
- package/dist/logger.d.ts +96 -0
- package/dist/logger.js +243 -0
- package/dist/metrics.d.ts +249 -0
- package/dist/metrics.js +610 -0
- package/dist/once.d.ts +31 -0
- package/dist/once.js +116 -0
- package/dist/quota.d.ts +44 -0
- package/dist/quota.js +98 -0
- package/dist/records.d.ts +182 -0
- package/dist/records.js +346 -0
- package/dist/runtime/bun.d.ts +2 -0
- package/dist/runtime/bun.js +164 -0
- package/dist/runtime/node.d.ts +2 -0
- package/dist/runtime/node.js +157 -0
- package/dist/runtime/shared.d.ts +25 -0
- package/dist/runtime/shared.js +45 -0
- package/dist/runtime.d.ts +48 -0
- package/dist/runtime.js +4 -0
- package/dist/schema.d.ts +39 -0
- package/dist/schema.js +21 -0
- package/dist/session.d.ts +120 -0
- package/dist/session.js +546 -0
- package/dist/sql.d.ts +121 -0
- package/dist/sql.js +342 -0
- package/dist/store.d.ts +103 -0
- package/dist/store.js +153 -0
- package/dist/time.d.ts +35 -0
- package/dist/time.js +44 -0
- package/dist/trace.d.ts +18 -0
- package/dist/trace.js +22 -0
- package/dist/wire/codec.d.ts +90 -0
- package/dist/wire/codec.js +383 -0
- package/dist/wire/frame.d.ts +41 -0
- package/dist/wire/frame.js +102 -0
- package/dist/wire/messages.d.ts +1403 -0
- package/dist/wire/messages.js +472 -0
- package/dist/wire/msgpack.d.ts +93 -0
- package/dist/wire/msgpack.js +680 -0
- package/package.json +40 -0
- package/src/background.ts +108 -0
- package/src/blobs.ts +437 -0
- package/src/cancel.ts +26 -0
- package/src/clock.ts +45 -0
- package/src/config.ts +501 -0
- package/src/connection.ts +512 -0
- package/src/console.ts +228 -0
- package/src/errors.ts +211 -0
- package/src/handles.ts +68 -0
- package/src/index.ts +92 -0
- package/src/jobs.ts +963 -0
- package/src/kv.ts +1093 -0
- package/src/limiter.ts +99 -0
- package/src/logger.ts +326 -0
- package/src/metrics.ts +896 -0
- package/src/once.ts +142 -0
- package/src/quota.ts +137 -0
- package/src/records.ts +537 -0
- package/src/runtime/bun.ts +190 -0
- package/src/runtime/node.ts +177 -0
- package/src/runtime/shared.ts +61 -0
- package/src/runtime.ts +57 -0
- package/src/schema.ts +69 -0
- package/src/session.ts +665 -0
- package/src/sql.ts +478 -0
- package/src/store.ts +219 -0
- package/src/time.ts +87 -0
- package/src/trace.ts +32 -0
- package/src/wire/codec.ts +445 -0
- package/src/wire/frame.ts +139 -0
- package/src/wire/messages.ts +562 -0
- package/src/wire/msgpack.ts +712 -0
|
@@ -0,0 +1,512 @@
|
|
|
1
|
+
// A connection is a transport and the session over it; a link is what gives
|
|
2
|
+
// the store its connection, dialling again once the last one ended: the
|
|
3
|
+
// directory's sidecar, found through SERVE or started, a private child, or a
|
|
4
|
+
// remote server.
|
|
5
|
+
|
|
6
|
+
import { randomBytes } from 'node:crypto'
|
|
7
|
+
import { join, resolve } from 'node:path'
|
|
8
|
+
|
|
9
|
+
import manifest from '../package.json' with { type: 'json' }
|
|
10
|
+
import { currentSignal } from './cancel.ts'
|
|
11
|
+
import { ClosedError, OutcomeUnknownError, TinystoreError, UnavailableError } from './errors.ts'
|
|
12
|
+
import type { PrivateChild, Runtime, TlsOptions, Transport } from './runtime.ts'
|
|
13
|
+
import { LostError, Session, type SessionOptions, type Stream, watch } from './session.ts'
|
|
14
|
+
import { Empty, methods } from './wire/messages.ts'
|
|
15
|
+
|
|
16
|
+
/** How long a server may take to answer HELLO. */
|
|
17
|
+
const handshakeTime = 5000
|
|
18
|
+
|
|
19
|
+
export class Connection {
|
|
20
|
+
readonly session: Session
|
|
21
|
+
readonly #transport: Transport
|
|
22
|
+
/** what close waits for once the transport has ended: a private child's exit */
|
|
23
|
+
readonly #closing: () => Promise<unknown>
|
|
24
|
+
/** the handles this connection opened, by what they are: a bucket's name and options */
|
|
25
|
+
readonly handles = new Map<string, Promise<number>>()
|
|
26
|
+
|
|
27
|
+
constructor(
|
|
28
|
+
session: Session,
|
|
29
|
+
transport: Transport,
|
|
30
|
+
closing: () => Promise<unknown> = () => Promise.resolve(),
|
|
31
|
+
) {
|
|
32
|
+
this.session = session
|
|
33
|
+
this.#transport = transport
|
|
34
|
+
this.#closing = closing
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Connects, shakes hands, and gives up after the handshake's time. */
|
|
38
|
+
static async dial(runtime: Runtime, endpoint: string, options: SessionOptions, tls?: TlsOptions) {
|
|
39
|
+
let session: Session | undefined
|
|
40
|
+
const early: Uint8Array[] = []
|
|
41
|
+
const transport = await runtime
|
|
42
|
+
.connect(
|
|
43
|
+
endpoint,
|
|
44
|
+
{
|
|
45
|
+
data: bytes =>
|
|
46
|
+
session === undefined ? early.push(bytes.slice()) : session.receive(bytes),
|
|
47
|
+
end: err => session?.end(err),
|
|
48
|
+
},
|
|
49
|
+
tls,
|
|
50
|
+
)
|
|
51
|
+
.catch((err: unknown) => {
|
|
52
|
+
// a socket that refuses fails as the platform says it; a caller sees one kind
|
|
53
|
+
if (err instanceof TinystoreError) {
|
|
54
|
+
throw err
|
|
55
|
+
}
|
|
56
|
+
throw new ClosedError(`cannot reach ${endpoint}: ${(err as Error).message}`)
|
|
57
|
+
})
|
|
58
|
+
session = new Session(bytes => transport.write(bytes), options)
|
|
59
|
+
for (const bytes of early) {
|
|
60
|
+
session.receive(bytes)
|
|
61
|
+
}
|
|
62
|
+
const connection = new Connection(session, transport)
|
|
63
|
+
await connection.#handshake()
|
|
64
|
+
return connection
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Shakes hands over a private child's stdin and stdout. Closing waits for
|
|
69
|
+
* the child's exit, since until then it holds the directory: its LOCK, and
|
|
70
|
+
* on Windows every file it opened, which a removal fails on.
|
|
71
|
+
*/
|
|
72
|
+
static async overChild(child: PrivateChild, session: Session): Promise<Connection> {
|
|
73
|
+
const connection = new Connection(session, child.transport, () => child.exited)
|
|
74
|
+
await connection.#handshake()
|
|
75
|
+
return connection
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
async #handshake(): Promise<void> {
|
|
79
|
+
const timer = setTimeout(
|
|
80
|
+
() => this.session.end(new ClosedError(`no WELCOME within ${handshakeTime / 1000} s`)),
|
|
81
|
+
handshakeTime,
|
|
82
|
+
)
|
|
83
|
+
try {
|
|
84
|
+
await this.session.welcomed
|
|
85
|
+
} catch (err) {
|
|
86
|
+
this.#transport.close()
|
|
87
|
+
throw err
|
|
88
|
+
} finally {
|
|
89
|
+
clearTimeout(timer)
|
|
90
|
+
}
|
|
91
|
+
this.session.onEnd(() => this.#transport.close())
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Ends the connection; a private child is waited for until it has exited. */
|
|
95
|
+
async close(): Promise<void> {
|
|
96
|
+
this.session.end(new ClosedError('the store closed'))
|
|
97
|
+
this.#transport.close()
|
|
98
|
+
await this.#closing()
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Where a link dials. */
|
|
103
|
+
export type Dialer = () => Promise<Connection>
|
|
104
|
+
|
|
105
|
+
/** SERVE, where a directory's sidecar says it listens. */
|
|
106
|
+
interface Published {
|
|
107
|
+
protocol: number
|
|
108
|
+
server: string
|
|
109
|
+
pid: number
|
|
110
|
+
instance: string
|
|
111
|
+
secret: string
|
|
112
|
+
endpoints: string[]
|
|
113
|
+
/** a server started for its clients, which a client of a newer release replaces */
|
|
114
|
+
sidecar?: boolean
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** How long a client waits for a sidecar to answer, its own or another's, before it gives up. */
|
|
118
|
+
const startTime = 15_000
|
|
119
|
+
|
|
120
|
+
/** The pause before a start that found the directory held starts again, doubling up to a second. */
|
|
121
|
+
const heldPause = 100
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Finds the directory's sidecar through SERVE or starts one, as docs/wire.md
|
|
125
|
+
* "Finding a local server" says: a sidecar found proves itself before the
|
|
126
|
+
* first call, and one started exits with 3 when another holds the directory,
|
|
127
|
+
* whose SERVE the client then waits for. A sidecar of an older release than
|
|
128
|
+
* this SDK's is stopped and replaced with this SDK's binary; another server
|
|
129
|
+
* of an older release, a person's or a program's own, is told of once.
|
|
130
|
+
*/
|
|
131
|
+
export function sidecar(
|
|
132
|
+
runtime: Runtime,
|
|
133
|
+
dir: string,
|
|
134
|
+
binary: () => string,
|
|
135
|
+
idle?: number,
|
|
136
|
+
older: (server: string) => boolean = server => olderRelease(server, manifest.version),
|
|
137
|
+
): Dialer {
|
|
138
|
+
const absolute = resolve(dir)
|
|
139
|
+
const serve = join(absolute, 'server', 'SERVE')
|
|
140
|
+
const log = join(absolute, 'server', 'serve.log')
|
|
141
|
+
const idling = idle === undefined ? [] : ['--idle', `${idle}ms`]
|
|
142
|
+
let told = false
|
|
143
|
+
return async () => {
|
|
144
|
+
const found = await reachServe(runtime, serve)
|
|
145
|
+
let stoppedInstance: string | undefined
|
|
146
|
+
if (found !== undefined) {
|
|
147
|
+
const server = (await found.connection.session.welcomed).server
|
|
148
|
+
if (!older(server)) {
|
|
149
|
+
return found.connection
|
|
150
|
+
}
|
|
151
|
+
if (found.sidecar && (await stopped(found.connection))) {
|
|
152
|
+
process.stderr.write(`${replacedSidecar(server, manifest.version, dir)}\n`)
|
|
153
|
+
stoppedInstance = found.instance
|
|
154
|
+
} else {
|
|
155
|
+
if (!told) {
|
|
156
|
+
process.stderr.write(`${olderServer(server, manifest.version, dir)}\n`)
|
|
157
|
+
}
|
|
158
|
+
told = true
|
|
159
|
+
return found.connection
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
const command = [binary(), 'serve', '--dir', absolute, '--local', '--log', log, ...idling]
|
|
163
|
+
return startSidecar(runtime, serve, log, command, stoppedInstance)
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Starts a sidecar and waits for SERVE to name one that answers, its own or
|
|
169
|
+
* another client's that won the start. One that exits with 3 found the
|
|
170
|
+
* directory held, by a winner about to publish or by a sidecar still letting
|
|
171
|
+
* go, and is started again after a pause; any other exit is an error. A
|
|
172
|
+
* sidecar told to stop answers for a moment after it agreed, until SERVE
|
|
173
|
+
* goes, so the one of the instance stopped is passed over.
|
|
174
|
+
*/
|
|
175
|
+
async function startSidecar(
|
|
176
|
+
runtime: Runtime,
|
|
177
|
+
serve: string,
|
|
178
|
+
log: string,
|
|
179
|
+
command: string[],
|
|
180
|
+
stoppedInstance?: string,
|
|
181
|
+
): Promise<Connection> {
|
|
182
|
+
const deadline = Date.now() + startTime
|
|
183
|
+
let held = false
|
|
184
|
+
for (let pause = heldPause; ; pause = Math.min(pause * 2, 1000)) {
|
|
185
|
+
const child = runtime.spawnDetached(command)
|
|
186
|
+
let exited: number | undefined
|
|
187
|
+
child.exited.then(code => {
|
|
188
|
+
exited = code
|
|
189
|
+
})
|
|
190
|
+
let again: number | undefined
|
|
191
|
+
for (let wait = 5; Date.now() < deadline; wait = Math.min(wait * 2, 100)) {
|
|
192
|
+
const reached = await reachServe(runtime, serve)
|
|
193
|
+
if (reached !== undefined && reached.instance !== stoppedInstance) {
|
|
194
|
+
return reached.connection
|
|
195
|
+
}
|
|
196
|
+
await reached?.connection.close()
|
|
197
|
+
if (exited !== undefined && exited !== 3) {
|
|
198
|
+
throw new ClosedError(`the sidecar exited with ${exited}: ${await tail(runtime, log)}`)
|
|
199
|
+
}
|
|
200
|
+
if (exited === 3) {
|
|
201
|
+
held = true
|
|
202
|
+
again ??= Date.now() + pause
|
|
203
|
+
if (Date.now() >= again) {
|
|
204
|
+
break
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
await sleep(wait)
|
|
208
|
+
}
|
|
209
|
+
if (Date.now() >= deadline) {
|
|
210
|
+
const why = held
|
|
211
|
+
? 'another process holds the directory but no sidecar answers'
|
|
212
|
+
: 'no sidecar answered'
|
|
213
|
+
throw new ClosedError(`${why} in ${startTime / 1000} s: ${await tail(runtime, log)}`)
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Asks a sidecar to stop as tinystore stop does, closing the connection once
|
|
220
|
+
* it has answered; false when it refuses, and the connection stays open.
|
|
221
|
+
*/
|
|
222
|
+
async function stopped(connection: Connection): Promise<boolean> {
|
|
223
|
+
try {
|
|
224
|
+
await connection.session.call(methods['server.stop'], Empty.encode({}))
|
|
225
|
+
} catch {
|
|
226
|
+
return false
|
|
227
|
+
}
|
|
228
|
+
await connection.close()
|
|
229
|
+
return true
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Whether a server's release is older than the SDK's own; a build that is no
|
|
234
|
+
* release, a development copy's or a Go pseudo-version, is neither.
|
|
235
|
+
*/
|
|
236
|
+
export function olderRelease(server: string, own: string): boolean {
|
|
237
|
+
const theirs = release(server)
|
|
238
|
+
const ours = release(own)
|
|
239
|
+
return theirs !== undefined && ours !== undefined && compareReleases(theirs, ours) < 0
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** What a program whose SDK replaced a sidecar of an older release is told. */
|
|
243
|
+
export function replacedSidecar(server: string, own: string, dir: string): string {
|
|
244
|
+
return (
|
|
245
|
+
`tinystore: the sidecar serving ${dir} was ${server}, older than this SDK's ${own}; it finishes ` +
|
|
246
|
+
"its calls, and this SDK's binary serves the directory from now on"
|
|
247
|
+
)
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/** What a program whose SDK found a server of an older release that is no sidecar is told. */
|
|
251
|
+
export function olderServer(server: string, own: string, dir: string): string {
|
|
252
|
+
return (
|
|
253
|
+
`tinystore: ${dir} is served by ${server}, older than this SDK's ${own}; a person or a program ` +
|
|
254
|
+
'started that server, and it runs until they stop it'
|
|
255
|
+
)
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
interface Release {
|
|
259
|
+
core: number[]
|
|
260
|
+
pre: string[]
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/**
|
|
264
|
+
* A release's version, its v optional: 0.2.0, v0.2.0-rc.1. A development copy's
|
|
265
|
+
* 0.0.0, a Go pseudo-version and (devel) are none.
|
|
266
|
+
*/
|
|
267
|
+
function release(version: string): Release | undefined {
|
|
268
|
+
const parts = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.]+))?$/.exec(version)
|
|
269
|
+
if (parts === null) {
|
|
270
|
+
return undefined
|
|
271
|
+
}
|
|
272
|
+
const core = [Number(parts[1]), Number(parts[2]), Number(parts[3])]
|
|
273
|
+
return core.every(n => n === 0)
|
|
274
|
+
? undefined
|
|
275
|
+
: { core, pre: parts[4] === undefined ? [] : parts[4].split('.') }
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** Semantic versioning's order: a release after its pre-releases, rc.2 before rc.10. */
|
|
279
|
+
function compareReleases(a: Release, b: Release): number {
|
|
280
|
+
for (let i = 0; i < 3; i++) {
|
|
281
|
+
if (a.core[i] !== b.core[i]) {
|
|
282
|
+
return a.core[i]! - b.core[i]!
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
if (a.pre.length === 0 || b.pre.length === 0) {
|
|
286
|
+
return b.pre.length - a.pre.length
|
|
287
|
+
}
|
|
288
|
+
for (let i = 0; i < Math.min(a.pre.length, b.pre.length); i++) {
|
|
289
|
+
const x = a.pre[i]!
|
|
290
|
+
const y = b.pre[i]!
|
|
291
|
+
const numbers = /^\d+$/.test(x) && /^\d+$/.test(y)
|
|
292
|
+
if (x !== y) {
|
|
293
|
+
return numbers ? Number(x) - Number(y) : x < y ? -1 : 1
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
return a.pre.length - b.pre.length
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/** The sidecar SERVE names, once its proof checks; undefined on any failure. */
|
|
300
|
+
async function reachServe(
|
|
301
|
+
runtime: Runtime,
|
|
302
|
+
serve: string,
|
|
303
|
+
): Promise<{ connection: Connection; sidecar: boolean; instance: string } | undefined> {
|
|
304
|
+
let published: Published
|
|
305
|
+
try {
|
|
306
|
+
const text = await runtime.readFile(serve)
|
|
307
|
+
if (text === undefined) {
|
|
308
|
+
return undefined
|
|
309
|
+
}
|
|
310
|
+
published = JSON.parse(new TextDecoder().decode(text))
|
|
311
|
+
} catch {
|
|
312
|
+
return undefined
|
|
313
|
+
}
|
|
314
|
+
const endpoint = published.endpoints?.[0]
|
|
315
|
+
const secret = Buffer.from(published.secret ?? '', 'base64url')
|
|
316
|
+
if (published.protocol !== 1 || endpoint === undefined || secret.length !== 32) {
|
|
317
|
+
return undefined
|
|
318
|
+
}
|
|
319
|
+
try {
|
|
320
|
+
const connection = await Connection.dial(runtime, endpoint, {
|
|
321
|
+
client: runtime.client,
|
|
322
|
+
secret: new Uint8Array(secret),
|
|
323
|
+
challenge: new Uint8Array(randomBytes(16)),
|
|
324
|
+
})
|
|
325
|
+
return { connection, sidecar: published.sidecar === true, instance: published.instance }
|
|
326
|
+
} catch {
|
|
327
|
+
return undefined
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
function sleep(ms: number): Promise<void> {
|
|
332
|
+
return new Promise(resolve => setTimeout(resolve, ms))
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
async function tail(runtime: Runtime, log: string): Promise<string> {
|
|
336
|
+
const text = await runtime.readFile(log).catch(() => undefined)
|
|
337
|
+
if (text === undefined) {
|
|
338
|
+
return 'it wrote no log'
|
|
339
|
+
}
|
|
340
|
+
const lines = new TextDecoder().decode(text).trimEnd().split('\n')
|
|
341
|
+
return lines.slice(-5).join('\n')
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/** A private child: tinystore serve --stdio, living and dying with this process. */
|
|
345
|
+
export function privateChild(
|
|
346
|
+
runtime: Runtime,
|
|
347
|
+
dir: string,
|
|
348
|
+
binary: () => string,
|
|
349
|
+
clock?: Date,
|
|
350
|
+
): Dialer {
|
|
351
|
+
// a test's clock starts where the first child's did, and a child started again starts it there
|
|
352
|
+
const clocked = clock === undefined ? [] : ['--clock', clock.toISOString()]
|
|
353
|
+
return async () => {
|
|
354
|
+
let session: Session | undefined
|
|
355
|
+
const argv = [binary(), 'serve', '--dir', resolve(dir), '--stdio', ...clocked]
|
|
356
|
+
const child = runtime.spawnPrivate(argv, {
|
|
357
|
+
data: bytes => session?.receive(bytes),
|
|
358
|
+
end: err => session?.end(err),
|
|
359
|
+
})
|
|
360
|
+
session = new Session(bytes => child.transport.write(bytes), { client: runtime.client })
|
|
361
|
+
session.onEnd(() => {
|
|
362
|
+
child.transport.close()
|
|
363
|
+
// a child told to leave by the end of its stdin drains and exits; one that does not is killed
|
|
364
|
+
const killer = setTimeout(() => child.kill(), 10_000)
|
|
365
|
+
child.exited.finally(() => clearTimeout(killer))
|
|
366
|
+
})
|
|
367
|
+
try {
|
|
368
|
+
return await Connection.overChild(child, session)
|
|
369
|
+
} catch (err) {
|
|
370
|
+
child.kill()
|
|
371
|
+
throw new ClosedError(`the private server did not start: ${(err as Error).message}`)
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/** A remote server: tls:// checks its certificate before the token leaves; tcp:// does not. */
|
|
377
|
+
export function remote(runtime: Runtime, url: string, token: string, tls?: TlsOptions): Dialer {
|
|
378
|
+
return () => Connection.dial(runtime, url, { client: runtime.client, token }, tls)
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
/** What a call may do when its connection is lost: go again, or say its outcome is unknown. */
|
|
382
|
+
export type Idempotence = 'read' | 'write'
|
|
383
|
+
|
|
384
|
+
/**
|
|
385
|
+
* Gives calls a connection, dialling again once the last one ended, and runs
|
|
386
|
+
* a call so that a lost connection costs it what it must: a call whose
|
|
387
|
+
* REQUEST had not left goes again, so does a read that had, and a write that
|
|
388
|
+
* had is OutcomeUnknownError.
|
|
389
|
+
*/
|
|
390
|
+
export class Link {
|
|
391
|
+
readonly #dial: Dialer
|
|
392
|
+
#current: Promise<Connection> | undefined
|
|
393
|
+
#closed = false
|
|
394
|
+
|
|
395
|
+
constructor(dial: Dialer) {
|
|
396
|
+
this.#dial = dial
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/** The connection a call goes on. */
|
|
400
|
+
connection(): Promise<Connection> {
|
|
401
|
+
if (this.#closed) {
|
|
402
|
+
return Promise.reject(new ClosedError('the store is closed'))
|
|
403
|
+
}
|
|
404
|
+
const current = this.#current
|
|
405
|
+
if (current !== undefined) {
|
|
406
|
+
return current.then(
|
|
407
|
+
c => (c.session.ended === undefined && !c.session.goingAway ? c : this.#redial(current)),
|
|
408
|
+
() => this.#redial(current),
|
|
409
|
+
)
|
|
410
|
+
}
|
|
411
|
+
return this.#redial(undefined)
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
// one dial at a time: every caller that found the same dead connection
|
|
415
|
+
// waits for the one new one
|
|
416
|
+
#redial(dead: Promise<Connection> | undefined): Promise<Connection> {
|
|
417
|
+
if (this.#current !== dead && this.#current !== undefined) {
|
|
418
|
+
return this.connection()
|
|
419
|
+
}
|
|
420
|
+
const dialled = this.#dial()
|
|
421
|
+
this.#current = dialled
|
|
422
|
+
dialled.catch(() => {
|
|
423
|
+
if (this.#current === dialled) {
|
|
424
|
+
this.#current = undefined
|
|
425
|
+
}
|
|
426
|
+
})
|
|
427
|
+
return dialled
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
/**
|
|
431
|
+
* Runs a call on the link's connection. build makes its REQUEST's body for
|
|
432
|
+
* that connection, whose handles it may open; run sends it.
|
|
433
|
+
*/
|
|
434
|
+
async run<T>(
|
|
435
|
+
idempotence: Idempotence,
|
|
436
|
+
attempt: (connection: Connection) => Promise<T>,
|
|
437
|
+
signal?: AbortSignal,
|
|
438
|
+
): Promise<T> {
|
|
439
|
+
for (let tries = 0; ; tries++) {
|
|
440
|
+
;(signal ?? currentSignal())?.throwIfAborted()
|
|
441
|
+
const connection = await this.connection()
|
|
442
|
+
try {
|
|
443
|
+
return await attempt(connection)
|
|
444
|
+
} catch (err) {
|
|
445
|
+
if (tries < 2 && (err instanceof LostError || err instanceof UnavailableError)) {
|
|
446
|
+
const sent = err instanceof LostError && err.sent
|
|
447
|
+
if (!sent || idempotence === 'read') {
|
|
448
|
+
continue
|
|
449
|
+
}
|
|
450
|
+
throw new OutcomeUnknownError(
|
|
451
|
+
`the connection was lost with the write in flight; read what it wrote before writing again: ${err.message}`,
|
|
452
|
+
)
|
|
453
|
+
}
|
|
454
|
+
throw err
|
|
455
|
+
}
|
|
456
|
+
}
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
/** Closes the connection and every one to come. */
|
|
460
|
+
async close(): Promise<void> {
|
|
461
|
+
this.#closed = true
|
|
462
|
+
const current = this.#current
|
|
463
|
+
this.#current = undefined
|
|
464
|
+
await current?.then(
|
|
465
|
+
c => c.close(),
|
|
466
|
+
() => {},
|
|
467
|
+
)
|
|
468
|
+
}
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
/** What a download sent: its header, its items, and the trailer that ended it. */
|
|
472
|
+
export interface Downloaded {
|
|
473
|
+
header: Uint8Array
|
|
474
|
+
items: Uint8Array[]
|
|
475
|
+
trailer: Uint8Array
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
/**
|
|
479
|
+
* Runs a download to its end: the RESPONSE that heads it, an item a DATA, and
|
|
480
|
+
* the DATA that ends it, giving each item's credit back as it arrives, since
|
|
481
|
+
* the server bounds a page before it sends it. A download the server answers
|
|
482
|
+
* with a RESPONSE that ends it has no items and that RESPONSE for trailer.
|
|
483
|
+
*/
|
|
484
|
+
export async function download(
|
|
485
|
+
connection: Connection,
|
|
486
|
+
method: number,
|
|
487
|
+
body: Uint8Array,
|
|
488
|
+
signal?: AbortSignal,
|
|
489
|
+
): Promise<Downloaded> {
|
|
490
|
+
signal?.throwIfAborted()
|
|
491
|
+
const stream = await connection.session.open(method, body, true)
|
|
492
|
+
const unwatch = watch(signal, stream)
|
|
493
|
+
try {
|
|
494
|
+
const head = await stream.next()
|
|
495
|
+
if (head.end) {
|
|
496
|
+
return { header: head.body, items: [], trailer: head.body }
|
|
497
|
+
}
|
|
498
|
+
const items: Uint8Array[] = []
|
|
499
|
+
for (;;) {
|
|
500
|
+
const event = await stream.next()
|
|
501
|
+
stream.consumed(event.body.length)
|
|
502
|
+
if (event.end) {
|
|
503
|
+
return { header: head.body, items, trailer: event.body }
|
|
504
|
+
}
|
|
505
|
+
items.push(event.body)
|
|
506
|
+
}
|
|
507
|
+
} finally {
|
|
508
|
+
unwatch()
|
|
509
|
+
}
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
export type { Stream }
|