@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.
- package/README.md +37 -37
- package/bin/tinystore.js +12 -1
- package/dist/backup.d.ts +33 -0
- package/dist/backup.js +49 -0
- package/dist/blobs.d.ts +160 -79
- package/dist/blobs.js +510 -217
- package/dist/channels.d.ts +90 -0
- package/dist/channels.js +291 -0
- package/dist/clock.js +3 -3
- package/dist/config.d.ts +209 -86
- package/dist/config.js +581 -538
- package/dist/connection.d.ts +64 -2
- package/dist/connection.js +201 -16
- package/dist/console.d.ts +27 -3
- package/dist/console.js +165 -12
- package/dist/dotenv.d.ts +7 -0
- package/dist/dotenv.js +79 -0
- package/dist/errors.d.ts +61 -1
- package/dist/errors.js +81 -1
- package/dist/handles.d.ts +44 -2
- package/dist/handles.js +81 -2
- package/dist/index.d.ts +17 -11
- package/dist/index.js +5 -3
- package/dist/instruments.d.ts +177 -0
- package/dist/instruments.js +819 -0
- package/dist/jobs.d.ts +335 -239
- package/dist/jobs.js +716 -536
- package/dist/json.d.ts +2 -0
- package/dist/json.js +122 -0
- package/dist/kv.d.ts +130 -243
- package/dist/kv.js +273 -640
- package/dist/limits.d.ts +80 -0
- package/dist/limits.js +139 -0
- package/dist/locks.d.ts +62 -0
- package/dist/locks.js +237 -0
- package/dist/logger.d.ts +45 -9
- package/dist/logger.js +150 -38
- package/dist/metrics.d.ts +210 -209
- package/dist/metrics.js +319 -556
- package/dist/once.d.ts +19 -18
- package/dist/once.js +74 -63
- package/dist/query.d.ts +181 -0
- package/dist/query.js +788 -0
- package/dist/records.d.ts +241 -150
- package/dist/records.js +507 -291
- package/dist/runtime/addon.d.ts +14 -0
- package/dist/runtime/addon.js +69 -0
- package/dist/runtime/bun.js +5 -7
- package/dist/runtime/node.js +5 -7
- package/dist/runtime/pipe.d.ts +17 -0
- package/dist/runtime/pipe.js +133 -0
- package/dist/runtime/shared.d.ts +6 -0
- package/dist/runtime/shared.js +19 -0
- package/dist/runtime.d.ts +5 -2
- package/dist/search.d.ts +189 -0
- package/dist/search.js +281 -0
- package/dist/session.d.ts +31 -3
- package/dist/session.js +153 -41
- package/dist/sql.d.ts +228 -78
- package/dist/sql.js +745 -240
- package/dist/store.d.ts +244 -24
- package/dist/store.js +270 -67
- package/dist/time.d.ts +5 -1
- package/dist/time.js +22 -2
- package/dist/tx.d.ts +61 -0
- package/dist/tx.js +314 -0
- package/dist/wire/codec.d.ts +23 -7
- package/dist/wire/codec.js +56 -35
- package/dist/wire/frame.d.ts +2 -0
- package/dist/wire/frame.js +31 -14
- package/dist/wire/messages.d.ts +259 -0
- package/dist/wire/messages.js +22 -0
- package/dist/wire/msgpack.d.ts +49 -1
- package/dist/wire/msgpack.js +293 -56
- package/dist/wire/protocol.d.ts +2683 -0
- package/dist/wire/protocol.js +10846 -0
- package/package.json +39 -38
- package/src/backup.ts +81 -0
- package/src/blobs.ts +678 -301
- package/src/channels.ts +377 -0
- package/src/clock.ts +4 -4
- package/src/config.ts +902 -612
- package/src/connection.ts +279 -21
- package/src/console.ts +180 -12
- package/src/dotenv.ts +82 -0
- package/src/errors.ts +105 -0
- package/src/handles.ts +157 -8
- package/src/index.ts +158 -52
- package/src/instruments.ts +1042 -0
- package/src/jobs.ts +1017 -733
- package/src/json.ts +133 -0
- package/src/kv.ts +424 -847
- package/src/limits.ts +202 -0
- package/src/locks.ts +320 -0
- package/src/logger.ts +209 -40
- package/src/metrics.ts +557 -752
- package/src/once.ts +86 -83
- package/src/query.ts +1005 -0
- package/src/records.ts +795 -418
- package/src/runtime/addon.ts +99 -0
- package/src/runtime/bun.ts +5 -7
- package/src/runtime/node.ts +5 -7
- package/src/runtime/pipe.ts +178 -0
- package/src/runtime/shared.ts +20 -0
- package/src/runtime.ts +5 -2
- package/src/search.ts +480 -0
- package/src/session.ts +187 -41
- package/src/sql.ts +993 -306
- package/src/store.ts +473 -78
- package/src/time.ts +48 -3
- package/src/tx.ts +426 -0
- package/src/wire/codec.ts +78 -37
- package/src/wire/frame.ts +44 -14
- package/src/wire/messages.ts +25 -0
- package/src/wire/msgpack.ts +327 -56
- package/src/wire/protocol.ts +11709 -0
- package/dist/limiter.d.ts +0 -45
- package/dist/limiter.js +0 -68
- package/dist/quota.d.ts +0 -44
- package/dist/quota.js +0 -98
- package/src/limiter.ts +0 -99
- 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
|
+
}
|