@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.
Files changed (100) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +262 -0
  3. package/bin/tinystore.js +50 -0
  4. package/dist/background.d.ts +30 -0
  5. package/dist/background.js +93 -0
  6. package/dist/blobs.d.ts +98 -0
  7. package/dist/blobs.js +299 -0
  8. package/dist/cancel.d.ts +14 -0
  9. package/dist/cancel.js +22 -0
  10. package/dist/clock.d.ts +21 -0
  11. package/dist/clock.js +35 -0
  12. package/dist/config.d.ts +60 -0
  13. package/dist/config.js +417 -0
  14. package/dist/connection.d.ts +78 -0
  15. package/dist/connection.js +405 -0
  16. package/dist/console.d.ts +48 -0
  17. package/dist/console.js +195 -0
  18. package/dist/errors.d.ts +103 -0
  19. package/dist/errors.js +158 -0
  20. package/dist/handles.d.ts +28 -0
  21. package/dist/handles.js +37 -0
  22. package/dist/index.d.ts +21 -0
  23. package/dist/index.js +7 -0
  24. package/dist/jobs.d.ts +304 -0
  25. package/dist/jobs.js +684 -0
  26. package/dist/kv.d.ts +283 -0
  27. package/dist/kv.js +815 -0
  28. package/dist/limiter.d.ts +45 -0
  29. package/dist/limiter.js +68 -0
  30. package/dist/logger.d.ts +96 -0
  31. package/dist/logger.js +243 -0
  32. package/dist/metrics.d.ts +249 -0
  33. package/dist/metrics.js +610 -0
  34. package/dist/once.d.ts +31 -0
  35. package/dist/once.js +116 -0
  36. package/dist/quota.d.ts +44 -0
  37. package/dist/quota.js +98 -0
  38. package/dist/records.d.ts +182 -0
  39. package/dist/records.js +346 -0
  40. package/dist/runtime/bun.d.ts +2 -0
  41. package/dist/runtime/bun.js +164 -0
  42. package/dist/runtime/node.d.ts +2 -0
  43. package/dist/runtime/node.js +157 -0
  44. package/dist/runtime/shared.d.ts +25 -0
  45. package/dist/runtime/shared.js +45 -0
  46. package/dist/runtime.d.ts +48 -0
  47. package/dist/runtime.js +4 -0
  48. package/dist/schema.d.ts +39 -0
  49. package/dist/schema.js +21 -0
  50. package/dist/session.d.ts +120 -0
  51. package/dist/session.js +546 -0
  52. package/dist/sql.d.ts +121 -0
  53. package/dist/sql.js +342 -0
  54. package/dist/store.d.ts +103 -0
  55. package/dist/store.js +153 -0
  56. package/dist/time.d.ts +35 -0
  57. package/dist/time.js +44 -0
  58. package/dist/trace.d.ts +18 -0
  59. package/dist/trace.js +22 -0
  60. package/dist/wire/codec.d.ts +90 -0
  61. package/dist/wire/codec.js +383 -0
  62. package/dist/wire/frame.d.ts +41 -0
  63. package/dist/wire/frame.js +102 -0
  64. package/dist/wire/messages.d.ts +1403 -0
  65. package/dist/wire/messages.js +472 -0
  66. package/dist/wire/msgpack.d.ts +93 -0
  67. package/dist/wire/msgpack.js +680 -0
  68. package/package.json +40 -0
  69. package/src/background.ts +108 -0
  70. package/src/blobs.ts +437 -0
  71. package/src/cancel.ts +26 -0
  72. package/src/clock.ts +45 -0
  73. package/src/config.ts +501 -0
  74. package/src/connection.ts +512 -0
  75. package/src/console.ts +228 -0
  76. package/src/errors.ts +211 -0
  77. package/src/handles.ts +68 -0
  78. package/src/index.ts +92 -0
  79. package/src/jobs.ts +963 -0
  80. package/src/kv.ts +1093 -0
  81. package/src/limiter.ts +99 -0
  82. package/src/logger.ts +326 -0
  83. package/src/metrics.ts +896 -0
  84. package/src/once.ts +142 -0
  85. package/src/quota.ts +137 -0
  86. package/src/records.ts +537 -0
  87. package/src/runtime/bun.ts +190 -0
  88. package/src/runtime/node.ts +177 -0
  89. package/src/runtime/shared.ts +61 -0
  90. package/src/runtime.ts +57 -0
  91. package/src/schema.ts +69 -0
  92. package/src/session.ts +665 -0
  93. package/src/sql.ts +478 -0
  94. package/src/store.ts +219 -0
  95. package/src/time.ts +87 -0
  96. package/src/trace.ts +32 -0
  97. package/src/wire/codec.ts +445 -0
  98. package/src/wire/frame.ts +139 -0
  99. package/src/wire/messages.ts +562 -0
  100. package/src/wire/msgpack.ts +712 -0
