@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
@@ -3,13 +3,20 @@
3
3
  // directory's sidecar, found through SERVE or started, a private child, or a
4
4
  // remote server.
5
5
  import { randomBytes } from 'node:crypto';
6
- import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
6
+ import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
7
7
  import { join, resolve } from 'node:path';
8
8
  import manifest from '../package.json' with { type: 'json' };
9
- import { currentSignal } from './cancel.js';
10
- import { ClosedError, InvalidError, OutcomeUnknownError, TinystoreError, UnavailableError, } from './errors.js';
9
+ import { checkSignal, currentSignal, unlessCancelled, withoutSignal } from './cancel.js';
10
+ import { CancelledError, ClosedError, InvalidError, OutcomeUnknownError, TinystoreError, UnavailableError, } from './errors.js';
11
+ import { lastLines, notStarted } from './runtime/shared.js';
11
12
  import { ConnectionLostError, protocol, Session, watch, } from './session.js';
12
13
  import { Empty, methods, StoreOptions } from './wire/protocol.js';
14
+ /** Refuses a count of series no store can hold, before anything leaves. */
15
+ export function checkMaxSeries(maxSeries) {
16
+ if (maxSeries !== undefined && !(Number.isSafeInteger(maxSeries) && maxSeries > 0)) {
17
+ throw new InvalidError(`open: maxSeries ${maxSeries}: a whole count above 0`);
18
+ }
19
+ }
13
20
  /** Refuses a durability that is neither word, before anything leaves. */
