@tinyshed/tinystore 0.1.0 → 0.1.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.
Files changed (69) hide show
  1. package/dist/blobs.d.ts +1 -1
  2. package/dist/blobs.js +13 -5
  3. package/dist/cancel.d.ts +16 -2
  4. package/dist/cancel.js +36 -2
  5. package/dist/channels.js +20 -6
  6. package/dist/config.d.ts +49 -1
  7. package/dist/config.js +86 -7
  8. package/dist/connection.d.ts +52 -10
  9. package/dist/connection.js +305 -73
  10. package/dist/handles.d.ts +10 -1
  11. package/dist/handles.js +27 -4
  12. package/dist/index.d.ts +4 -4
  13. package/dist/jobs.d.ts +33 -1
  14. package/dist/jobs.js +45 -0
  15. package/dist/logger.d.ts +22 -10
  16. package/dist/logger.js +118 -28
  17. package/dist/metrics.d.ts +19 -0
  18. package/dist/metrics.js +22 -1
  19. package/dist/query.js +33 -9
  20. package/dist/records.d.ts +30 -2
  21. package/dist/records.js +8 -0
  22. package/dist/runtime/addon.js +3 -2
  23. package/dist/runtime/bun.js +33 -12
  24. package/dist/runtime/node.js +30 -8
  25. package/dist/runtime/pipe.d.ts +2 -0
  26. package/dist/runtime/pipe.js +45 -20
  27. package/dist/runtime/shared.d.ts +28 -4
  28. package/dist/runtime/shared.js +125 -13
  29. package/dist/runtime.d.ts +28 -6
  30. package/dist/session.d.ts +9 -5
  31. package/dist/session.js +113 -31
  32. package/dist/sql.d.ts +18 -5
  33. package/dist/sql.js +44 -11
  34. package/dist/store.d.ts +25 -11
  35. package/dist/store.js +67 -9
  36. package/dist/wire/codec.d.ts +5 -0
  37. package/dist/wire/codec.js +10 -0
  38. package/dist/wire/frame.d.ts +2 -0
  39. package/dist/wire/frame.js +4 -0
  40. package/dist/wire/msgpack.d.ts +7 -3
  41. package/dist/wire/msgpack.js +11 -4
  42. package/dist/wire/protocol.d.ts +246 -36
  43. package/dist/wire/protocol.js +387 -101
  44. package/package.json +9 -8
  45. package/src/blobs.ts +13 -5
  46. package/src/cancel.ts +44 -2
  47. package/src/channels.ts +21 -6
  48. package/src/config.ts +138 -12
  49. package/src/connection.ts +377 -77
  50. package/src/handles.ts +32 -4
  51. package/src/index.ts +5 -0
  52. package/src/jobs.ts +63 -0
  53. package/src/logger.ts +158 -40
  54. package/src/metrics.ts +46 -1
  55. package/src/query.ts +33 -13
  56. package/src/records.ts +40 -2
  57. package/src/runtime/addon.ts +3 -2
  58. package/src/runtime/bun.ts +44 -9
  59. package/src/runtime/node.ts +30 -5
  60. package/src/runtime/pipe.ts +49 -19
  61. package/src/runtime/shared.ts +137 -16
  62. package/src/runtime.ts +31 -6
  63. package/src/session.ts +129 -30
  64. package/src/sql.ts +48 -14
  65. package/src/store.ts +81 -14
  66. package/src/wire/codec.ts +11 -0
  67. package/src/wire/frame.ts +5 -0
  68. package/src/wire/msgpack.ts +11 -4
  69. package/src/wire/protocol.ts +404 -103
package/src/connection.ts CHANGED
@@ -4,19 +4,21 @@
4
4
  // remote server.
5
5
 
6
6
  import { randomBytes } from 'node:crypto'
7
- import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
7
+ import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
8
8
  import { join, resolve } from 'node:path'
9
9
 
10
10
  import manifest from '../package.json' with { type: 'json' }
11
- import { currentSignal } from './cancel.ts'
11
+ import { checkSignal, currentSignal, unlessCancelled, withoutSignal } from './cancel.ts'
12
12
  import {
13
+ CancelledError,
13
14
  ClosedError,
14
15
  InvalidError,
15
16
  OutcomeUnknownError,
16
17
  TinystoreError,
17
18
  UnavailableError,
18
19
  } from './errors.ts'
