@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.6

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 (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/src/limits.ts ADDED
@@ -0,0 +1,202 @@
1
+ // May this request pass: a rate limit lets a smooth rate of requests a key
2
+ // through, the generic cell rate algorithm with its times in the core's memory;
3
+ // a quota counts uses in windows that reset, all of them or none in one
4
+ // durable write. Both answer rather than throw, with one Allowance.
5
+
6
+ import type { Link } from './connection.ts'
7
+ import { InvalidError } from './errors.ts'
8
+ import { checkName } from './handles.ts'
9
+ import { callOn, keyText } from './kv.ts'
10
+ import { dateOf, ms, type Unit } from './time.ts'
11
+ import type { Key } from './wire/codec.ts'
12
+ import { KvAllowance, KvQuotaOpen, KvRateLimitOpen, type Method } from './wire/protocol.ts'
13
+
14
+ /**
15
+ * How many pass a span: '100/s', '5/10s', '1000/h', '300/7d', a span of one
16
+ * unit leaving out its 1. The type checks it as it is written.
17
+ */
18
+ export type Rate = `${number}/${Unit}` | `${number}/${number}${Unit}`
19
+
20
+ export interface RateLimitOptions {
21
+ /** how many requests a key passes a span */
22
+ rate: Rate
23
+ /** how many may pass at once before the rate holds the next; the rate's count when absent */
24
+ burst?: number | undefined
25
+ }
26
+
27
+ /** One window of a quota as a key stands in it. */
28
+ export interface WindowUse {
29
+ used: number
30
+ limit: number
31
+ left: number
32
+ /** when the window resets; undefined for one not started */
33
+ resetsAt: Date | undefined
34
+ }
35
+
36
+ /** What a rate limit or a quota answers a request. */
37
+ export interface Allowance<W extends string = never> {
38
+ ok: boolean
39
+ /** how many more would pass now */
40
+ left: number
41
+ /** when a refused request may try again; undefined when it passed */
42
+ retryAt: Date | undefined
43
+ /** a quota's windows by name; none for a rate limit */
44
+ windows: Record<W, WindowUse>
45
+ }
46
+
47
+ /**
48
+ * A rate's count and span in milliseconds: a span of one unit may leave out
49
+ * its 1.
50
+ *
51
+ * '100/s' → 100 a 1000 ms, '5/10s' → 5 a 10000 ms
52
+ */
53
+ export function rateOf(rate: string): { count: number; per: number } {
54
+ const parts = /^(\d+)\/(\d*)([a-z]+)$/.exec(rate)
55
+ if (parts === null) {
56
+ throw new InvalidError(`the rate ${JSON.stringify(rate)}; write it as 100/s, 5/10s or 1000/h`)
57
+ }
58
+ const [, count, span, unit] = parts
59
+ return { count: Number(count), per: ms(`${span === '' ? '1' : span}${unit}`) }
60
+ }
61
+
62
+ /** A rate of requests a key: open it with `store.rateLimit(name, { rate })`. */
63
+ export class RateLimit {
64
+ readonly name: string
65
+ readonly #link: Link
66
+ readonly #open: Uint8Array
67
+ readonly #under: readonly string[]
68
+
69
+ /** Rate limits come from `store.rateLimit` and their `under`. */
70
+ constructor(link: Link, name: string, open: Uint8Array, under: readonly string[]) {
71
+ this.#link = link
72
+ this.name = name
73
+ this.#open = open
74
+ this.#under = under
75
+ }
76
+
77
+ /** The rate limit of a branch, each key apart from the same key elsewhere. */
78
+ under(...owners: Key[]): RateLimit {
79
+ return new RateLimit(this.#link, this.name, this.#open, [
80
+ ...this.#under,
81
+ ...owners.map(keyText),
82
+ ])
83
+ }
84
+
85
+ /** Asks for n requests of key, one unless given: all pass or none; more than the burst is InvalidError. */
86
+ async allow(key: Key, n = 1): Promise<Allowance> {
87
+ return allowanceOf(await this.#call('kv.allow', key, n, 'write'))
88
+ }
89
+
90
+ /** The answer one request would get, using nothing. */
91
+ async peek(key: Key): Promise<Allowance> {
92
+ return allowanceOf(await this.#call('kv.peek', key, undefined, 'read'))
93
+ }
94
+
95
+ /** Forgets key, so that its next request starts afresh. */
96
+ async reset(key: Key): Promise<void> {
97
+ await this.#call('kv.reset', key, undefined, 'write')
98
+ }
99
+
100
+ #call(method: Method, key: Key, n: number | undefined, idempotence: 'read' | 'write') {
101
+ const fields = { key, n: n === 1 ? undefined : n }
102
+ return callOn(
103
+ this.#link,
104
+ 'kv.rateLimit.open',
105
+ this.#open,
106
+ this.#under,
107
+ method,
108
+ fields,
109
+ idempotence,
110
+ )
111
+ }
112
+ }
113
+
114
+ /** Uses by key in named windows: open it with `store.quota(name, { daily: '100/1d' })`. */
115
+ export class Quota<W extends string = string> {
116
+ readonly name: string
117
+ readonly #link: Link
118
+ readonly #open: Uint8Array
119
+ readonly #under: readonly string[]
120
+
121
+ /** Quotas come from `store.quota` and their `under`. */
122
+ constructor(link: Link, name: string, open: Uint8Array, under: readonly string[]) {
123
+ this.#link = link
124
+ this.name = name
125
+ this.#open = open
126
+ this.#under = under
127
+ }
128
+
129
+ under(...owners: Key[]): Quota<W> {
130
+ return new Quota(this.#link, this.name, this.#open, [...this.#under, ...owners.map(keyText)])
131
+ }
132
+
133
+ /**
134
+ * Uses n of key's every window, one unless given, or none when one has no
135
+ * room; more than a window's limit is InvalidError.
136
+ *
137
+ * const { ok, retryAt, windows } = await ai.allow(user.id)
138
+ */
139
+ async allow(key: Key, n = 1): Promise<Allowance<W>> {
140
+ return allowanceOf(await this.#call('kv.allow', key, n, 'write'))
141
+ }
142
+
143
+ async peek(key: Key): Promise<Allowance<W>> {
144
+ return allowanceOf(await this.#call('kv.peek', key, undefined, 'read'))
145
+ }
146
+
147
+ async reset(key: Key): Promise<void> {
148
+ await this.#call('kv.reset', key, undefined, 'write')
149
+ }
150
+
151
+ /** Gives n uses back to every window of key, one unless given. */
152
+ async refund(key: Key, n = 1): Promise<void> {
153
+ await this.#call('kv.refund', key, n, 'write')
154
+ }
155
+
156
+ #call(method: Method, key: Key, n: number | undefined, idempotence: 'read' | 'write') {
157
+ const fields = { key, n: n === 1 ? undefined : n }
158
+ return callOn(this.#link, 'kv.quota.open', this.#open, this.#under, method, fields, idempotence)
159
+ }
160
+ }
161
+
162
+ /** A rate limit's open: its name and rate, checked before anything leaves. */
163
+ export function rateLimitOpen(name: string, options: RateLimitOptions): Uint8Array {
164
+ checkName(name, 'rate limit')
165
+ const { count, per } = rateOf(options.rate)
166
+ if (count < 1 || per < 1) {
167
+ throw new InvalidError(`kv rate limit ${name}: a rate of ${options.rate}`)
168
+ }
169
+ if (options.burst !== undefined && (!Number.isInteger(options.burst) || options.burst < 1)) {
170
+ throw new InvalidError(`kv rate limit ${name}: a burst of ${options.burst}`)
171
+ }
172
+ return KvRateLimitOpen.encode({ name, rate: count, per, burst: options.burst })
173
+ }
174
+
175
+ /** A quota's open: its windows by name, in the order they were given. */
176
+ export function quotaOpen(name: string, windows: Record<string, Rate>): Uint8Array {
177
+ checkName(name, 'quota')
178
+ const named = Object.entries(windows).map(([window, rate]) => {
179
+ const { count, per } = rateOf(rate)
180
+ return { name: window, limit: count, per }
181
+ })
182
+ return KvQuotaOpen.encode({ name, windows: named })
183
+ }
184
+
185
+ function allowanceOf<W extends string>(body: Uint8Array): Allowance<W> {
186
+ const answer = KvAllowance.decode(body)
187
+ const windows = {} as Record<W, WindowUse>
188
+ for (const window of answer.windows ?? []) {
189
+ windows[(window.name ?? '') as W] = {
190
+ used: window.used ?? 0,
191
+ limit: window.limit ?? 0,
192
+ left: window.left ?? 0,
193
+ resetsAt: dateOf(window.resetsAt),
194
+ }
195
+ }
196
+ return {
197
+ ok: answer.ok === true,
198
+ left: answer.left ?? 0,
199
+ retryAt: dateOf(answer.retryAt),
200
+ windows,
201
+ }
202
+ }
package/src/locks.ts ADDED
@@ -0,0 +1,320 @@
1
+ // Locks and semaphores, as docs/guides/locks/README.md has them: a key that one holder
2
+ // at a time, or `limit`, may hold while a function runs, across every
3
+ // program of a store. The store keeps them in its process's memory; a holder
4
+ // here renews its lease at a third of its ttl from this program, so that a
5
+ // program that froze stops renewing and loses the key.
6
+
7
+ import { AsyncLocalStorage } from 'node:async_hooks'
8
+
9
+ import { currentSignal } from './cancel.ts'
10
+ import type { Link } from './connection.ts'
11
+ import { ClosedError, InUseError, InvalidError, LostError } from './errors.ts'
12
+ import { checkName } from './handles.ts'
13
+ import { keyText } from './kv.ts'
14
+ import { ConnectionLostError } from './session.ts'
15
+ import { insideDatabaseTx } from './sql.ts'
16
+ import { type Duration, ms } from './time.ts'
17
+ import { insideStoreTx } from './tx.ts'
18
+ import type { Key } from './wire/codec.ts'
19
+ import { LocksHeld, LocksHold, LocksLease, LocksRenew, methods } from './wire/protocol.ts'
20
+
21
+ /** How long a lease lasts between renewals, and a hold waits, unless said. */
22
+ const defaultTtl = 10_000
23
+ const defaultWait = 10_000
24
+
25
+ export interface LockOptions {
26
+ /** how long a lease lasts from its last renewal: 10 s unless said, 1 s to 1 hour */
27
+ ttl?: Duration | undefined
28
+ /** how long a lease lasts from its grant, however it is renewed: past it the next in line holds the key */
29
+ maxHold?: Duration | undefined
30
+ }
31
+
32
+ export interface SemaphoreOptions extends LockOptions {
33
+ /** how many may hold a key at once, 1 to 1000 */
34
+ limit: number
35
+ }
36
+
37
+ export interface HoldOptions {
38
+ /** how long the hold waits in line: 10 s unless said, then InUseError */
39
+ wait?: Duration | undefined
40
+ }
41
+
42
+ /** What tryHold gives: the function's value, or that the key was held. */
43
+ export type Tried<T> = { acquired: true; value: T } | { acquired: false }
44
+
45
+ /** A holding of a lock's key, given to the function that holds it. */
46
+ export interface Lease {
47
+ /** grows with every lease the store gives: hand it to whatever must refuse a late holder */
48
+ readonly fence: bigint
49
+ /** aborts when the lease is lost: run out, revoked at maxHold, or its store closed */
50
+ readonly signal: AbortSignal
51
+ }
52
+
53
+ /** A holding of a semaphore's key: one of its limit. */
54
+ export interface Permit {
55
+ readonly signal: AbortSignal
56
+ }
57
+
58
+ /** Keys held one holder at a time: open them with `store.lock(name)`. */
59
+ export class Lock {
60
+ readonly name: string
61
+ readonly #keys: Keys
62
+
63
+ /** A lock comes from `store.lock`. */
64
+ constructor(link: Link, name: string, options: LockOptions | undefined) {
65
+ checkName(name, 'lock')
66
+ this.name = name
67
+ this.#keys = new Keys(link, 'lock', name, 1, options)
68
+ }
69
+
70
+ /**
71
+ * Waits for key, holds it while fn runs and lets it go, giving what fn
72
+ * gives. A key still held after the wait is InUseError; a lease lost
73
+ * while fn ran is LostError, though fn succeeded.
74
+ *
75
+ * await invoices.hold(invoice.id, lease => charge(invoice, { fence: lease.fence, signal: lease.signal }))
76
+ */
77
+ async hold<T>(key: Key, fn: (lease: Lease) => T | Promise<T>, options?: HoldOptions): Promise<T> {
78
+ return held(await this.#keys.hold(key, fn, waitOf(options), leaseOf), this.#keys.place(key))
79
+ }
80
+
81
+ /** Holds key while fn runs if nobody holds it, and says it was held without waiting if somebody does. */
82
+ tryHold<T>(key: Key, fn: (lease: Lease) => T | Promise<T>): Promise<Tried<T>> {
83
+ return this.#keys.hold(key, fn, 0, leaseOf)
84
+ }
85
+ }
86
+
87
+ /** Keys held by up to their limit at a time: open them with `store.semaphore(name, { limit })`. */
88
+ export class Semaphore {
89
+ readonly name: string
90
+ readonly limit: number
91
+ readonly #keys: Keys
92
+
93
+ /** A semaphore comes from `store.semaphore`. */
94
+ constructor(link: Link, name: string, options: SemaphoreOptions) {
95
+ checkName(name, 'semaphore')
96
+ if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1000) {
97
+ throw new InvalidError(`semaphore ${name}: a limit of ${options.limit}, not 1 to 1000`)
98
+ }
99
+ this.name = name
100
+ this.limit = options.limit
101
+ this.#keys = new Keys(link, 'semaphore', name, options.limit, options)
102
+ }
103
+
104
+ async hold<T>(
105
+ key: Key,
106
+ fn: (permit: Permit) => T | Promise<T>,
107
+ options?: HoldOptions,
108
+ ): Promise<T> {
109
+ return held(await this.#keys.hold(key, fn, waitOf(options), permitOf), this.#keys.place(key))
110
+ }
111
+
112
+ tryHold<T>(key: Key, fn: (permit: Permit) => T | Promise<T>): Promise<Tried<T>> {
113
+ return this.#keys.hold(key, fn, 0, permitOf)
114
+ }
115
+ }
116
+
117
+ function waitOf(options: HoldOptions | undefined): number {
118
+ return ms(options?.wait ?? defaultWait)
119
+ }
120
+
121
+ /** What hold gives: fn's value, a hold told not to wait finding the key held. */
122
+ function held<T>(tried: Tried<T>, place: string): T {
123
+ if (!tried.acquired) {
124
+ throw new InUseError(`${place}: held, and the hold would not wait`)
125
+ }
126
+ return tried.value
127
+ }
128
+
129
+ const leaseOf = (holding: Holding): Lease => ({ fence: holding.fence, signal: holding.signal })
130
+ const permitOf = (holding: Holding): Permit => ({ signal: holding.signal })
131
+
132
+ // The keys the caller holds or waits for, as its async context carries them,
133
+ // each with the link of the store it is of.
134
+ const holding = new AsyncLocalStorage<readonly (readonly [Link, string])[]>()
135
+
136
+ /** What a lock and a semaphore share: asking for a key, and the lease once given. */
137
+ class Keys {
138
+ readonly #link: Link
139
+ readonly #kind: 'lock' | 'semaphore'
140
+ readonly #name: string
141
+ readonly #limit: number
142
+ readonly #ttl: number
143
+ readonly #maxHold: number | undefined
144
+
145
+ constructor(
146
+ link: Link,
147
+ kind: 'lock' | 'semaphore',
148
+ name: string,
149
+ limit: number,
150
+ options: LockOptions | undefined,
151
+ ) {
152
+ this.#link = link
153
+ this.#kind = kind
154
+ this.#name = name
155
+ this.#limit = limit
156
+ this.#ttl = ms(options?.ttl ?? defaultTtl)
157
+ this.#maxHold = options?.maxHold === undefined ? undefined : ms(options.maxHold)
158
+ }
159
+
160
+ /** The key as an error names it: `lock invoices: key "42"`. */
161
+ place(key: Key): string {
162
+ return `${this.#kind} ${this.#name}: key ${JSON.stringify(keyText(key))}`
163
+ }
164
+
165
+ async hold<T, V>(
166
+ key: Key,
167
+ fn: (view: V) => T | Promise<T>,
168
+ wait: number,
169
+ viewOf: (holding: Holding) => V,
170
+ ): Promise<Tried<T>> {
171
+ const place = this.place(key)
172
+ this.#refuse(place)
173
+ const answer = await this.#ask(keyText(key), wait)
174
+ if (answer.acquired !== true) {
175
+ return { acquired: false }
176
+ }
177
+ const lease = new Holding(this.#link, place, answer, this.#ttl)
178
+ try {
179
+ const inside = [...(holding.getStore() ?? []), [this.#link, place] as const]
180
+ const value = await holding.run(inside, () => fn(viewOf(lease)))
181
+ lease.check()
182
+ return { acquired: true, value }
183
+ } finally {
184
+ await lease.end()
185
+ }
186
+ }
187
+
188
+ /**
189
+ * Refuses a hold that would wait for what its caller holds: a database's
190
+ * writer, which a transaction keeps while the key is waited for, or the
191
+ * same key.
192
+ */
193
+ #refuse(place: string): void {
194
+ if (insideStoreTx() || insideDatabaseTx()) {
195
+ throw new InvalidError(
196
+ `${place}: a hold inside a transaction would keep its writer while the key is waited for: hold first`,
197
+ )
198
+ }
199
+ if (holding.getStore()?.some(([link, held]) => link === this.#link && held === place)) {
200
+ throw new InvalidError(`${place}: a hold of a key inside its own hold would wait for itself`)
201
+ }
202
+ }
203
+
204
+ // A connection lost on the way asks again with the same request, which the
205
+ // store answers with the lease it gave, or with the ask's place in line.
206
+ async #ask(key: string, wait: number): Promise<ReturnType<typeof LocksHeld.decode>> {
207
+ const body = LocksHold.encode({
208
+ kind: this.#kind,
209
+ name: this.#name,
210
+ key,
211
+ limit: this.#limit,
212
+ ttl: this.#ttl,
213
+ maxHold: this.#maxHold,
214
+ wait,
215
+ request: crypto.getRandomValues(new Uint8Array(16)),
216
+ })
217
+ const answer = await this.#link.run('read', connection =>
218
+ connection.session.call(methods['locks.hold'], body, currentSignal()),
219
+ )
220
+ return LocksHeld.decode(answer)
221
+ }
222
+ }
223
+
224
+ /**
225
+ * A lease this program holds: renewed at a third of its ttl, and counted lost
226
+ * at its own deadline, the time it sent the last renewal that succeeded plus
227
+ * its ttl, less a margin, or at maxHold.
228
+ */
229
+ class Holding {
230
+ readonly fence: bigint
231
+ readonly #link: Link
232
+ readonly #place: string
233
+ readonly #lease: Uint8Array
234
+ readonly #ttl: number
235
+ readonly #lost = new AbortController()
236
+ readonly #renewing: ReturnType<typeof setInterval>
237
+ #runningOut: ReturnType<typeof setTimeout> | undefined
238
+ readonly #revoking: ReturnType<typeof setTimeout> | undefined
239
+
240
+ constructor(link: Link, place: string, answer: ReturnType<typeof LocksHeld.decode>, ttl: number) {
241
+ this.#link = link
242
+ this.#place = place
243
+ this.#lease = answer.lease ?? new Uint8Array(0)
244
+ this.#ttl = ttl
245
+ this.fence = answer.fence === undefined || answer.fence === '' ? 0n : BigInt(answer.fence)
246
+ this.#renewing = unref(setInterval(() => void this.#renew(), Math.max(1, Math.floor(ttl / 3))))
247
+ this.#runOutAt(performance.now() + ttl)
248
+ const revokeIn = answer.revokeIn
249
+ this.#revoking =
250
+ revokeIn === undefined
251
+ ? undefined
252
+ : unref(setTimeout(() => this.#lose('it was revoked at its maxHold'), revokeIn))
253
+ }
254
+
255
+ get signal(): AbortSignal {
256
+ return this.#lost.signal
257
+ }
258
+
259
+ /** Throws why the lease was lost, if it was. */
260
+ check(): void {
261
+ if (this.#lost.signal.aborted) {
262
+ throw this.#lost.signal.reason
263
+ }
264
+ }
265
+
266
+ /** Stops renewing and lets the key go; a lease lost already lets nothing go. */
267
+ async end(): Promise<void> {
268
+ this.#stop()
269
+ const body = LocksLease.encode({ lease: this.#lease })
270
+ await this.#link
271
+ .run('read', connection => connection.session.call(methods['locks.release'], body))
272
+ .catch(() => {})
273
+ }
274
+
275
+ async #renew(): Promise<void> {
276
+ const sent = performance.now()
277
+ const body = LocksRenew.encode({ lease: this.#lease, ttl: this.#ttl })
278
+ try {
279
+ await this.#link.run('read', connection =>
280
+ connection.session.call(methods['locks.renew'], body),
281
+ )
282
+ this.#runOutAt(sent + this.#ttl)
283
+ } catch (err) {
284
+ if (err instanceof LostError) {
285
+ this.#lose('it ran out before it was renewed')
286
+ } else if (err instanceof ClosedError && !(err instanceof ConnectionLostError)) {
287
+ this.#lose('its store closed', err)
288
+ }
289
+ // any other failure keeps renewing until the lease's own deadline
290
+ }
291
+ }
292
+
293
+ #runOutAt(deadline: number): void {
294
+ if (this.#runningOut !== undefined) {
295
+ clearTimeout(this.#runningOut)
296
+ }
297
+ const margin = Math.min(1000, this.#ttl / 10)
298
+ const left = Math.max(0, deadline - margin - performance.now())
299
+ this.#runningOut = unref(setTimeout(() => this.#lose('it was not renewed in time'), left))
300
+ }
301
+
302
+ #lose(why: string, cause?: Error): void {
303
+ this.#stop()
304
+ if (!this.#lost.signal.aborted) {
305
+ this.#lost.abort(cause ?? new LostError(`${this.#place}: the lease was lost: ${why}`))
306
+ }
307
+ }
308
+
309
+ #stop(): void {
310
+ clearInterval(this.#renewing)
311
+ clearTimeout(this.#runningOut)
312
+ clearTimeout(this.#revoking)
313
+ }
314
+ }
315
+
316
+ /** A timer that keeps no program running by itself. */
317
+ function unref<T extends ReturnType<typeof setTimeout>>(timer: T): T {
318
+ ;(timer as { unref?: () => void }).unref?.()
319
+ return timer
320
+ }