14
21
  export function checkDurability(durability, of) {
15
22
  if (durability !== undefined && durability !== 'full' && durability !== 'os') {
@@ -25,13 +32,16 @@ export function asking(dial, dir, durability) {
25
32
  if (durability === undefined) {
26
33
  return dial;
27
34
  }
28
- return async () => {
29
- const connection = await dial();
35
+ return async (dialling) => {
36
+ const connection = await dial(dialling);
30
37
  const opened = (await connection.session.welcomed).durability;
31
38
  if (opened !== durability) {
32
39
  await connection.close();
33
- const as = opened === undefined ? 'with none said' : `with durability '${opened}'`;
34
- throw new InvalidError(`the store in ${dir} is open ${as}, and this program asked for '${durability}'`);
40
+ const as = opened === undefined
41
+ ? 'with no durability set, full but os for records and metrics'
42
+ : `with durability '${opened}'`;
43
+ throw new InvalidError(`the store in ${dir} is open ${as}, and this program asked for '${durability}': ` +
44
+ `open it without durability, or start its server with --durability ${durability}`);
35
45
  }
36
46
  return connection;
37
47
  };
@@ -52,18 +62,25 @@ export class Connection {
52
62
  this.#transport = transport;
53
63
  this.#closing = closing;
54
64
  }
55
- /** Connects, shakes hands, and gives up after the handshake's time. */
56
- static async dial(runtime, endpoint, options, tls) {
65
+ /**
66
+ * Connects, shakes hands, and gives up after the handshake's time, or once
67
+ * the signal aborts: before the socket connects, its connect is let go, and
68
+ * after, the socket.
69
+ */
70
+ static async dial(runtime, endpoint, options, tls, signal) {
71
+ if (signal?.aborted) {
72
+ throw signal.reason;
73
+ }
57
74
  let session;
58
75
  const early = [];
59
76
  const transport = await runtime
60
77
  .connect(endpoint, {
61
78
  data: bytes => session === undefined ? early.push(bytes.slice()) : session.receive(bytes),
62
79
  end: err => session?.end(err),
63
- }, tls)
80
+ }, tls, signal)
64
81
  .catch((err) => {
65
82
  // a socket that refuses fails as the platform says it; a caller sees one kind
66
- if (err instanceof TinystoreError) {
83
+ if (err instanceof TinystoreError || signal?.aborted) {
67
84
  throw err;
68
85
  }
69
86
  throw new ClosedError(`cannot reach ${endpoint}: ${err.message}`);
@@ -73,13 +90,13 @@ export class Connection {
73
90
  session.receive(bytes);
74
91
  }
75
92
  const connection = new Connection(session, transport);
76
- await connection.#handshake();
93
+ await connection.#handshake(signal);
77
94
  return connection;
78
95
  }
79
96
  /** Shakes hands over a pipe to the core in this process. */
80
- static async overPipe(session, transport) {
97
+ static async overPipe(session, transport, signal) {
81
98
  const connection = new Connection(session, transport);
82
- await connection.#handshake();
99
+ await connection.#handshake(signal);
83
100
  return connection;
84
101
  }
85
102
  /**
@@ -87,13 +104,19 @@ export class Connection {
87
104
  * the child's exit, since until then it holds the directory: its LOCK, and
88
105
  * on Windows every file it opened, which a removal fails on.
89
106
  */
90
- static async overChild(child, session) {
107
+ static async overChild(child, session, signal) {
91
108
  const connection = new Connection(session, child.transport, () => child.exited);
92
- await connection.#handshake();
109
+ await connection.#handshake(signal);
93
110
  return connection;
94
111
  }
95
- async #handshake() {
112
+ // a signal that aborts ends the session with its reason, as the time does
113
+ async #handshake(signal) {
96
114
  const timer = setTimeout(() => this.session.end(new ClosedError(`no WELCOME within ${handshakeTime / 1000} s`)), handshakeTime);
115
+ const abort = () => this.session.end(signal?.reason);
116
+ if (signal?.aborted) {
117
+ abort();
118
+ }
119
+ signal?.addEventListener('abort', abort, { once: true });
97
120
  try {
98
121
  await this.session.welcomed;
99
122
  }
@@ -103,6 +126,7 @@ export class Connection {
103
126
  }
104
127
  finally {
105
128
  clearTimeout(timer);
129
+ signal?.removeEventListener('abort', abort);
106
130
  }
107
131
  this.session.onEnd(() => this.#transport.close());
108
132
  }
@@ -131,15 +155,16 @@ export function sidecar(runtime, dir, binary, started = {}, older = server => ol
131
155
  const log = join(absolute, 'server', 'serve.log');
132
156
  const idling = started.idle === undefined ? [] : ['--idle', `${started.idle}ms`];
133
157
  let told = false;
134
- return async () => {
135
- const found = await reachServe(runtime, serve);
158
+ return async (dialling) => {
159
+ dialling.waiting('the sidecar starts');
160
+ const found = await reachServe(runtime, serve, dialling.signal);
136
161
  let stoppedInstance;
137
162
  if (found !== undefined) {
138
163
  const server = (await found.connection.session.welcomed).server;
139
164
  if (!older(server)) {
140
165
  return found.connection;
141
166
  }
142
- if (found.sidecar && (await stopped(found.connection))) {
167
+ if (found.sidecar && (await stopped(found.connection, dialling.signal))) {
143
168
  process.stderr.write(`${replacedSidecar(server, manifest.version, dir)}\n`);
144
169
  stoppedInstance = found.instance;
145
170
  }
@@ -153,7 +178,7 @@ export function sidecar(runtime, dir, binary, started = {}, older = server => ol
153
178
  }
154
179
  const flags = [...idling, ...storeFlags(started, absolute)];
155
180
  const command = [binary(), 'serve', '--dir', absolute, '--local', '--log-file', log, ...flags];
156
- return startSidecar(runtime, serve, log, command, stoppedInstance);
181
+ return startSidecar(runtime, serve, log, command, dialling, stoppedInstance);
157
182
  };
158
183
  }
159
184
  /** What selfMetrics asks for, none when it asks for nothing. */
@@ -172,7 +197,10 @@ function storeFlags(started, dir) {
172
197
  const measured = asked === undefined
173
198
  ? keyed
174
199
  : [...keyed, '--self-metrics', ...(asked.system ? [] : ['--no-system-metrics'])];
175
- return [...measured, ...nodeFlags(started.node, join(dir, 'server', 'node.toml'))];
200
+ const series = started.maxSeries === undefined
201
+ ? measured
202
+ : [...measured, '--max-series', String(started.maxSeries)];
203
+ return [...series, ...nodeFlags(started.node, join(dir, 'server', 'node.toml'))];
176
204
  }
177
205
  /**
178
206
  * A node's options as `tinystore serve` takes them: where it listens and the
@@ -216,8 +244,13 @@ function nodeFlags(node, config) {
216
244
  if (node.advertise !== undefined) {
217
245
  settings.push(`advertise = ${JSON.stringify(node.advertise)}`);
218
246
  }
219
- mkdirSync(join(config, '..'), { recursive: true });
220
- writeFileSync(config, `${settings.join('\n')}\n`);
247
+ try {
248
+ mkdirSync(join(config, '..'), { recursive: true });
249
+ writeFileSync(config, `${settings.join('\n')}\n`);
250
+ }
251
+ catch (err) {
252
+ throw new ClosedError(`cannot write the node's config ${config}: ${err.message}`);
253
+ }
221
254
  flags.push('--node-config', config);
222
255
  return flags;
223
256
  }
@@ -227,51 +260,136 @@ function nodeFlags(node, config) {
227
260
  * directory held, by a winner about to publish or by a sidecar still letting
228
261
  * go, and is started again after a pause; any other exit is an error. A
229
262
  * sidecar told to stop answers for a moment after it agreed, until SERVE
230
- * goes, so the one of the instance stopped is passed over.
263
+ * goes, so the one of the instance stopped is passed over. The dial's signal
264
+ * stops it at its next turn, before it starts another, and a sidecar already
265
+ * started is left to its idle time.
231
266
  */
232
- async function startSidecar(runtime, serve, log, command, stoppedInstance) {
267
+ async function startSidecar(runtime, serve, log, command, dialling, stoppedInstance) {
233
268
  const deadline = Date.now() + startTime;
234
269
  let held = false;
235
270
  for (let pause = heldPause;; pause = Math.min(pause * 2, 1000)) {
236
- const child = runtime.spawnDetached(command);
237
- let exited;
238
- child.exited.then(code => {
239
- exited = code;
271
+ // a probe of SERVE that the close cut short finds nothing, and says
272
+ // nothing of it: before the first start and between two, start none
273
+ dialling.signal.throwIfAborted();
274
+ const child = new Spawned(runtime, command, log);
275
+ try {
276
+ const reached = await child.served(serve, deadline, pause, stoppedInstance, dialling);
277
+ if (reached !== undefined) {
278
+ return reached;
279
+ }
280
+ held ||= child.exited?.code === 3;
281
+ if (Date.now() >= deadline) {
282
+ const why = held
283
+ ? 'another process holds the directory but no sidecar answers'
284
+ : 'no sidecar answered';
285
+ throw new ClosedError(`${why} in ${startTime / 1000} s: ${await child.failure()}`);
286
+ }
287
+ }
288
+ finally {
289
+ child.release();
290
+ }
291
+ }
292
+ }
293
+ /** A sidecar this process started, and how it ended once it has, read without waiting. */
294
+ class Spawned {
295
+ exited;
296
+ #failed;
297
+ #runtime;
298
+ #child;
299
+ #binary;
300
+ #log;
301
+ /** serve.log's size before it started: the log keeps every run's lines, so this one's begin here */
302
+ #logged;
303
+ constructor(runtime, command, log) {
304
+ this.#runtime = runtime;
305
+ this.#binary = command[0];
306
+ this.#log = log;
307
+ this.#logged = sizeOf(log);
308
+ this.#child = runtime.spawnDetached(command);
309
+ this.#child.exited.then(ended => {
310
+ this.exited = ended;
311
+ }, (err) => {
312
+ this.#failed = { err };
240
313
  });
314
+ }
315
+ /**
316
+ * The sidecar SERVE names once one answers, this one or a winner; none
317
+ * once this one found the directory held and the pause passed, or at the
318
+ * deadline. Any other exit of this one is the error.
319
+ */
320
+ async served(serve, deadline, pause, stoppedInstance, dialling) {
321
+ const signal = dialling.signal;
241
322
  let again;
242
323
  for (let wait = 5; Date.now() < deadline; wait = Math.min(wait * 2, 100)) {
243
- const reached = await reachServe(runtime, serve);
324
+ if (signal.aborted) {
325
+ throw signal.reason;
326
+ }
327
+ const reached = await reachServe(this.#runtime, serve, signal);
244
328
  if (reached !== undefined && reached.instance !== stoppedInstance) {
245
329
  return reached.connection;
246
330
  }
247
331
  await reached?.connection.close();
248
- if (exited !== undefined && exited !== 3) {
249
- throw new ClosedError(`the sidecar exited with ${exited}: ${await tail(runtime, log)}`);
332
+ if (this.#failed !== undefined) {
333
+ throw new ClosedError(`cannot start the sidecar ${this.#binary}: ${notStarted(this.#failed.err)}`);
334
+ }
335
+ if (this.exited !== undefined && this.exited.code !== 3) {
336
+ throw new ClosedError(`the sidecar exited with ${this.exited.code}: ${await this.failure()}`);
250
337
  }
251
- if (exited === 3) {
252
- held = true;
253
- again ??= Date.now() + pause;
338
+ if (this.exited?.code === 3) {
339
+ if (again === undefined) {
340
+ dialling.waiting('another process holds the directory and no sidecar answers');
341
+ again = Date.now() + pause;
342
+ }
254
343
  if (Date.now() >= again) {
255
- break;
344
+ return undefined;
256
345
  }
257
346
  }
258
- await sleep(wait);
259
- }
260
- if (Date.now() >= deadline) {
261
- const why = held
262
- ? 'another process holds the directory but no sidecar answers'
263
- : 'no sidecar answered';
264
- throw new ClosedError(`${why} in ${startTime / 1000} s: ${await tail(runtime, log)}`);
347
+ await sleep(wait, signal);
265
348
  }
349
+ return undefined;
350
+ }
351
+ /** Why it stopped without serving, as startFailure says it. */
352
+ async failure() {
353
+ const stderr = this.exited?.stderr ?? this.#child.stderr();
354
+ const log = stderr.trim() === ''
355
+ ? await this.#runtime.readFile(this.#log).catch(() => undefined)
356
+ : undefined;
357
+ return startFailure(stderr, log, this.#logged);
358
+ }
359
+ /** Stops reading its stderr once the start is over. */
360
+ release() {
361
+ this.#child.release();
362
+ }
363
+ }
364
+ /**
365
+ * Why a sidecar that never served stopped: the last lines it wrote to
366
+ * stderr, which say a failure before its log opened, or else the lines its
367
+ * log gained since it started, when it was `logged` bytes long.
368
+ */
369
+ export function startFailure(stderr, log, logged) {
370
+ if (stderr.trim() !== '') {
371
+ return lastLines(stderr);
372
+ }
373
+ // a log shorter than it was is another file, every line of it new
374
+ const from = log === undefined || log.length < logged ? 0 : logged;
375
+ const gained = log === undefined ? '' : new TextDecoder().decode(log.subarray(from));
376
+ return gained.trim() === '' ? 'it wrote no log' : lastLines(gained);
377
+ }
378
+ function sizeOf(path) {
379
+ try {
380
+ return statSync(path).size;
381
+ }
382
+ catch {
383
+ return 0;
266
384
  }
267
385
  }
268
386
  /**
269
387
  * Asks a sidecar to stop as tinystore stop does, closing the connection once
270
388
  * it has answered; false when it refuses, and the connection stays open.
271
389
  */
272
- async function stopped(connection) {
390
+ async function stopped(connection, signal) {
273
391
  try {
274
- await connection.session.call(methods['server.stop'], Empty.encode({}));
392
+ await connection.session.call(methods['server.stop'], Empty.encode({}), signal);
275
393
  }
276
394
  catch {
277
395
  return false;
@@ -333,7 +451,7 @@ function compareReleases(a, b) {
333
451
  return a.pre.length - b.pre.length;
334
452
  }
335
453
  /** The sidecar SERVE names, once its proof checks; undefined on any failure. */
336
- async function reachServe(runtime, serve) {
454
+ async function reachServe(runtime, serve, signal) {
337
455
  let published;
338
456
  try {
339
457
  const text = await runtime.readFile(serve);
@@ -351,33 +469,41 @@ async function reachServe(runtime, serve) {
351
469
  return undefined;
352
470
  }
353
471
  try {
354
- const connection = await Connection.dial(runtime, endpoint, {
472
+ const asked = {
355
473
  client: runtime.client,
356
474
  secret: new Uint8Array(secret),
357
475
  challenge: new Uint8Array(randomBytes(16)),
358
- });
476
+ };
477
+ const connection = await Connection.dial(runtime, endpoint, asked, undefined, signal);
359
478
  return { connection, sidecar: published.sidecar === true, instance: published.instance };
360
479
  }
361
480
  catch {
362
481
  return undefined;
363
482
  }
364
483
  }
365
- function sleep(ms) {
366
- return new Promise(resolve => setTimeout(resolve, ms));
367
- }
368
- async function tail(runtime, log) {
369
- const text = await runtime.readFile(log).catch(() => undefined);
370
- if (text === undefined) {
371
- return 'it wrote no log';
484
+ /** A pause, which the signal ends early with its reason. */
485
+ function sleep(ms, signal) {
486
+ if (signal.aborted) {
487
+ return Promise.reject(signal.reason);
372
488
  }
373
- const lines = new TextDecoder().decode(text).trimEnd().split('\n');
374
- return lines.slice(-5).join('\n');
489
+ return new Promise((resolve, reject) => {
490
+ const abort = () => {
491
+ clearTimeout(timer);
492
+ reject(signal.reason);
493
+ };
494
+ const timer = setTimeout(() => {
495
+ signal.removeEventListener('abort', abort);
496
+ resolve();
497
+ }, ms);
498
+ signal.addEventListener('abort', abort, { once: true });
499
+ });
375
500
  }
376
501
  /** A private child: tinystore serve --stdio, living and dying with this process. */
377
502
  export function privateChild(runtime, dir, binary, clock, started = {}) {
378
503
  // a test's clock starts where the first child's did, and a child started again starts it there
379
504
  const clocked = clock === undefined ? [] : ['--clock', clock.toISOString()];
380
- return async () => {
505
+ return async (dialling) => {
506
+ dialling.waiting('the private server starts');
381
507
  let session;
382
508
  const argv = [
383
509
  binary(),
@@ -388,9 +514,13 @@ export function privateChild(runtime, dir, binary, clock, started = {}) {
388
514
  ...clocked,
389
515
  ...storeFlags(started, resolve(dir)),
390
516
  ];
391
- const child = runtime.spawnPrivate(argv, {
517
+ const child = await runtime
518
+ .spawnPrivate(argv, {
392
519
  data: bytes => session?.receive(bytes),
393
520
  end: err => session?.end(err),
521
+ })
522
+ .catch((err) => {
523
+ throw new ClosedError(`cannot start the private server ${argv[0]}: ${notStarted(err)}`);
394
524
  });
395
525
  session = new Session(bytes => child.transport.write(bytes), { client: runtime.client });
396
526
  session.onEnd(() => {
@@ -400,7 +530,7 @@ export function privateChild(runtime, dir, binary, clock, started = {}) {
400
530
  child.exited.finally(() => clearTimeout(killer));
401
531
  });
402
532
  try {
403
- return await Connection.overChild(child, session);
533
+ return await Connection.overChild(child, session, dialling.signal);
404
534
  }
405
535
  catch (err) {
406
536
  child.kill();
@@ -434,8 +564,10 @@ export function embedded(runtime, dir, library, started = {}) {
434
564
  synchronousWith: node?.synchronousWith ?? [],
435
565
  selfMetrics: selfMetricsOf(started.selfMetrics) !== undefined,
436
566
  withoutSystem: selfMetricsOf(started.selfMetrics)?.system === false,
567
+ maxSeries: started.maxSeries,
437
568
  });
438
- return async () => {
569
+ return async (dialling) => {
570
+ dialling.waiting('the store opens');
439
571
  let session;
440
572
  const end = (err) => session?.end(err);
441
573
  const transport = typeof Bun === 'undefined'
@@ -445,15 +577,19 @@ export function embedded(runtime, dir, library, started = {}) {
445
577
  })
446
578
  : (await import('./runtime/pipe.js')).openPipe(library(), resolve(dir), options, {
447
579
  frames: (bytes, length) => session?.read(bytes, length) ?? length,
580
+ frame: bytes => session?.read(bytes, bytes.length, true),
448
581
  end,
449
582
  });
450
583
  session = new Session(bytes => transport.write(bytes), { client: runtime.client });
451
- return await Connection.overPipe(session, transport);
584
+ return await Connection.overPipe(session, transport, dialling.signal);
452
585
  };
453
586
  }
454
587
  /** A remote server: tls:// checks its certificate before the token leaves; tcp:// does not. */
455
588
  export function remote(runtime, url, token, tls) {
456
- return () => Connection.dial(runtime, url, { client: runtime.client, token }, tls);
589
+ return dialling => {
590
+ dialling.waiting('the server has not answered');
591
+ return Connection.dial(runtime, url, { client: runtime.client, token }, tls, dialling.signal);
592
+ };
457
593
  }
458
594
  /**
459
595
  * Gives calls a connection, dialling again once the last one ended, and runs
@@ -463,14 +599,29 @@ export function remote(runtime, url, token, tls) {
463
599
  */
464
600
  export class Link {
465
601
  #dial;
602
+ #followers = new Set();
466
603
  #current;
467
604
  #dialled;
605
+ /** the cancel of the dial under way, which only close aborts */
606
+ #dialling;
607
+ /** what the dial under way waits for, which a caller who gives up on it is told */
608
+ #waiting = 'the store has not answered';
468
609
  #closed = false;
469
610
  constructor(dial) {
470
611
  this.#dial = dial;
471
612
  }
472
- /** The connection a call goes on. */
473
- connection() {
613
+ /**
614
+ * The connection a call goes on. A caller whose signal aborts stops
615
+ * waiting at once, CancelledError naming what the dial waits for, and
616
+ * the dial goes on for the others.
617
+ */
618
+ connection(signal, of = 'a call') {
619
+ if (this.#closed) {
620
+ return Promise.reject(new ClosedError('the store is closed'));
621
+ }
622
+ return unlessCancelled(this.#connected(), signal, () => new CancelledError(`${of}: cancelled while ${this.#waiting}`));
623
+ }
624
+ #connected() {
474
625
  if (this.#closed) {
475
626
  return Promise.reject(new ClosedError('the store is closed'));
476
627
  }
@@ -488,10 +639,15 @@ export class Link {
488
639
  // one dial at a time: every caller that found the same dead connection
489
640
  // waits for the one new one
490
641
  #redial(dead) {
642
+ // a caller that waited on a dial the close let go of finds the link
643
+ // closed: a dial now would be a connection nothing closes
644
+ if (this.#closed) {
645
+ return Promise.reject(new ClosedError('the store is closed'));
646
+ }
491
647
  if (this.#current !== dead && this.#current !== undefined) {
492
- return this.connection();
648
+ return this.#connected();
493
649
  }
494
- const dialled = this.#dial();
650
+ const dialled = this.#dialAnew();
495
651
  this.#current = dialled;
496
652
  this.#dialled = undefined;
497
653
  dialled.then(connection => {
@@ -505,15 +661,50 @@ export class Link {
505
661
  });
506
662
  return dialled;
507
663
  }
664
+ /**
665
+ * A dial of the link's own, under a cancel that only close aborts: once
666
+ * it has, the dial fails with the close's ClosedError whatever it was
667
+ * doing, and a connection it made after is closed, since nobody takes it.
668
+ */
669
+ #dialAnew() {
670
+ const controller = new AbortController();
671
+ this.#dialling = controller;
672
+ this.#waiting = 'the store has not answered';
673
+ const dialling = {
674
+ signal: controller.signal,
675
+ waiting: what => {
676
+ if (this.#dialling === controller) {
677
+ this.#waiting = what;
678
+ }
679
+ },
680
+ };
681
+ const settled = () => {
682
+ if (this.#dialling === controller) {
683
+ this.#dialling = undefined;
684
+ }
685
+ };
686
+ // no caller's withSignal reaches a dial that all of them share
687
+ return withoutSignal(() => this.#dial(dialling)).then(async (connection) => {
688
+ settled();
689
+ if (!controller.signal.aborted) {
690
+ return connection;
691
+ }
692
+ await connection.close();
693
+ throw controller.signal.reason;
694
+ }, (err) => {
695
+ settled();
696
+ throw controller.signal.aborted ? controller.signal.reason : err;
697
+ });
698
+ }
508
699
  /**
509
700
  * Runs a call on the link's connection. build makes its REQUEST's body for
510
701
  * that connection, whose handles it may open; run sends it.
511
702
  */
512
703
  async run(idempotence, attempt, signal) {
704
+ const given = signal ?? currentSignal();
513
705
  for (let tries = 0;; tries++) {
514
- ;
515
- (signal ?? currentSignal())?.throwIfAborted();
516
- const connection = await this.connection();
706
+ checkSignal(given);
707
+ const connection = await this.connection(given);
517
708
  try {
518
709
  return await attempt(connection);
519
710
  }
@@ -525,15 +716,56 @@ export class Link {
525
716
  }
526
717
  }
527
718
  }
528
- /** Closes the connection and every one to come. */
719
+ /**
720
+ * Keeps a stream that follows the store until it closes, a subscription's,
721
+ * a loop's, a tail's or a watch's, for close to cancel; it returns what
722
+ * lets the stream go. Once the link is closed it cancels the stream at
723
+ * once.
724
+ */
725
+ follow(stream) {
726
+ if (this.#closed) {
727
+ stream.cancel(new ClosedError('the store is closed'));
728
+ return () => { };
729
+ }
730
+ this.#followers.add(stream);
731
+ return () => this.#followers.delete(stream);
732
+ }
733
+ /**
734
+ * Closes the connection and every one to come. Each stream that follows
735
+ * the store is cancelled first, and its end waited for, a moment at most:
736
+ * one the server still ran would keep a private child, or a sidecar's
737
+ * connection, draining for ten seconds. A dial under way stops at its next
738
+ * wait, and every call waiting on it fails ClosedError.
739
+ */
529
740
  async close() {
530
741
  this.#closed = true;
742
+ this.#dialling?.abort(new ClosedError('the store is closed'));
743
+ const followers = [...this.#followers];
744
+ this.#followers.clear();
745
+ for (const stream of followers) {
746
+ stream.cancel(new ClosedError('the store is closed'));
747
+ }
748
+ await within(followerWait, followers.map(stream => stream.finishing()));
531
749
  const current = this.#current;
532
750
  this.#current = undefined;
533
751
  this.#dialled = undefined;
534
752
  await current?.then(c => c.close(), () => { });
535
753
  }
536
754
  }
755
+ /** How long a store's close waits for the server's end of a stream it cancelled. */
756
+ const followerWait = 2_000;
757
+ /** Waits for every promise, `ms` at most. */
758
+ async function within(ms, promises) {
759
+ if (promises.length === 0) {
760
+ return;
761
+ }
762
+ let timer;
763
+ const late = new Promise(resolve => {
764
+ timer = setTimeout(resolve, ms);
765
+ });
766
+ await Promise.race([Promise.all(promises), late]);
767
+ clearTimeout(timer);
768
+ }
537
769
  /**
538
770
  * Whether a call that failed goes on another connection: one whose REQUEST
539
771
  * had not left, and a read that had. A write that had is OutcomeUnknownError,
@@ -556,7 +788,7 @@ export function goesAgain(err, idempotence) {
556
788
  * with a RESPONSE that ends it has no items and that RESPONSE for trailer.
557
789
  */
558
790
  export async function download(connection, method, body, signal) {
559
- signal?.throwIfAborted();
791
+ checkSignal(signal);
560
792
  const stream = await connection.session.open(method, body, true);
561
793
  const unwatch = watch(signal, stream);
562
794
  try {
package/dist/handles.d.ts CHANGED
@@ -48,7 +48,16 @@ export declare function viaLink(link: Link): Via;
48
48
  * shares its handle. An open that fails is tried again by the next call.
49
49
  */
50
50
  export declare function handleOn(connection: Connection, method: number, open: Open): Promise<number>;
51
- /** A bucket's or a queue's name, as every engine takes it: [a-z0-9][a-z0-9_-]{0,63}. */
51
+ /**
52
+ * A connection lost while a handle opened, as the call that needed the handle
53
+ * meets it: the open's REQUEST had left, the call's own had not, so the call
54
+ * goes again on the next connection, where the handle opens again.
55
+ */
56
+ export declare function unsent(err: unknown): unknown;
57
+ /**
58
+ * A bucket's or a queue's name, as every engine takes it: [a-z0-9][a-z0-9_-]{0,63},
59
+ * with the nearest name that is when there is one: `focusroom.rooms` as `focusroom_rooms`.
60
+ */
52
61
  export declare function checkName(name: string, of: string): void;
53
62
  /**
54
63
  * What a batch's or a view's function returned, once the batch has settled: a