package/src/session.ts ADDED
@@ -0,0 +1,665 @@
1
+ // A connection's protocol, without its bytes' way there and back: frames in,
2
+ // frames out, streams, credit both ways, PING, GOAWAY and cancelling, as
3
+ // docs/wire.md says them. The transport hands it what it read and takes what
4
+ // it writes; nothing here waits on a socket, so the same code serves a Unix
5
+ // socket, a Windows pipe, a child's stdio and TLS.
6
+
7
+ import { createHmac, timingSafeEqual } from 'node:crypto'
8
+
9
+ import { currentSignal } from './cancel.ts'
10
+ import {
11
+ CancelledError,
12
+ ClosedError,
13
+ errorOf,
14
+ LimitError,
15
+ ProtocolError,
16
+ type TinystoreError,
17
+ UnavailableError,
18
+ } from './errors.ts'
19
+ import type { Read } from './wire/codec.ts'
20
+ import {
21
+ checkHeader,
22
+ credit,
23
+ Flag,
24
+ frame,
25
+ granted,
26
+ Kind,
27
+ kindName,
28
+ parseHeader,
29
+ } from './wire/frame.ts'
30
+ import { Failure, GoAway, Hello, Welcome } from './wire/messages.ts'
31
+
32
+ export const protocol = 1
33
+
34
+ /** What this client lets the server send on a stream before it grants more: a body at least. */
35
+ export const downloadWindow = 2 << 20
36
+
37
+ /** The largest body a WELCOME may come in, before a body is agreed. */
38
+ const welcomeMost = 1 << 20
39
+
40
+ export type Agreed = Required<Omit<Read<typeof Welcome.fields>, 'proof'>>
41
+
42
+ export interface SessionOptions {
43
+ /** a name and version, for the server's logs */
44
+ client: string
45
+ /** a remote connection's token */
46
+ token?: string | undefined
47
+ /** SERVE's secret, whose proof a local server must give before any call */
48
+ secret?: Uint8Array | undefined
49
+ /** sixteen random bytes the proof answers; given with the secret */
50
+ challenge?: Uint8Array | undefined
51
+ }
52
+
53
+ /**
54
+ * The connection was lost with a stream on it. Sent says whether its REQUEST
55
+ * had left: one that had not may go on another connection whatever it was,
56
+ * and one that had is a read to send again or a write whose outcome is
57
+ * unknown.
58
+ */
59
+ export class LostError extends ClosedError {
60
+ readonly sent: boolean
61
+
62
+ constructor(message: string, sent: boolean) {
63
+ super(message)
64
+ this.sent = sent
65
+ }
66
+ }
67
+
68
+ /** A frame of a stream's answer: the RESPONSE, a DATA, or the error that ends it. */
69
+ export interface Event {
70
+ kind: 'response' | 'data'
71
+ body: Uint8Array
72
+ end: boolean
73
+ }
74
+
75
+ type Waiter<T> = { resolve: (v: T) => void; reject: (e: Error) => void }
76
+
77
+ /**
78
+ * One stream: a client's REQUEST from its frame to the server's final frame,
79
+ * the one span in which its number is in use.
80
+ */
81
+ export class Stream {
82
+ readonly id: number
83
+ readonly method: number
84
+ /** the REQUEST has left, so the server may have acted on it */
85
+ sent = false
86
+ /** the server's final frame came, or the connection ended */
87
+ finished = false
88
+ #events: Event[] = []
89
+ #waiting: Waiter<Event> | undefined
90
+ #failure: Error | undefined
91
+ #session: Session
92
+ #uploadCredit: number
93
+ #creditWaiters: Waiter<void>[] = []
94
+ #granting = 0
95
+ #cancelled = false
96
+
97
+ constructor(session: Session, id: number, method: number, uploadCredit: number) {
98
+ this.#session = session
99
+ this.id = id
100
+ this.method = method
101
+ this.#uploadCredit = uploadCredit
102
+ }
103
+
104
+ /** The next frame of the answer, or its error. */
105
+ next(): Promise<Event> {
106
+ const event = this.#events.shift()
107
+ if (event !== undefined) {
108
+ return Promise.resolve(event)
109
+ }
110
+ if (this.#failure !== undefined) {
111
+ return Promise.reject(this.#failure)
112
+ }
113
+ return new Promise((resolve, reject) => {
114
+ this.#waiting = { resolve, reject }
115
+ })
116
+ }
117
+
118
+ /**
119
+ * Sends a body of an upload as DATA once the stream's credit lets it go;
120
+ * end says it is the last. Only an empty body ending the upload may be
121
+ * empty.
122
+ */
123
+ async send(body: Uint8Array, end: boolean): Promise<void> {
124
+ while (!this.finished && this.#uploadCredit < body.length) {
125
+ await new Promise<void>((resolve, reject) => this.#creditWaiters.push({ resolve, reject }))
126
+ }
127
+ if (this.finished) {
128
+ throw this.#failure ?? new ClosedError('the stream ended before its upload did')
129
+ }
130
+ this.#uploadCredit -= body.length
131
+ this.#session.enqueue(this, frame(Kind.data, end ? Flag.end : 0, 0, this.id, body), body.length)
132
+ }
133
+
134
+ /**
135
+ * Gives back what a DATA the server sent took of the stream's credit, once
136
+ * the caller has done with it; a grant goes once half the window has.
137
+ */
138
+ consumed(n: number): void {
139
+ if (this.finished) {
140
+ return
141
+ }
142
+ this.#granting += n
143
+ if (this.#granting >= downloadWindow / 2) {
144
+ this.#session.post(credit(this.id, this.#granting))
145
+ this.#granting = 0
146
+ }
147
+ }
148
+
149
+ /**
150
+ * Asks the server to stop. A stream whose REQUEST has not left never
151
+ * leaves; one that has keeps its number until the server's final frame,
152
+ * which is dropped.
153
+ */
154
+ cancel(): void {
155
+ if (this.finished || this.#cancelled) {
156
+ return
157
+ }
158
+ this.#cancelled = true
159
+ this.#session.cancel(this)
160
+ this.fail(new CancelledError('the call was cancelled'))
161
+ }
162
+
163
+ get cancelled(): boolean {
164
+ return this.#cancelled
165
+ }
166
+
167
+ deliver(event: Event): void {
168
+ if (this.#cancelled) {
169
+ return
170
+ }
171
+ const waiting = this.#waiting
172
+ if (waiting !== undefined) {
173
+ this.#waiting = undefined
174
+ waiting.resolve(event)
175
+ return
176
+ }
177
+ this.#events.push(event)
178
+ }
179
+
180
+ /** Ends what waits on the stream with err; events already arrived are read first. */
181
+ fail(err: Error): void {
182
+ this.#failure ??= err
183
+ const waiting = this.#waiting
184
+ this.#waiting = undefined
185
+ waiting?.reject(err)
186
+ for (const w of this.#creditWaiters.splice(0)) {
187
+ w.reject(err)
188
+ }
189
+ }
190
+
191
+ grant(n: number): void {
192
+ this.#uploadCredit += n
193
+ for (const w of this.#creditWaiters.splice(0)) {
194
+ w.resolve()
195
+ }
196
+ }
197
+
198
+ finish(): void {
199
+ this.finished = true
200
+ for (const w of this.#creditWaiters.splice(0)) {
201
+ w.resolve()
202
+ }
203
+ this.#unwatch?.()
204
+ this.#unwatch = undefined
205
+ }
206
+
207
+ /** Cancels the stream when the signal aborts, until the stream finishes. */
208
+ watchSignal(signal: AbortSignal): void {
209
+ this.#unwatch = watch(signal, this)
210
+ }
211
+
212
+ #unwatch: (() => void) | undefined
213
+ }
214
+
215
+ /** A frame waiting for the connection's credit, in the order it was asked for. */
216
+ interface Queued {
217
+ stream: Stream
218
+ bytes: Uint8Array
219
+ counted: number
220
+ request: boolean
221
+ }
222
+
223
+ /**
224
+ * The protocol of one connection. It writes through send, which the
225
+ * transport takes whole, and reads what receive is given, frames split
226
+ * anywhere.
227
+ */
228
+ export class Session {
229
+ readonly #send: (bytes: Uint8Array) => void
230
+ readonly #options: SessionOptions
231
+ /** resolves with what the WELCOME agreed, or rejects with why there is none */
232
+ readonly welcomed: Promise<Agreed>
233
+ #welcome: Waiter<Agreed>
234
+ #agreed: Agreed | undefined
235
+
236
+ #streams = new Map<number, Stream>()
237
+ #next = 0
238
+ #waitingToOpen: Waiter<void>[] = []
239
+ #queue: Queued[] = []
240
+ #credit = 0
241
+
242
+ #out: Uint8Array[] = []
243
+ #outBytes = 0
244
+ #flushing = false
245
+
246
+ #rest: Uint8Array | undefined
247
+ #goingAway = false
248
+ #ended: Error | undefined
249
+ readonly #endListeners: ((err: Error) => void)[] = []
250
+
251
+ constructor(send: (bytes: Uint8Array) => void, options: SessionOptions) {
252
+ this.#send = send
253
+ this.#options = options
254
+ let welcome!: Waiter<Agreed>
255
+ this.welcomed = new Promise<Agreed>((resolve, reject) => {
256
+ welcome = { resolve, reject }
257
+ })
258
+ this.#welcome = welcome
259
+ // a caller that never awaits the handshake still hears of its end
260
+ this.welcomed.catch(() => {})
261
+ this.post(
262
+ frame(
263
+ Kind.hello,
264
+ 0,
265
+ 0,
266
+ 0,
267
+ Hello.encode({
268
+ protocol,
269
+ client: options.client,
270
+ token: options.token,
271
+ streamCredit: downloadWindow,
272
+ challenge: options.challenge,
273
+ }),
274
+ ),
275
+ )
276
+ }
277
+
278
+ get agreed(): Agreed | undefined {
279
+ return this.#agreed
280
+ }
281
+
282
+ /** The server said GOAWAY: no stream opens here any more. */
283
+ get goingAway(): boolean {
284
+ return this.#goingAway
285
+ }
286
+
287
+ /** Why the connection ended, once it has. */
288
+ get ended(): Error | undefined {
289
+ return this.#ended
290
+ }
291
+
292
+ /** Streams in use, their final frames not yet come. */
293
+ get streams(): number {
294
+ return this.#streams.size
295
+ }
296
+
297
+ onEnd(listener: (err: Error) => void): void {
298
+ if (this.#ended !== undefined) {
299
+ listener(this.#ended)
300
+ return
301
+ }
302
+ this.#endListeners.push(listener)
303
+ }
304
+
305
+ /**
306
+ * Opens a stream with its REQUEST. End says the REQUEST is the client's
307
+ * whole side; an upload's DATA follows through the stream otherwise. It
308
+ * waits while the streams in flight are all in use.
309
+ */
310
+ async open(method: number, body: Uint8Array, end: boolean): Promise<Stream> {
311
+ const signal = currentSignal()
312
+ signal?.throwIfAborted()
313
+ const agreed = await this.welcomed
314
+ if (body.length > agreed.maxBody) {
315
+ throw new LimitError(
316
+ `a request of ${body.length} bytes, past the ${agreed.maxBody} a body holds`,
317
+ )
318
+ }
319
+ while (this.#streams.size >= agreed.inFlight && this.#usable() === undefined) {
320
+ await new Promise<void>((resolve, reject) => this.#waitingToOpen.push({ resolve, reject }))
321
+ }
322
+ const refused = this.#usable()
323
+ if (refused !== undefined) {
324
+ throw refused
325
+ }
326
+ const stream = new Stream(this, this.#nextID(), method, agreed.streamCredit)
327
+ this.#streams.set(stream.id, stream)
328
+ this.#enqueue({
329
+ stream,
330
+ bytes: frame(Kind.request, end ? Flag.end : 0, method, stream.id, body),
331
+ counted: body.length,
332
+ request: true,
333
+ })
334
+ if (signal !== undefined) {
335
+ stream.watchSignal(signal)
336
+ }
337
+ return stream
338
+ }
339
+
340
+ /** Why no stream may open now: the connection ended or is going away. */
341
+ #usable(): Error | undefined {
342
+ if (this.#ended !== undefined) {
343
+ return new LostError(`the connection ended: ${this.#ended.message}`, false)
344
+ }
345
+ if (this.#goingAway) {
346
+ return new UnavailableError('the server is closing this connection')
347
+ }
348
+ return undefined
349
+ }
350
+
351
+ /** A call: one REQUEST, and the RESPONSE that answers it. */
352
+ async call(method: number, body: Uint8Array, signal?: AbortSignal): Promise<Uint8Array> {
353
+ signal?.throwIfAborted()
354
+ const stream = await this.open(method, body, true)
355
+ const unwatch = watch(signal, stream)
356
+ try {
357
+ const event = await stream.next()
358
+ if (event.kind !== 'response' || !event.end) {
359
+ this.fault(
360
+ new ProtocolError(`a ${event.kind} without END answering a call on stream ${stream.id}`),
361
+ )
362
+ }
363
+ return event.body
364
+ } finally {
365
+ unwatch()
366
+ }
367
+ }
368
+
369
+ // a stream's number: from 1, never 0 and never one in use, so that a frame
370
+ // for a stream that has ended never reaches the next one
371
+ #nextID(): number {
372
+ for (;;) {
373
+ this.#next = this.#next === 0xffff_ffff ? 1 : this.#next + 1
374
+ if (!this.#streams.has(this.#next)) {
375
+ return this.#next
376
+ }
377
+ }
378
+ }
379
+
380
+ enqueue(stream: Stream, bytes: Uint8Array, counted: number): void {
381
+ this.#enqueue({ stream, bytes, counted, request: false })
382
+ }
383
+
384
+ #enqueue(q: Queued): void {
385
+ this.#queue.push(q)
386
+ this.#drain()
387
+ }
388
+
389
+ // frames that count against the connection's credit leave in the order
390
+ // they were asked for, as far as the credit goes
391
+ #drain(): void {
392
+ while (this.#queue.length > 0) {
393
+ const q = this.#queue[0]!
394
+ if (q.counted > this.#credit) {
395
+ return
396
+ }
397
+ this.#queue.shift()
398
+ this.#credit -= q.counted
399
+ if (q.request) {
400
+ q.stream.sent = true
401
+ }
402
+ this.post(q.bytes)
403
+ }
404
+ }
405
+
406
+ /** Writes a frame that does not wait for credit: a CREDIT, a CANCEL, a PONG. */
407
+ post(bytes: Uint8Array): void {
408
+ if (this.#ended !== undefined) {
409
+ return
410
+ }
411
+ this.#out.push(bytes)
412
+ this.#outBytes += bytes.length
413
+ if (!this.#flushing) {
414
+ this.#flushing = true
415
+ queueMicrotask(() => this.#flush())
416
+ }
417
+ }
418
+
419
+ // the frames asked for in one turn leave in one write
420
+ #flush(): void {
421
+ this.#flushing = false
422
+ if (this.#out.length === 0 || this.#ended !== undefined) {
423
+ return
424
+ }
425
+ let bytes: Uint8Array
426
+ if (this.#out.length === 1) {
427
+ bytes = this.#out[0]!
428
+ } else {
429
+ bytes = new Uint8Array(this.#outBytes)
430
+ let at = 0
431
+ for (const each of this.#out) {
432
+ bytes.set(each, at)
433
+ at += each.length
434
+ }
435
+ }
436
+ this.#out = []
437
+ this.#outBytes = 0
438
+ this.#send(bytes)
439
+ }
440
+
441
+ cancel(stream: Stream): void {
442
+ if (!stream.sent) {
443
+ this.#queue = this.#queue.filter(q => q.stream !== stream)
444
+ this.#release(stream)
445
+ return
446
+ }
447
+ this.post(frame(Kind.cancel, 0, 0, stream.id, new Uint8Array(0)))
448
+ }
449
+
450
+ // takes a stream out of use, dropping what of it has not left: its number
451
+ // may be named again at once
452
+ #release(stream: Stream): void {
453
+ stream.finish()
454
+ if (this.#streams.get(stream.id) === stream) {
455
+ this.#streams.delete(stream.id)
456
+ }
457
+ this.#queue = this.#queue.filter(q => q.stream !== stream || q.request)
458
+ this.#waitingToOpen.shift()?.resolve()
459
+ }
460
+
461
+ /** Takes bytes the transport read: any part of a frame, or several. */
462
+ receive(chunk: Uint8Array): void {
463
+ if (this.#ended !== undefined) {
464
+ return
465
+ }
466
+ let bytes = chunk
467
+ if (this.#rest !== undefined) {
468
+ bytes = new Uint8Array(this.#rest.length + chunk.length)
469
+ bytes.set(this.#rest)
470
+ bytes.set(chunk, this.#rest.length)
471
+ this.#rest = undefined
472
+ }
473
+ let at = 0
474
+ try {
475
+ while (bytes.length - at >= 12) {
476
+ const h = parseHeader(bytes, at)
477
+ checkHeader(h, this.#agreed?.maxBody ?? welcomeMost)
478
+ const stop = at + 12 + h.length
479
+ if (stop > bytes.length) {
480
+ break
481
+ }
482
+ // a body of its own, since events outlive the read's buffer
483
+ this.#take(h, bytes.slice(at + 12, stop))
484
+ at = stop
485
+ }
486
+ } catch (err) {
487
+ this.fault(err instanceof Error ? err : new ProtocolError(String(err)))
488
+ return
489
+ }
490
+ if (at < bytes.length) {
491
+ this.#rest = bytes.slice(at)
492
+ }
493
+ }
494
+
495
+ #take(h: ReturnType<typeof parseHeader>, body: Uint8Array): void {
496
+ if (this.#agreed === undefined) {
497
+ this.#handshake(h.kind, body)
498
+ return
499
+ }
500
+ switch (h.kind) {
501
+ case Kind.response:
502
+ case Kind.data:
503
+ this.#answer(h.kind, h.flags, h.stream, body)
504
+ return
505
+ case Kind.credit:
506
+ this.#credited(h.stream, granted(body))
507
+ return
508
+ case Kind.ping:
509
+ this.post(frame(Kind.pong, 0, 0, 0, body))
510
+ return
511
+ case Kind.pong:
512
+ return
513
+ case Kind.goaway:
514
+ this.#goAway(body)
515
+ return
516
+ }
517
+ throw new ProtocolError(`a ${kindName(h.kind)} from the server`)
518
+ }
519
+
520
+ #handshake(kind: number, body: Uint8Array): void {
521
+ if (kind === Kind.goaway) {
522
+ const away = GoAway.decode(body)
523
+ this.end(
524
+ errorOf(away.code ?? 'unavailable', away.message ?? 'the server refused the connection'),
525
+ )
526
+ return
527
+ }
528
+ if (kind !== Kind.welcome) {
529
+ throw new ProtocolError(`a ${kindName(kind)} where the WELCOME belongs`)
530
+ }
531
+ const welcome = Welcome.decode(body)
532
+ if (welcome.protocol !== protocol) {
533
+ throw new ProtocolError(`the server speaks protocol ${welcome.protocol}, not ${protocol}`)
534
+ }
535
+ const { secret, challenge } = this.#options
536
+ if (
537
+ secret !== undefined &&
538
+ challenge !== undefined &&
539
+ !proves(secret, challenge, welcome.proof)
540
+ ) {
541
+ throw new ProtocolError(
542
+ 'the server cannot prove it read SERVE: another process holds its endpoint',
543
+ )
544
+ }
545
+ const agreed: Agreed = {
546
+ protocol: welcome.protocol,
547
+ server: welcome.server ?? '',
548
+ instance: welcome.instance ?? new Uint8Array(0),
549
+ capability: welcome.capability ?? 'data',
550
+ maxBody: welcome.maxBody ?? 0,
551
+ inFlight: welcome.inFlight ?? 1,
552
+ connectionCredit: welcome.connectionCredit ?? 0,
553
+ streamCredit: welcome.streamCredit ?? 0,
554
+ engines: welcome.engines ?? [],
555
+ now: welcome.now ?? 0,
556
+ }
557
+ this.#agreed = agreed
558
+ this.#credit = agreed.connectionCredit
559
+ this.#welcome.resolve(agreed)
560
+ }
561
+
562
+ #answer(kind: number, flags: number, id: number, body: Uint8Array): void {
563
+ const stream = this.#streams.get(id)
564
+ if (stream === undefined) {
565
+ throw new ProtocolError(`a ${kindName(kind)} on stream ${id}, which is not in use`)
566
+ }
567
+ const end = (flags & Flag.end) !== 0
568
+ if (end) {
569
+ this.#release(stream)
570
+ }
571
+ if ((flags & Flag.error) !== 0) {
572
+ stream.fail(failureOf(body))
573
+ return
574
+ }
575
+ stream.deliver({ kind: kind === Kind.response ? 'response' : 'data', body, end })
576
+ if (stream.cancelled && kind === Kind.data) {
577
+ stream.consumed(body.length)
578
+ }
579
+ }
580
+
581
+ #credited(id: number, n: number): void {
582
+ if (id === 0) {
583
+ this.#credit += n
584
+ this.#drain()
585
+ return
586
+ }
587
+ this.#streams.get(id)?.grant(n)
588
+ }
589
+
590
+ // after a GOAWAY no stream opens; a REQUEST still waiting for credit goes
591
+ // nowhere and may be sent on another connection
592
+ #goAway(body: Uint8Array): void {
593
+ const away = GoAway.decode(body)
594
+ this.#goingAway = true
595
+ const unsent = new UnavailableError(away.message ?? 'the server is closing this connection')
596
+ for (const q of this.#queue.filter(q => q.request)) {
597
+ q.stream.fail(unsent)
598
+ this.#release(q.stream)
599
+ }
600
+ for (const w of this.#waitingToOpen.splice(0)) {
601
+ w.reject(unsent)
602
+ }
603
+ }
604
+
605
+ /** A frame broke the protocol: the connection ends, and whoever runs it closes it. */
606
+ fault(err: Error): void {
607
+ this.end(err instanceof ProtocolError ? err : new ProtocolError(err.message))
608
+ }
609
+
610
+ /**
611
+ * Ends the session: the transport closed, or a frame broke the protocol.
612
+ * Every stream still open learns whether its REQUEST had left.
613
+ */
614
+ end(err: Error): void {
615
+ if (this.#ended !== undefined) {
616
+ return
617
+ }
618
+ this.#ended = err
619
+ this.#welcome.reject(err)
620
+ for (const stream of this.#streams.values()) {
621
+ stream.fail(new LostError(`the connection ended: ${err.message}`, stream.sent))
622
+ stream.finish()
623
+ }
624
+ this.#streams.clear()
625
+ this.#queue = []
626
+ for (const w of this.#waitingToOpen.splice(0)) {
627
+ w.reject(new LostError(`the connection ended: ${err.message}`, false))
628
+ }
629
+ for (const listener of this.#endListeners.splice(0)) {
630
+ listener(err)
631
+ }
632
+ }
633
+ }
634
+
635
+ /** Cancels a stream when a signal aborts; returns what stops watching. */
636
+ export function watch(signal: AbortSignal | undefined, stream: Stream): () => void {
637
+ if (signal === undefined) {
638
+ return () => {}
639
+ }
640
+ const cancel = () => stream.cancel()
641
+ if (signal.aborted) {
642
+ cancel()
643
+ return () => {}
644
+ }
645
+ signal.addEventListener('abort', cancel, { once: true })
646
+ return () => signal.removeEventListener('abort', cancel)
647
+ }
648
+
649
+ /** The error a final frame with ERROR carries. */
650
+ export function failureOf(body: Uint8Array): TinystoreError {
651
+ const failure = Failure.decode(body)
652
+ return errorOf(failure.code ?? 'internal', failure.message ?? '', failure.what ?? {})
653
+ }
654
+
655
+ /** A WELCOME's proof is the HMAC-SHA256 of the challenge keyed with SERVE's secret. */
656
+ export function proves(
657
+ secret: Uint8Array,
658
+ challenge: Uint8Array,
659
+ proof: Uint8Array | undefined,
660
+ ): boolean {
661
+ if (proof === undefined || proof.length !== 32) {
662
+ return false
663
+ }
664
+ return timingSafeEqual(createHmac('sha256', secret).update(challenge).digest(), proof)
665
+ }