19
- import type { PrivateChild, Runtime, TlsOptions, Transport } from './runtime.ts'
20
+ import { lastLines, notStarted } from './runtime/shared.ts'
21
+ import type { Detached, PrivateChild, Runtime, TlsOptions, Transport } from './runtime.ts'
20
22
  import {
21
23
  ConnectionLostError,
22
24
  protocol,
@@ -33,13 +35,22 @@ import { Empty, methods, StoreOptions } from './wire/protocol.ts'
33
35
  * one database:
34
36
  *
35
37
  * 'full' synced to the disk: it survives a crash of the operating
36
- * system and a power loss. What every file is unless told.
38
+ * system and a power loss. What kv, jobs, files, search and
39
+ * every database are unless told.
37
40
  * 'os' written to the operating system, synced a little later: it
38
41
  * survives the program's crash, and a power loss may take the
39
- * last commits, never the file.
42
+ * last commits, never the file. What records and metrics are
43
+ * unless told.
40
44
  */
41
45
  export type Durability = 'full' | 'os'
42
46
 
47
+ /** Refuses a count of series no store can hold, before anything leaves. */
48
+ export function checkMaxSeries(maxSeries: number | undefined): void {
49
+ if (maxSeries !== undefined && !(Number.isSafeInteger(maxSeries) && maxSeries > 0)) {
50
+ throw new InvalidError(`open: maxSeries ${maxSeries}: a whole count above 0`)
51
+ }
52
+ }
53
+
43
54
  /** Refuses a durability that is neither word, before anything leaves. */
44
55
  export function checkDurability(durability: Durability | undefined, of: string): void {
45
56
  if (durability !== undefined && durability !== 'full' && durability !== 'os') {
@@ -56,14 +67,18 @@ export function asking(dial: Dialer, dir: string, durability: Durability | undef
56
67
  if (durability === undefined) {
57
68
  return dial
58
69
  }
59
- return async () => {
60
- const connection = await dial()
70
+ return async dialling => {
71
+ const connection = await dial(dialling)
61
72
  const opened = (await connection.session.welcomed).durability
62
73
  if (opened !== durability) {
63
74
  await connection.close()
64
- const as = opened === undefined ? 'with none said' : `with durability '${opened}'`
75
+ const as =
76
+ opened === undefined
77
+ ? 'with no durability set, full but os for records and metrics'
78
+ : `with durability '${opened}'`
65
79
  throw new InvalidError(
66
- `the store in ${dir} is open ${as}, and this program asked for '${durability}'`,
80
+ `the store in ${dir} is open ${as}, and this program asked for '${durability}': ` +
81
+ `open it without durability, or start its server with --durability ${durability}`,
67
82
  )
68
83
  }
69
84
  return connection
@@ -93,8 +108,21 @@ export class Connection {
93
108
  this.#closing = closing
94
109
  }
95
110
 
96
- /** Connects, shakes hands, and gives up after the handshake's time. */
97
- static async dial(runtime: Runtime, endpoint: string, options: SessionOptions, tls?: TlsOptions) {
111
+ /**
112
+ * Connects, shakes hands, and gives up after the handshake's time, or once
113
+ * the signal aborts: before the socket connects, its connect is let go, and
114
+ * after, the socket.
115
+ */
116
+ static async dial(
117
+ runtime: Runtime,
118
+ endpoint: string,
119
+ options: SessionOptions,
120
+ tls?: TlsOptions,
121
+ signal?: AbortSignal,
122
+ ) {
123
+ if (signal?.aborted) {
124
+ throw signal.reason
125
+ }
98
126
  let session: Session | undefined
99
127
  const early: Uint8Array[] = []
100
128
  const transport = await runtime
@@ -106,10 +134,11 @@ export class Connection {
106
134
  end: err => session?.end(err),
107
135
  },
108
136
  tls,
137
+ signal,
109
138
  )
110
139
  .catch((err: unknown) => {
111
140
  // a socket that refuses fails as the platform says it; a caller sees one kind
112
- if (err instanceof TinystoreError) {
141
+ if (err instanceof TinystoreError || signal?.aborted) {
113
142
  throw err
114
143
  }
115
144
  throw new ClosedError(`cannot reach ${endpoint}: ${(err as Error).message}`)
@@ -119,14 +148,18 @@ export class Connection {
119
148
  session.receive(bytes)
120
149
  }
121
150
  const connection = new Connection(session, transport)
122
- await connection.#handshake()
151
+ await connection.#handshake(signal)
123
152
  return connection
124
153
  }
125
154
 
126
155
  /** Shakes hands over a pipe to the core in this process. */
127
- static async overPipe(session: Session, transport: Transport): Promise<Connection> {
156
+ static async overPipe(
157
+ session: Session,
158
+ transport: Transport,
159
+ signal?: AbortSignal,
160
+ ): Promise<Connection> {
128
161
  const connection = new Connection(session, transport)
129
- await connection.#handshake()
162
+ await connection.#handshake(signal)
130
163
  return connection
131
164
  }
132
165
 
@@ -135,17 +168,27 @@ export class Connection {
135
168
  * the child's exit, since until then it holds the directory: its LOCK, and
136
169
  * on Windows every file it opened, which a removal fails on.
137
170
  */
138
- static async overChild(child: PrivateChild, session: Session): Promise<Connection> {
171
+ static async overChild(
172
+ child: PrivateChild,
173
+ session: Session,
174
+ signal?: AbortSignal,
175
+ ): Promise<Connection> {
139
176
  const connection = new Connection(session, child.transport, () => child.exited)
140
- await connection.#handshake()
177
+ await connection.#handshake(signal)
141
178
  return connection
142
179
  }
143
180
 
144
- async #handshake(): Promise<void> {
181
+ // a signal that aborts ends the session with its reason, as the time does
182
+ async #handshake(signal?: AbortSignal): Promise<void> {
145
183
  const timer = setTimeout(
146
184
  () => this.session.end(new ClosedError(`no WELCOME within ${handshakeTime / 1000} s`)),
147
185
  handshakeTime,
148
186
  )
187
+ const abort = () => this.session.end(signal?.reason as Error)
188
+ if (signal?.aborted) {
189
+ abort()
190
+ }
191
+ signal?.addEventListener('abort', abort, { once: true })
149
192
  try {
150
193
  await this.session.welcomed
151
194
  } catch (err) {
@@ -153,6 +196,7 @@ export class Connection {
153
196
  throw err
154
197
  } finally {
155
198
  clearTimeout(timer)
199
+ signal?.removeEventListener('abort', abort)
156
200
  }
157
201
  this.session.onEnd(() => this.#transport.close())
158
202
  }
@@ -165,8 +209,18 @@ export class Connection {
165
209
  }
166
210
  }
167
211
 
212
+ /**
213
+ * What a dial is given: a cancel of its own, which only its link's close
214
+ * aborts, never a caller's, and where it says what it waits for, which a
215
+ * caller who gives up on it is told.
216
+ */
217
+ export interface Dialling {
218
+ readonly signal: AbortSignal
219
+ waiting(what: string): void
220
+ }
221
+
168
222
  /** Where a link dials. */
169
- export type Dialer = () => Promise<Connection>
223
+ export type Dialer = (dialling: Dialling) => Promise<Connection>
170
224
 
171
225
  /** SERVE, where a directory's sidecar says it listens. */
172
226
  interface Published {
@@ -206,15 +260,16 @@ export function sidecar(
206
260
  const log = join(absolute, 'server', 'serve.log')
207
261
  const idling = started.idle === undefined ? [] : ['--idle', `${started.idle}ms`]
208
262
  let told = false
209
- return async () => {
210
- const found = await reachServe(runtime, serve)
263
+ return async dialling => {
264
+ dialling.waiting('the sidecar starts')
265
+ const found = await reachServe(runtime, serve, dialling.signal)
211
266
  let stoppedInstance: string | undefined
212
267
  if (found !== undefined) {
213
268
  const server = (await found.connection.session.welcomed).server
214
269
  if (!older(server)) {
215
270
  return found.connection
216
271
  }
217
- if (found.sidecar && (await stopped(found.connection))) {
272
+ if (found.sidecar && (await stopped(found.connection, dialling.signal))) {
218
273
  process.stderr.write(`${replacedSidecar(server, manifest.version, dir)}\n`)
219
274
  stoppedInstance = found.instance
220
275
  } else {
@@ -227,7 +282,7 @@ export function sidecar(
227
282
  }
228
283
  const flags = [...idling, ...storeFlags(started, absolute)]
229
284
  const command = [binary(), 'serve', '--dir', absolute, '--local', '--log-file', log, ...flags]
230
- return startSidecar(runtime, serve, log, command, stoppedInstance)
285
+ return startSidecar(runtime, serve, log, command, dialling, stoppedInstance)
231
286
  }
232
287
  }
233
288
 
@@ -242,6 +297,8 @@ export interface Started {
242
297
  node?: NodeOptions | undefined
243
298
  /** measures the store into its own metrics, the machine too unless it says system: false */
244
299
  selfMetrics?: SelfMetrics | undefined
300
+ /** the metrics series the store holds at most, when not the store's own 100,000 */
301
+ maxSeries?: number | undefined
245
302
  }
246
303
 
247
304
  /**
@@ -269,7 +326,11 @@ function storeFlags(started: Started, dir: string): string[] {
269
326
  asked === undefined
270
327
  ? keyed
271
328
  : [...keyed, '--self-metrics', ...(asked.system ? [] : ['--no-system-metrics'])]
272
- return [...measured, ...nodeFlags(started.node, join(dir, 'server', 'node.toml'))]
329
+ const series =
330
+ started.maxSeries === undefined
331
+ ? measured
332
+ : [...measured, '--max-series', String(started.maxSeries)]
333
+ return [...series, ...nodeFlags(started.node, join(dir, 'server', 'node.toml'))]
273
334
  }
274
335
 
275
336
  /**
@@ -316,8 +377,12 @@ function nodeFlags(node: NodeOptions | undefined, config: string): string[] {
316
377
  if (node.advertise !== undefined) {
317
378
  settings.push(`advertise = ${JSON.stringify(node.advertise)}`)
318
379
  }
319
- mkdirSync(join(config, '..'), { recursive: true })
320
- writeFileSync(config, `${settings.join('\n')}\n`)
380
+ try {
381
+ mkdirSync(join(config, '..'), { recursive: true })
382
+ writeFileSync(config, `${settings.join('\n')}\n`)
383
+ } catch (err) {
384
+ throw new ClosedError(`cannot write the node's config ${config}: ${(err as Error).message}`)
385
+ }
321
386
  flags.push('--node-config', config)
322
387
  return flags
323
388
  }
@@ -328,48 +393,153 @@ function nodeFlags(node: NodeOptions | undefined, config: string): string[] {
328
393
  * directory held, by a winner about to publish or by a sidecar still letting
329
394
  * go, and is started again after a pause; any other exit is an error. A
330
395
  * sidecar told to stop answers for a moment after it agreed, until SERVE
331
- * goes, so the one of the instance stopped is passed over.
396
+ * goes, so the one of the instance stopped is passed over. The dial's signal
397
+ * stops it at its next turn, before it starts another, and a sidecar already
398
+ * started is left to its idle time.
332
399
  */
333
400
  async function startSidecar(
334
401
  runtime: Runtime,
335
402
  serve: string,
336
403
  log: string,
337
404
  command: string[],
405
+ dialling: Dialling,
338
406
  stoppedInstance?: string,
339
407
  ): Promise<Connection> {
340
408
  const deadline = Date.now() + startTime
341
409
  let held = false
342
410
  for (let pause = heldPause; ; pause = Math.min(pause * 2, 1000)) {
343
- const child = runtime.spawnDetached(command)
344
- let exited: number | undefined
345
- child.exited.then(code => {
346
- exited = code
347
- })
411
+ // a probe of SERVE that the close cut short finds nothing, and says
412
+ // nothing of it: before the first start and between two, start none
413
+ dialling.signal.throwIfAborted()
414
+ const child = new Spawned(runtime, command, log)
415
+ try {
416
+ const reached = await child.served(serve, deadline, pause, stoppedInstance, dialling)
417
+ if (reached !== undefined) {
418
+ return reached
419
+ }
420
+ held ||= child.exited?.code === 3
421
+ if (Date.now() >= deadline) {
422
+ const why = held
423
+ ? 'another process holds the directory but no sidecar answers'
424
+ : 'no sidecar answered'
425
+ throw new ClosedError(`${why} in ${startTime / 1000} s: ${await child.failure()}`)
426
+ }
427
+ } finally {
428
+ child.release()
429
+ }
430
+ }
431
+ }
432
+
433
+ /** A sidecar this process started, and how it ended once it has, read without waiting. */
434
+ class Spawned {
435
+ exited: { code: number; stderr: string } | undefined
436
+ #failed: { err: unknown } | undefined
437
+ readonly #runtime: Runtime
438
+ readonly #child: Detached
439
+ readonly #binary: string
440
+ readonly #log: string
441
+ /** serve.log's size before it started: the log keeps every run's lines, so this one's begin here */
442
+ readonly #logged: number
443
+
444
+ constructor(runtime: Runtime, command: string[], log: string) {
445
+ this.#runtime = runtime
446
+ this.#binary = command[0]!
447
+ this.#log = log
448
+ this.#logged = sizeOf(log)
449
+ this.#child = runtime.spawnDetached(command)
450
+ this.#child.exited.then(
451
+ ended => {
452
+ this.exited = ended
453
+ },
454
+ (err: unknown) => {
455
+ this.#failed = { err }
456
+ },
457
+ )
458
+ }
459
+
460
+ /**
461
+ * The sidecar SERVE names once one answers, this one or a winner; none
462
+ * once this one found the directory held and the pause passed, or at the
463
+ * deadline. Any other exit of this one is the error.
464
+ */
465
+ async served(
466
+ serve: string,
467
+ deadline: number,
468
+ pause: number,
469
+ stoppedInstance: string | undefined,
470
+ dialling: Dialling,
471
+ ): Promise<Connection | undefined> {
472
+ const signal = dialling.signal
348
473
  let again: number | undefined
349
474
  for (let wait = 5; Date.now() < deadline; wait = Math.min(wait * 2, 100)) {
350
- const reached = await reachServe(runtime, serve)
475
+ if (signal.aborted) {
476
+ throw signal.reason
477
+ }
478
+ const reached = await reachServe(this.#runtime, serve, signal)
351
479
  if (reached !== undefined && reached.instance !== stoppedInstance) {
352
480
  return reached.connection
353
481
  }
354
482
  await reached?.connection.close()
355
- if (exited !== undefined && exited !== 3) {
356
- throw new ClosedError(`the sidecar exited with ${exited}: ${await tail(runtime, log)}`)
483
+ if (this.#failed !== undefined) {
484
+ throw new ClosedError(
485
+ `cannot start the sidecar ${this.#binary}: ${notStarted(this.#failed.err)}`,
486
+ )
357
487
  }
358
- if (exited === 3) {
359
- held = true
360
- again ??= Date.now() + pause
488
+ if (this.exited !== undefined && this.exited.code !== 3) {
489
+ throw new ClosedError(
490
+ `the sidecar exited with ${this.exited.code}: ${await this.failure()}`,
491
+ )
492
+ }
493
+ if (this.exited?.code === 3) {
494
+ if (again === undefined) {
495
+ dialling.waiting('another process holds the directory and no sidecar answers')
496
+ again = Date.now() + pause
497
+ }
361
498
  if (Date.now() >= again) {
362
- break
499
+ return undefined
363
500
  }
364
501
  }
365
- await sleep(wait)
366
- }
367
- if (Date.now() >= deadline) {
368
- const why = held
369
- ? 'another process holds the directory but no sidecar answers'
370
- : 'no sidecar answered'
371
- throw new ClosedError(`${why} in ${startTime / 1000} s: ${await tail(runtime, log)}`)
502
+ await sleep(wait, signal)
372
503
  }
504
+ return undefined
505
+ }
506
+
507
+ /** Why it stopped without serving, as startFailure says it. */
508
+ async failure(): Promise<string> {
509
+ const stderr = this.exited?.stderr ?? this.#child.stderr()
510
+ const log =
511
+ stderr.trim() === ''
512
+ ? await this.#runtime.readFile(this.#log).catch(() => undefined)
513
+ : undefined
514
+ return startFailure(stderr, log, this.#logged)
515
+ }
516
+
517
+ /** Stops reading its stderr once the start is over. */
518
+ release(): void {
519
+ this.#child.release()
520
+ }
521
+ }
522
+
523
+ /**
524
+ * Why a sidecar that never served stopped: the last lines it wrote to
525
+ * stderr, which say a failure before its log opened, or else the lines its
526
+ * log gained since it started, when it was `logged` bytes long.
527
+ */
528
+ export function startFailure(stderr: string, log: Uint8Array | undefined, logged: number): string {
529
+ if (stderr.trim() !== '') {
530
+ return lastLines(stderr)
531
+ }
532
+ // a log shorter than it was is another file, every line of it new
533
+ const from = log === undefined || log.length < logged ? 0 : logged
534
+ const gained = log === undefined ? '' : new TextDecoder().decode(log.subarray(from))
535
+ return gained.trim() === '' ? 'it wrote no log' : lastLines(gained)
536
+ }
537
+
538
+ function sizeOf(path: string): number {
539
+ try {
540
+ return statSync(path).size
541
+ } catch {
542
+ return 0
373
543
  }
374
544
  }
375
545
 
@@ -377,9 +547,9 @@ async function startSidecar(
377
547
  * Asks a sidecar to stop as tinystore stop does, closing the connection once
378
548
  * it has answered; false when it refuses, and the connection stays open.
379
549
  */
380
- async function stopped(connection: Connection): Promise<boolean> {
550
+ async function stopped(connection: Connection, signal: AbortSignal): Promise<boolean> {
381
551
  try {
382
- await connection.session.call(methods['server.stop'], Empty.encode({}))
552
+ await connection.session.call(methods['server.stop'], Empty.encode({}), signal)
383
553
  } catch {
384
554
  return false
385
555
  }
@@ -458,6 +628,7 @@ function compareReleases(a: Release, b: Release): number {
458
628
  async function reachServe(
459
629
  runtime: Runtime,
460
630
  serve: string,
631
+ signal: AbortSignal,
461
632
  ): Promise<{ connection: Connection; sidecar: boolean; instance: string } | undefined> {
462
633
  let published: Published
463
634
  try {
@@ -475,28 +646,34 @@ async function reachServe(
475
646
  return undefined
476
647
  }
477
648
  try {
478
- const connection = await Connection.dial(runtime, endpoint, {
649
+ const asked = {
479
650
  client: runtime.client,
480
651
  secret: new Uint8Array(secret),
481
652
  challenge: new Uint8Array(randomBytes(16)),
482
- })
653
+ }
654
+ const connection = await Connection.dial(runtime, endpoint, asked, undefined, signal)
483
655
  return { connection, sidecar: published.sidecar === true, instance: published.instance }
484
656
  } catch {
485
657
  return undefined
486
658
  }
487
659
  }
488
660
 
489
- function sleep(ms: number): Promise<void> {
490
- return new Promise(resolve => setTimeout(resolve, ms))
491
- }
492
-
493
- async function tail(runtime: Runtime, log: string): Promise<string> {
494
- const text = await runtime.readFile(log).catch(() => undefined)
495
- if (text === undefined) {
496
- return 'it wrote no log'
661
+ /** A pause, which the signal ends early with its reason. */
662
+ function sleep(ms: number, signal: AbortSignal): Promise<void> {
663
+ if (signal.aborted) {
664
+ return Promise.reject(signal.reason)
497
665
  }
498
- const lines = new TextDecoder().decode(text).trimEnd().split('\n')
499
- return lines.slice(-5).join('\n')
666
+ return new Promise((resolve, reject) => {
667
+ const abort = () => {
668
+ clearTimeout(timer)
669
+ reject(signal.reason)
670
+ }
671
+ const timer = setTimeout(() => {
672
+ signal.removeEventListener('abort', abort)
673
+ resolve()
674
+ }, ms)
675
+ signal.addEventListener('abort', abort, { once: true })
676
+ })
500
677
  }
501
678
 
502
679
  /** A private child: tinystore serve --stdio, living and dying with this process. */
@@ -509,7 +686,8 @@ export function privateChild(
509
686
  ): Dialer {
510
687
  // a test's clock starts where the first child's did, and a child started again starts it there
511
688
  const clocked = clock === undefined ? [] : ['--clock', clock.toISOString()]
512
- return async () => {
689
+ return async dialling => {
690
+ dialling.waiting('the private server starts')
513
691
  let session: Session | undefined
514
692
  const argv = [
515
693
  binary(),
@@ -520,10 +698,14 @@ export function privateChild(
520
698
  ...clocked,
521
699
  ...storeFlags(started, resolve(dir)),
522
700
  ]
523
- const child = runtime.spawnPrivate(argv, {
524
- data: bytes => session?.receive(bytes),
525
- end: err => session?.end(err),
526
- })
701
+ const child = await runtime
702
+ .spawnPrivate(argv, {
703
+ data: bytes => session?.receive(bytes),
704
+ end: err => session?.end(err),
705
+ })
706
+ .catch((err: unknown) => {
707
+ throw new ClosedError(`cannot start the private server ${argv[0]}: ${notStarted(err)}`)
708
+ })
527
709
  session = new Session(bytes => child.transport.write(bytes), { client: runtime.client })
528
710
  session.onEnd(() => {
529
711
  child.transport.close()
@@ -532,7 +714,7 @@ export function privateChild(
532
714
  child.exited.finally(() => clearTimeout(killer))
533
715
  })
534
716
  try {
535
- return await Connection.overChild(child, session)
717
+ return await Connection.overChild(child, session, dialling.signal)
536
718
  } catch (err) {
537
719
  child.kill()
538
720
  throw new ClosedError(`the private server did not start: ${(err as Error).message}`)
@@ -573,8 +755,10 @@ export function embedded(
573
755
  synchronousWith: node?.synchronousWith ?? [],
574
756
  selfMetrics: selfMetricsOf(started.selfMetrics) !== undefined,
575
757
  withoutSystem: selfMetricsOf(started.selfMetrics)?.system === false,
758
+ maxSeries: started.maxSeries,
576
759
  })
577
- return async () => {
760
+ return async dialling => {
761
+ dialling.waiting('the store opens')
578
762
  let session: Session | undefined
579
763
  const end = (err: Error) => session?.end(err)
580
764
  const transport =
@@ -585,16 +769,20 @@ export function embedded(
585
769
  })
586
770
  : (await import('./runtime/pipe.ts')).openPipe(library(), resolve(dir), options, {
587
771
  frames: (bytes, length) => session?.read(bytes, length) ?? length,
772
+ frame: bytes => session?.read(bytes, bytes.length, true),
588
773
  end,
589
774
  })
590
775
  session = new Session(bytes => transport.write(bytes), { client: runtime.client })
591
- return await Connection.overPipe(session, transport)
776
+ return await Connection.overPipe(session, transport, dialling.signal)
592
777
  }
593
778
  }
594
779
 
595
780
  /** A remote server: tls:// checks its certificate before the token leaves; tcp:// does not. */
596
781
  export function remote(runtime: Runtime, url: string, token: string, tls?: TlsOptions): Dialer {
597
- return () => Connection.dial(runtime, url, { client: runtime.client, token }, tls)
782
+ return dialling => {
783
+ dialling.waiting('the server has not answered')
784
+ return Connection.dial(runtime, url, { client: runtime.client, token }, tls, dialling.signal)
785
+ }
598
786
  }
599
787
 
600
788
  /** What a call may do when its connection is lost: go again, or say its outcome is unknown. */
@@ -608,16 +796,36 @@ export type Idempotence = 'read' | 'write'
608
796
  */
609
797
  export class Link {
610
798
  readonly #dial: Dialer
799
+ readonly #followers = new Set<Stream>()
611
800
  #current: Promise<Connection> | undefined
612
801
  #dialled: Connection | undefined
802
+ /** the cancel of the dial under way, which only close aborts */
803
+ #dialling: AbortController | undefined
804
+ /** what the dial under way waits for, which a caller who gives up on it is told */
805
+ #waiting = 'the store has not answered'
613
806
  #closed = false
614
807
 
615
808
  constructor(dial: Dialer) {
616
809
  this.#dial = dial
617
810
  }
618
811
 
619
- /** The connection a call goes on. */
620
- connection(): Promise<Connection> {
812
+ /**
813
+ * The connection a call goes on. A caller whose signal aborts stops
814
+ * waiting at once, CancelledError naming what the dial waits for, and
815
+ * the dial goes on for the others.
816
+ */
817
+ connection(signal?: AbortSignal, of = 'a call'): Promise<Connection> {
818
+ if (this.#closed) {
819
+ return Promise.reject(new ClosedError('the store is closed'))
820
+ }
821
+ return unlessCancelled(
822
+ this.#connected(),
823
+ signal,
824
+ () => new CancelledError(`${of}: cancelled while ${this.#waiting}`),
825
+ )
826
+ }
827
+
828
+ #connected(): Promise<Connection> {
621
829
  if (this.#closed) {
622
830
  return Promise.reject(new ClosedError('the store is closed'))
623
831
  }
@@ -640,10 +848,15 @@ export class Link {
640
848
  // one dial at a time: every caller that found the same dead connection
641
849
  // waits for the one new one
642
850
  #redial(dead: Promise<Connection> | undefined): Promise<Connection> {
851
+ // a caller that waited on a dial the close let go of finds the link
852
+ // closed: a dial now would be a connection nothing closes
853
+ if (this.#closed) {
854
+ return Promise.reject(new ClosedError('the store is closed'))
855
+ }
643
856
  if (this.#current !== dead && this.#current !== undefined) {
644
- return this.connection()
857
+ return this.#connected()
645
858
  }
646
- const dialled = this.#dial()
859
+ const dialled = this.#dialAnew()
647
860
  this.#current = dialled
648
861
  this.#dialled = undefined
649
862
  dialled.then(
@@ -661,6 +874,45 @@ export class Link {
661
874
  return dialled
662
875
  }
663
876
 
877
+ /**
878
+ * A dial of the link's own, under a cancel that only close aborts: once
879
+ * it has, the dial fails with the close's ClosedError whatever it was
880
+ * doing, and a connection it made after is closed, since nobody takes it.
881
+ */
882
+ #dialAnew(): Promise<Connection> {
883
+ const controller = new AbortController()
884
+ this.#dialling = controller
885
+ this.#waiting = 'the store has not answered'
886
+ const dialling: Dialling = {
887
+ signal: controller.signal,
888
+ waiting: what => {
889
+ if (this.#dialling === controller) {
890
+ this.#waiting = what
891
+ }
892
+ },
893
+ }
894
+ const settled = () => {
895
+ if (this.#dialling === controller) {
896
+ this.#dialling = undefined
897
+ }
898
+ }
899
+ // no caller's withSignal reaches a dial that all of them share
900
+ return withoutSignal(() => this.#dial(dialling)).then(
901
+ async connection => {
902
+ settled()
903
+ if (!controller.signal.aborted) {
904
+ return connection
905
+ }
906
+ await connection.close()
907
+ throw controller.signal.reason
908
+ },
909
+ (err: unknown) => {
910
+ settled()
911
+ throw controller.signal.aborted ? controller.signal.reason : err
912
+ },
913
+ )
914
+ }
915
+
664
916
  /**
665
917
  * Runs a call on the link's connection. build makes its REQUEST's body for
666
918
  * that connection, whose handles it may open; run sends it.
@@ -670,9 +922,10 @@ export class Link {
670
922
  attempt: (connection: Connection) => Promise<T>,
671
923
  signal?: AbortSignal,
672
924
  ): Promise<T> {
925
+ const given = signal ?? currentSignal()
673
926
  for (let tries = 0; ; tries++) {
674
- ;(signal ?? currentSignal())?.throwIfAborted()
675
- const connection = await this.connection()
927
+ checkSignal(given)
928
+ const connection = await this.connection(given)
676
929
  try {
677
930
  return await attempt(connection)
678
931
  } catch (err) {
@@ -684,9 +937,40 @@ export class Link {
684
937
  }
685
938
  }
686
939
 
687
- /** Closes the connection and every one to come. */
940
+ /**
941
+ * Keeps a stream that follows the store until it closes, a subscription's,
942
+ * a loop's, a tail's or a watch's, for close to cancel; it returns what
943
+ * lets the stream go. Once the link is closed it cancels the stream at
944
+ * once.
945
+ */
946
+ follow(stream: Stream): () => void {
947
+ if (this.#closed) {
948
+ stream.cancel(new ClosedError('the store is closed'))
949
+ return () => {}
950
+ }
951
+ this.#followers.add(stream)
952
+ return () => this.#followers.delete(stream)
953
+ }
954
+
955
+ /**
956
+ * Closes the connection and every one to come. Each stream that follows
957
+ * the store is cancelled first, and its end waited for, a moment at most:
958
+ * one the server still ran would keep a private child, or a sidecar's
959
+ * connection, draining for ten seconds. A dial under way stops at its next
960
+ * wait, and every call waiting on it fails ClosedError.
961
+ */
688
962
  async close(): Promise<void> {
689
963
  this.#closed = true
964
+ this.#dialling?.abort(new ClosedError('the store is closed'))
965
+ const followers = [...this.#followers]
966
+ this.#followers.clear()
967
+ for (const stream of followers) {
968
+ stream.cancel(new ClosedError('the store is closed'))
969
+ }
970
+ await within(
971
+ followerWait,
972
+ followers.map(stream => stream.finishing()),
973
+ )
690
974
  const current = this.#current
691
975
  this.#current = undefined
692
976
  this.#dialled = undefined
@@ -697,6 +981,22 @@ export class Link {
697
981
  }
698
982
  }
699
983
 
984
+ /** How long a store's close waits for the server's end of a stream it cancelled. */
985
+ const followerWait = 2_000
986
+
987
+ /** Waits for every promise, `ms` at most. */
988
+ async function within(ms: number, promises: Promise<unknown>[]): Promise<void> {
989
+ if (promises.length === 0) {
990
+ return
991
+ }
992
+ let timer: ReturnType<typeof setTimeout> | undefined
993
+ const late = new Promise<void>(resolve => {
994
+ timer = setTimeout(resolve, ms)
995
+ })
996
+ await Promise.race([Promise.all(promises), late])
997
+ clearTimeout(timer)
998
+ }
999
+
700
1000
  /**
701
1001
  * Whether a call that failed goes on another connection: one whose REQUEST
702
1002
  * had not left, and a read that had. A write that had is OutcomeUnknownError,
@@ -734,7 +1034,7 @@ export async function download(
734
1034
  body: Uint8Array,
735
1035
  signal?: AbortSignal,
736
1036
  ): Promise<Downloaded> {
737
- signal?.throwIfAborted()
1037
+ checkSignal(signal)
738
1038
  const stream = await connection.session.open(method, body, true)
739
1039
  const unwatch = watch(signal, stream)
740
1040
  try {