@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.7
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/dist/limiter.d.ts
DELETED
|
@@ -1,45 +0,0 @@
|
|
|
1
|
-
import type { Link } from './connection.ts';
|
|
2
|
-
import { type Unit } from './time.ts';
|
|
3
|
-
import type { Key } from './wire/codec.ts';
|
|
4
|
-
/**
|
|
5
|
-
* How many pass a span: '100/s', '5/10s', '1000/h', '300/7d', a span of one
|
|
6
|
-
* unit leaving out its 1. The type checks it as it is written.
|
|
7
|
-
*/
|
|
8
|
-
export type Rate = `${number}/${Unit}` | `${number}/${number}${Unit}`;
|
|
9
|
-
export interface LimiterOptions {
|
|
10
|
-
/** how many requests pass a span, each key on its own */
|
|
11
|
-
rate: Rate;
|
|
12
|
-
/** how many may pass at once before the rate holds the next; the rate's count when absent */
|
|
13
|
-
burst?: number;
|
|
14
|
-
}
|
|
15
|
-
/** What a limiter answers a request. */
|
|
16
|
-
export interface Allowance {
|
|
17
|
-
ok: boolean;
|
|
18
|
-
/** how many more requests would pass now */
|
|
19
|
-
left: number;
|
|
20
|
-
/** milliseconds until the request would pass; 0 when ok */
|
|
21
|
-
retryAfter: number;
|
|
22
|
-
}
|
|
23
|
-
/**
|
|
24
|
-
* A rate's count and span in milliseconds: a span of one unit may leave out
|
|
25
|
-
* its 1.
|
|
26
|
-
*
|
|
27
|
-
* '100/s' → 100 a 1000 ms, '5/10s' → 5 a 10000 ms
|
|
28
|
-
*/
|
|
29
|
-
export declare function rateOf(rate: string): {
|
|
30
|
-
count: number;
|
|
31
|
-
per: number;
|
|
32
|
-
};
|
|
33
|
-
/** A limiter: open it with `store.kv.limiter(name, { rate })`. */
|
|
34
|
-
export declare class Limiter {
|
|
35
|
-
#private;
|
|
36
|
-
readonly name: string;
|
|
37
|
-
/** Limiters come from `store.kv.limiter` and their `of`. */
|
|
38
|
-
constructor(link: Link, name: string, open: Uint8Array, owners: (string | Uint8Array)[]);
|
|
39
|
-
/** The limiter of a branch, each key apart from the same key elsewhere. */
|
|
40
|
-
of(...owners: Key[]): Limiter;
|
|
41
|
-
/** Asks for n requests of key, one unless given: all pass or none does; past the burst is InvalidError. */
|
|
42
|
-
allow(key: Key, n?: number): Promise<Allowance>;
|
|
43
|
-
}
|
|
44
|
-
/** A limiter's open: its name and rate, checked before anything leaves. */
|
|
45
|
-
export declare function limiterOpen(name: string, options: LimiterOptions): Uint8Array;
|
package/dist/limiter.js
DELETED
|
@@ -1,68 +0,0 @@
|
|
|
1
|
-
// A limiter of requests by key, as Go's kv.Limiter keeps one: the generic
|
|
2
|
-
// cell rate algorithm, one time a key, which the server holds in memory and
|
|
3
|
-
// writes every second, so a crash lets at most one burst more through.
|
|
4
|
-
import { InvalidError } from './errors.js';
|
|
5
|
-
import { checkName, handleOn, ownerText } from './handles.js';
|
|
6
|
-
import { ms } from './time.js';
|
|
7
|
-
import { KvAllowance, KvBucket, KvCall, methods } from './wire/messages.js';
|
|
8
|
-
/**
|
|
9
|
-
* A rate's count and span in milliseconds: a span of one unit may leave out
|
|
10
|
-
* its 1.
|
|
11
|
-
*
|
|
12
|
-
* '100/s' → 100 a 1000 ms, '5/10s' → 5 a 10000 ms
|
|
13
|
-
*/
|
|
14
|
-
export function rateOf(rate) {
|
|
15
|
-
const parts = /^(\d+)\/(\d*)([a-z]+)$/.exec(rate);
|
|
16
|
-
if (parts === null) {
|
|
17
|
-
throw new InvalidError(`the rate ${JSON.stringify(rate)}; write it as 100/s, 5/10s or 1000/h`);
|
|
18
|
-
}
|
|
19
|
-
const [, count, span, unit] = parts;
|
|
20
|
-
return { count: Number(count), per: ms(`${span === '' ? '1' : span}${unit}`) };
|
|
21
|
-
}
|
|
22
|
-
/** A limiter: open it with `store.kv.limiter(name, { rate })`. */
|
|
23
|
-
export class Limiter {
|
|
24
|
-
name;
|
|
25
|
-
#link;
|
|
26
|
-
#open;
|
|
27
|
-
#owners;
|
|
28
|
-
/** Limiters come from `store.kv.limiter` and their `of`. */
|
|
29
|
-
constructor(link, name, open, owners) {
|
|
30
|
-
this.#link = link;
|
|
31
|
-
this.name = name;
|
|
32
|
-
this.#open = open;
|
|
33
|
-
this.#owners = owners;
|
|
34
|
-
}
|
|
35
|
-
/** The limiter of a branch, each key apart from the same key elsewhere. */
|
|
36
|
-
of(...owners) {
|
|
37
|
-
return new Limiter(this.#link, this.name, this.#open, [
|
|
38
|
-
...this.#owners,
|
|
39
|
-
...owners.map(ownerText),
|
|
40
|
-
]);
|
|
41
|
-
}
|
|
42
|
-
/** Asks for n requests of key, one unless given: all pass or none does; past the burst is InvalidError. */
|
|
43
|
-
async allow(key, n = 1) {
|
|
44
|
-
const answer = await this.#link.run('write', async (connection) => {
|
|
45
|
-
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
46
|
-
const body = KvCall.encode({
|
|
47
|
-
handle,
|
|
48
|
-
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
49
|
-
key,
|
|
50
|
-
n: n === 1 ? undefined : n,
|
|
51
|
-
});
|
|
52
|
-
return KvAllowance.decode(await connection.session.call(methods['kv.allow'], body));
|
|
53
|
-
});
|
|
54
|
-
return { ok: answer.ok === true, left: answer.left ?? 0, retryAfter: answer.retryAfter ?? 0 };
|
|
55
|
-
}
|
|
56
|
-
}
|
|
57
|
-
/** A limiter's open: its name and rate, checked before anything leaves. */
|
|
58
|
-
export function limiterOpen(name, options) {
|
|
59
|
-
checkName(name, 'limiter');
|
|
60
|
-
const { count, per } = rateOf(options.rate);
|
|
61
|
-
if (count < 1 || per < 1) {
|
|
62
|
-
throw new InvalidError(`limiter ${name}: a rate of ${options.rate}`);
|
|
63
|
-
}
|
|
64
|
-
if (options.burst !== undefined && (!Number.isInteger(options.burst) || options.burst < 1)) {
|
|
65
|
-
throw new InvalidError(`limiter ${name}: a burst of ${options.burst}`);
|
|
66
|
-
}
|
|
67
|
-
return KvBucket.encode({ name, rate: count, per, burst: options.burst });
|
|
68
|
-
}
|
package/dist/quota.d.ts
DELETED
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
import type { Link } from './connection.ts';
|
|
2
|
-
import { type Rate } from './limiter.ts';
|
|
3
|
-
import type { Key } from './wire/codec.ts';
|
|
4
|
-
/** One window of a key: what it used of its limit, and when it resets. */
|
|
5
|
-
export interface WindowUsage {
|
|
6
|
-
used: number;
|
|
7
|
-
limit: number;
|
|
8
|
-
left: number;
|
|
9
|
-
/** when the window ends and the next use starts another; undefined before it starts */
|
|
10
|
-
resetAt: Date | undefined;
|
|
11
|
-
}
|
|
12
|
-
/** What a quota answers a key: what a limiter answers, and each window by its name. */
|
|
13
|
-
export interface QuotaUsage<W extends string = string> {
|
|
14
|
-
ok: boolean;
|
|
15
|
-
/** how many more uses would pass now */
|
|
16
|
-
left: number;
|
|
17
|
-
/** milliseconds until a refused use would pass; 0 when ok */
|
|
18
|
-
retryAfter: number;
|
|
19
|
-
windows: Record<W, WindowUsage>;
|
|
20
|
-
}
|
|
21
|
-
/** A quota: open it with `store.kv.quota(name, { session: '100/5h', weekly: '300/7d' })`. */
|
|
22
|
-
export declare class Quota<W extends string = string> {
|
|
23
|
-
#private;
|
|
24
|
-
readonly name: string;
|
|
25
|
-
/** Quotas come from `store.kv.quota` and their `of`. */
|
|
26
|
-
constructor(link: Link, name: string, open: Uint8Array, owners: (string | Uint8Array)[]);
|
|
27
|
-
/** The quota of a branch, each key apart from the same key elsewhere. */
|
|
28
|
-
of(...owners: Key[]): Quota<W>;
|
|
29
|
-
/**
|
|
30
|
-
* Uses n of key's every window, one unless given, or none when one has no
|
|
31
|
-
* room for them; more than a window's limit is InvalidError.
|
|
32
|
-
*
|
|
33
|
-
* const { ok, retryAfter, windows } = await ai.allow(user.id)
|
|
34
|
-
*/
|
|
35
|
-
allow(key: Key, n?: number): Promise<QuotaUsage<W>>;
|
|
36
|
-
/** Key's windows without using them: ok says whether one more use would pass now. */
|
|
37
|
-
get(key: Key): Promise<QuotaUsage<W>>;
|
|
38
|
-
/** Gives n uses back, one unless given, to each of key's windows that has not reset since. */
|
|
39
|
-
refund(key: Key, n?: number): Promise<void>;
|
|
40
|
-
/** Forgets key's windows, so that its next use starts each anew. */
|
|
41
|
-
delete(key: Key): Promise<void>;
|
|
42
|
-
}
|
|
43
|
-
/** A quota's open: its name and windows, checked before anything leaves. */
|
|
44
|
-
export declare function quotaOpen(name: string, windows: Record<string, Rate>): Uint8Array;
|
package/dist/quota.js
DELETED
|
@@ -1,98 +0,0 @@
|
|
|
1
|
-
// A quota of uses by key, as Go's kv.Quota keeps one: several windows, each
|
|
2
|
-
// starting at a key's first use after the last ended, checked and counted
|
|
3
|
-
// together in one durable write, or not counted at all.
|
|
4
|
-
import { InvalidError } from './errors.js';
|
|
5
|
-
import { checkName, handleOn, ownerText } from './handles.js';
|
|
6
|
-
import { rateOf } from './limiter.js';
|
|
7
|
-
import { dateOf } from './time.js';
|
|
8
|
-
import { KvAllowance, KvBucket, KvCall, methods } from './wire/messages.js';
|
|
9
|
-
/** A quota: open it with `store.kv.quota(name, { session: '100/5h', weekly: '300/7d' })`. */
|
|
10
|
-
export class Quota {
|
|
11
|
-
name;
|
|
12
|
-
#link;
|
|
13
|
-
#open;
|
|
14
|
-
#owners;
|
|
15
|
-
/** Quotas come from `store.kv.quota` and their `of`. */
|
|
16
|
-
constructor(link, name, open, owners) {
|
|
17
|
-
this.#link = link;
|
|
18
|
-
this.name = name;
|
|
19
|
-
this.#open = open;
|
|
20
|
-
this.#owners = owners;
|
|
21
|
-
}
|
|
22
|
-
/** The quota of a branch, each key apart from the same key elsewhere. */
|
|
23
|
-
of(...owners) {
|
|
24
|
-
return new Quota(this.#link, this.name, this.#open, [...this.#owners, ...owners.map(ownerText)]);
|
|
25
|
-
}
|
|
26
|
-
/**
|
|
27
|
-
* Uses n of key's every window, one unless given, or none when one has no
|
|
28
|
-
* room for them; more than a window's limit is InvalidError.
|
|
29
|
-
*
|
|
30
|
-
* const { ok, retryAfter, windows } = await ai.allow(user.id)
|
|
31
|
-
*/
|
|
32
|
-
async allow(key, n = 1) {
|
|
33
|
-
return usageOf(await this.#call('kv.allow', key, n, 'write'));
|
|
34
|
-
}
|
|
35
|
-
/** Key's windows without using them: ok says whether one more use would pass now. */
|
|
36
|
-
async get(key) {
|
|
37
|
-
return usageOf(await this.#call('kv.usage', key, 1, 'read'));
|
|
38
|
-
}
|
|
39
|
-
/** Gives n uses back, one unless given, to each of key's windows that has not reset since. */
|
|
40
|
-
async refund(key, n = 1) {
|
|
41
|
-
await this.#call('kv.refund', key, n, 'write');
|
|
42
|
-
}
|
|
43
|
-
/** Forgets key's windows, so that its next use starts each anew. */
|
|
44
|
-
async delete(key) {
|
|
45
|
-
await this.#call('kv.delete', key, 1, 'write');
|
|
46
|
-
}
|
|
47
|
-
async #call(method, key, n, idempotence) {
|
|
48
|
-
return this.#link.run(idempotence, async (connection) => {
|
|
49
|
-
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
50
|
-
const body = KvCall.encode({
|
|
51
|
-
handle,
|
|
52
|
-
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
53
|
-
key,
|
|
54
|
-
n: n === 1 ? undefined : n,
|
|
55
|
-
});
|
|
56
|
-
return await connection.session.call(methods[method], body);
|
|
57
|
-
});
|
|
58
|
-
}
|
|
59
|
-
}
|
|
60
|
-
function usageOf(body) {
|
|
61
|
-
const answer = KvAllowance.decode(body);
|
|
62
|
-
const windows = {};
|
|
63
|
-
for (const w of answer.windows ?? []) {
|
|
64
|
-
windows[(w.name ?? '')] = {
|
|
65
|
-
used: w.used ?? 0,
|
|
66
|
-
limit: w.limit ?? 0,
|
|
67
|
-
left: w.left ?? 0,
|
|
68
|
-
resetAt: dateOf(w.resetAt),
|
|
69
|
-
};
|
|
70
|
-
}
|
|
71
|
-
return {
|
|
72
|
-
ok: answer.ok === true,
|
|
73
|
-
left: answer.left ?? 0,
|
|
74
|
-
retryAfter: answer.retryAfter ?? 0,
|
|
75
|
-
windows,
|
|
76
|
-
};
|
|
77
|
-
}
|
|
78
|
-
/** A quota's open: its name and windows, checked before anything leaves. */
|
|
79
|
-
export function quotaOpen(name, windows) {
|
|
80
|
-
checkName(name, 'quota');
|
|
81
|
-
const spans = Object.entries(windows);
|
|
82
|
-
if (spans.length < 1 || spans.length > 8) {
|
|
83
|
-
throw new InvalidError(`quota ${name}: ${spans.length} windows, not one to eight`);
|
|
84
|
-
}
|
|
85
|
-
return KvBucket.encode({
|
|
86
|
-
name,
|
|
87
|
-
windows: spans.map(([window, rate]) => {
|
|
88
|
-
if (!/^[a-z][a-z0-9_]{0,31}$/.test(window)) {
|
|
89
|
-
throw new InvalidError(`quota ${name}: a window name is [a-z][a-z0-9_]{0,31}, not ${window}`);
|
|
90
|
-
}
|
|
91
|
-
const { count, per } = rateOf(rate);
|
|
92
|
-
if (count < 1 || per < 1) {
|
|
93
|
-
throw new InvalidError(`quota ${name}: a window of ${rate}`);
|
|
94
|
-
}
|
|
95
|
-
return { name: window, limit: count, per };
|
|
96
|
-
}),
|
|
97
|
-
});
|
|
98
|
-
}
|
package/src/limiter.ts
DELETED
|
@@ -1,99 +0,0 @@
|
|
|
1
|
-
// A limiter of requests by key, as Go's kv.Limiter keeps one: the generic
|
|
2
|
-
// cell rate algorithm, one time a key, which the server holds in memory and
|
|
3
|
-
// writes every second, so a crash lets at most one burst more through.
|
|
4
|
-
|
|
5
|
-
import type { Link } from './connection.ts'
|
|
6
|
-
import { InvalidError } from './errors.ts'
|
|
7
|
-
import { checkName, handleOn, ownerText } from './handles.ts'
|
|
8
|
-
import { ms, type Unit } from './time.ts'
|
|
9
|
-
import type { Key } from './wire/codec.ts'
|
|
10
|
-
import { KvAllowance, KvBucket, KvCall, methods } from './wire/messages.ts'
|
|
11
|
-
|
|
12
|
-
/**
|
|
13
|
-
* How many pass a span: '100/s', '5/10s', '1000/h', '300/7d', a span of one
|
|
14
|
-
* unit leaving out its 1. The type checks it as it is written.
|
|
15
|
-
*/
|
|
16
|
-
export type Rate = `${number}/${Unit}` | `${number}/${number}${Unit}`
|
|
17
|
-
|
|
18
|
-
export interface LimiterOptions {
|
|
19
|
-
/** how many requests pass a span, each key on its own */
|
|
20
|
-
rate: Rate
|
|
21
|
-
/** how many may pass at once before the rate holds the next; the rate's count when absent */
|
|
22
|
-
burst?: number
|
|
23
|
-
}
|
|
24
|
-
|
|
25
|
-
/** What a limiter answers a request. */
|
|
26
|
-
export interface Allowance {
|
|
27
|
-
ok: boolean
|
|
28
|
-
/** how many more requests would pass now */
|
|
29
|
-
left: number
|
|
30
|
-
/** milliseconds until the request would pass; 0 when ok */
|
|
31
|
-
retryAfter: number
|
|
32
|
-
}
|
|
33
|
-
|
|
34
|
-
/**
|
|
35
|
-
* A rate's count and span in milliseconds: a span of one unit may leave out
|
|
36
|
-
* its 1.
|
|
37
|
-
*
|
|
38
|
-
* '100/s' → 100 a 1000 ms, '5/10s' → 5 a 10000 ms
|
|
39
|
-
*/
|
|
40
|
-
export function rateOf(rate: string): { count: number; per: number } {
|
|
41
|
-
const parts = /^(\d+)\/(\d*)([a-z]+)$/.exec(rate)
|
|
42
|
-
if (parts === null) {
|
|
43
|
-
throw new InvalidError(`the rate ${JSON.stringify(rate)}; write it as 100/s, 5/10s or 1000/h`)
|
|
44
|
-
}
|
|
45
|
-
const [, count, span, unit] = parts
|
|
46
|
-
return { count: Number(count), per: ms(`${span === '' ? '1' : span}${unit}`) }
|
|
47
|
-
}
|
|
48
|
-
|
|
49
|
-
/** A limiter: open it with `store.kv.limiter(name, { rate })`. */
|
|
50
|
-
export class Limiter {
|
|
51
|
-
readonly name: string
|
|
52
|
-
readonly #link: Link
|
|
53
|
-
readonly #open: Uint8Array
|
|
54
|
-
readonly #owners: (string | Uint8Array)[]
|
|
55
|
-
|
|
56
|
-
/** Limiters come from `store.kv.limiter` and their `of`. */
|
|
57
|
-
constructor(link: Link, name: string, open: Uint8Array, owners: (string | Uint8Array)[]) {
|
|
58
|
-
this.#link = link
|
|
59
|
-
this.name = name
|
|
60
|
-
this.#open = open
|
|
61
|
-
this.#owners = owners
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
/** The limiter of a branch, each key apart from the same key elsewhere. */
|
|
65
|
-
of(...owners: Key[]): Limiter {
|
|
66
|
-
return new Limiter(this.#link, this.name, this.#open, [
|
|
67
|
-
...this.#owners,
|
|
68
|
-
...owners.map(ownerText),
|
|
69
|
-
])
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
/** Asks for n requests of key, one unless given: all pass or none does; past the burst is InvalidError. */
|
|
73
|
-
async allow(key: Key, n = 1): Promise<Allowance> {
|
|
74
|
-
const answer = await this.#link.run('write', async connection => {
|
|
75
|
-
const handle = await handleOn(connection, methods['kv.open'], this.#open)
|
|
76
|
-
const body = KvCall.encode({
|
|
77
|
-
handle,
|
|
78
|
-
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
79
|
-
key,
|
|
80
|
-
n: n === 1 ? undefined : n,
|
|
81
|
-
})
|
|
82
|
-
return KvAllowance.decode(await connection.session.call(methods['kv.allow'], body))
|
|
83
|
-
})
|
|
84
|
-
return { ok: answer.ok === true, left: answer.left ?? 0, retryAfter: answer.retryAfter ?? 0 }
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
|
|
88
|
-
/** A limiter's open: its name and rate, checked before anything leaves. */
|
|
89
|
-
export function limiterOpen(name: string, options: LimiterOptions): Uint8Array {
|
|
90
|
-
checkName(name, 'limiter')
|
|
91
|
-
const { count, per } = rateOf(options.rate)
|
|
92
|
-
if (count < 1 || per < 1) {
|
|
93
|
-
throw new InvalidError(`limiter ${name}: a rate of ${options.rate}`)
|
|
94
|
-
}
|
|
95
|
-
if (options.burst !== undefined && (!Number.isInteger(options.burst) || options.burst < 1)) {
|
|
96
|
-
throw new InvalidError(`limiter ${name}: a burst of ${options.burst}`)
|
|
97
|
-
}
|
|
98
|
-
return KvBucket.encode({ name, rate: count, per, burst: options.burst })
|
|
99
|
-
}
|
package/src/quota.ts
DELETED
|
@@ -1,137 +0,0 @@
|
|
|
1
|
-
// A quota of uses by key, as Go's kv.Quota keeps one: several windows, each
|
|
2
|
-
// starting at a key's first use after the last ended, checked and counted
|
|
3
|
-
// together in one durable write, or not counted at all.
|
|
4
|
-
|
|
5
|
-
import type { Link } from './connection.ts'
|
|
6
|
-
import { InvalidError } from './errors.ts'
|
|
7
|
-
import { checkName, handleOn, ownerText } from './handles.ts'
|
|
8
|
-
import { type Rate, rateOf } from './limiter.ts'
|
|
9
|
-
import { dateOf } from './time.ts'
|
|
10
|
-
import type { Key } from './wire/codec.ts'
|
|
11
|
-
import { KvAllowance, KvBucket, KvCall, methods } from './wire/messages.ts'
|
|
12
|
-
|
|
13
|
-
/** One window of a key: what it used of its limit, and when it resets. */
|
|
14
|
-
export interface WindowUsage {
|
|
15
|
-
used: number
|
|
16
|
-
limit: number
|
|
17
|
-
left: number
|
|
18
|
-
/** when the window ends and the next use starts another; undefined before it starts */
|
|
19
|
-
resetAt: Date | undefined
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
/** What a quota answers a key: what a limiter answers, and each window by its name. */
|
|
23
|
-
export interface QuotaUsage<W extends string = string> {
|
|
24
|
-
ok: boolean
|
|
25
|
-
/** how many more uses would pass now */
|
|
26
|
-
left: number
|
|
27
|
-
/** milliseconds until a refused use would pass; 0 when ok */
|
|
28
|
-
retryAfter: number
|
|
29
|
-
windows: Record<W, WindowUsage>
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
/** A quota: open it with `store.kv.quota(name, { session: '100/5h', weekly: '300/7d' })`. */
|
|
33
|
-
export class Quota<W extends string = string> {
|
|
34
|
-
readonly name: string
|
|
35
|
-
readonly #link: Link
|
|
36
|
-
readonly #open: Uint8Array
|
|
37
|
-
readonly #owners: (string | Uint8Array)[]
|
|
38
|
-
|
|
39
|
-
/** Quotas come from `store.kv.quota` and their `of`. */
|
|
40
|
-
constructor(link: Link, name: string, open: Uint8Array, owners: (string | Uint8Array)[]) {
|
|
41
|
-
this.#link = link
|
|
42
|
-
this.name = name
|
|
43
|
-
this.#open = open
|
|
44
|
-
this.#owners = owners
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
/** The quota of a branch, each key apart from the same key elsewhere. */
|
|
48
|
-
of(...owners: Key[]): Quota<W> {
|
|
49
|
-
return new Quota(this.#link, this.name, this.#open, [...this.#owners, ...owners.map(ownerText)])
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
/**
|
|
53
|
-
* Uses n of key's every window, one unless given, or none when one has no
|
|
54
|
-
* room for them; more than a window's limit is InvalidError.
|
|
55
|
-
*
|
|
56
|
-
* const { ok, retryAfter, windows } = await ai.allow(user.id)
|
|
57
|
-
*/
|
|
58
|
-
async allow(key: Key, n = 1): Promise<QuotaUsage<W>> {
|
|
59
|
-
return usageOf(await this.#call('kv.allow', key, n, 'write'))
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
/** Key's windows without using them: ok says whether one more use would pass now. */
|
|
63
|
-
async get(key: Key): Promise<QuotaUsage<W>> {
|
|
64
|
-
return usageOf(await this.#call('kv.usage', key, 1, 'read'))
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
/** Gives n uses back, one unless given, to each of key's windows that has not reset since. */
|
|
68
|
-
async refund(key: Key, n = 1): Promise<void> {
|
|
69
|
-
await this.#call('kv.refund', key, n, 'write')
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
/** Forgets key's windows, so that its next use starts each anew. */
|
|
73
|
-
async delete(key: Key): Promise<void> {
|
|
74
|
-
await this.#call('kv.delete', key, 1, 'write')
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
async #call(
|
|
78
|
-
method: 'kv.allow' | 'kv.usage' | 'kv.refund' | 'kv.delete',
|
|
79
|
-
key: Key,
|
|
80
|
-
n: number,
|
|
81
|
-
idempotence: 'read' | 'write',
|
|
82
|
-
) {
|
|
83
|
-
return this.#link.run(idempotence, async connection => {
|
|
84
|
-
const handle = await handleOn(connection, methods['kv.open'], this.#open)
|
|
85
|
-
const body = KvCall.encode({
|
|
86
|
-
handle,
|
|
87
|
-
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
88
|
-
key,
|
|
89
|
-
n: n === 1 ? undefined : n,
|
|
90
|
-
})
|
|
91
|
-
return await connection.session.call(methods[method], body)
|
|
92
|
-
})
|
|
93
|
-
}
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
function usageOf<W extends string>(body: Uint8Array): QuotaUsage<W> {
|
|
97
|
-
const answer = KvAllowance.decode(body)
|
|
98
|
-
const windows = {} as Record<W, WindowUsage>
|
|
99
|
-
for (const w of answer.windows ?? []) {
|
|
100
|
-
windows[(w.name ?? '') as W] = {
|
|
101
|
-
used: w.used ?? 0,
|
|
102
|
-
limit: w.limit ?? 0,
|
|
103
|
-
left: w.left ?? 0,
|
|
104
|
-
resetAt: dateOf(w.resetAt),
|
|
105
|
-
}
|
|
106
|
-
}
|
|
107
|
-
return {
|
|
108
|
-
ok: answer.ok === true,
|
|
109
|
-
left: answer.left ?? 0,
|
|
110
|
-
retryAfter: answer.retryAfter ?? 0,
|
|
111
|
-
windows,
|
|
112
|
-
}
|
|
113
|
-
}
|
|
114
|
-
|
|
115
|
-
/** A quota's open: its name and windows, checked before anything leaves. */
|
|
116
|
-
export function quotaOpen(name: string, windows: Record<string, Rate>): Uint8Array {
|
|
117
|
-
checkName(name, 'quota')
|
|
118
|
-
const spans = Object.entries(windows)
|
|
119
|
-
if (spans.length < 1 || spans.length > 8) {
|
|
120
|
-
throw new InvalidError(`quota ${name}: ${spans.length} windows, not one to eight`)
|
|
121
|
-
}
|
|
122
|
-
return KvBucket.encode({
|
|
123
|
-
name,
|
|
124
|
-
windows: spans.map(([window, rate]) => {
|
|
125
|
-
if (!/^[a-z][a-z0-9_]{0,31}$/.test(window)) {
|
|
126
|
-
throw new InvalidError(
|
|
127
|
-
`quota ${name}: a window name is [a-z][a-z0-9_]{0,31}, not ${window}`,
|
|
128
|
-
)
|
|
129
|
-
}
|
|
130
|
-
const { count, per } = rateOf(rate)
|
|
131
|
-
if (count < 1 || per < 1) {
|
|
132
|
-
throw new InvalidError(`quota ${name}: a window of ${rate}`)
|
|
133
|
-
}
|
|
134
|
-
return { name: window, limit: count, per }
|
|
135
|
-
}),
|
|
136
|
-
})
|
|
137
|
-
}
|