@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.
- package/LICENSE +202 -0
- package/README.md +262 -0
- package/bin/tinystore.js +50 -0
- package/dist/background.d.ts +30 -0
- package/dist/background.js +93 -0
- package/dist/blobs.d.ts +98 -0
- package/dist/blobs.js +299 -0
- package/dist/cancel.d.ts +14 -0
- package/dist/cancel.js +22 -0
- package/dist/clock.d.ts +21 -0
- package/dist/clock.js +35 -0
- package/dist/config.d.ts +60 -0
- package/dist/config.js +417 -0
- package/dist/connection.d.ts +78 -0
- package/dist/connection.js +405 -0
- package/dist/console.d.ts +48 -0
- package/dist/console.js +195 -0
- package/dist/errors.d.ts +103 -0
- package/dist/errors.js +158 -0
- package/dist/handles.d.ts +28 -0
- package/dist/handles.js +37 -0
- package/dist/index.d.ts +21 -0
- package/dist/index.js +7 -0
- package/dist/jobs.d.ts +304 -0
- package/dist/jobs.js +684 -0
- package/dist/kv.d.ts +283 -0
- package/dist/kv.js +815 -0
- package/dist/limiter.d.ts +45 -0
- package/dist/limiter.js +68 -0
- package/dist/logger.d.ts +96 -0
- package/dist/logger.js +243 -0
- package/dist/metrics.d.ts +249 -0
- package/dist/metrics.js +610 -0
- package/dist/once.d.ts +31 -0
- package/dist/once.js +116 -0
- package/dist/quota.d.ts +44 -0
- package/dist/quota.js +98 -0
- package/dist/records.d.ts +182 -0
- package/dist/records.js +346 -0
- package/dist/runtime/bun.d.ts +2 -0
- package/dist/runtime/bun.js +164 -0
- package/dist/runtime/node.d.ts +2 -0
- package/dist/runtime/node.js +157 -0
- package/dist/runtime/shared.d.ts +25 -0
- package/dist/runtime/shared.js +45 -0
- package/dist/runtime.d.ts +48 -0
- package/dist/runtime.js +4 -0
- package/dist/schema.d.ts +39 -0
- package/dist/schema.js +21 -0
- package/dist/session.d.ts +120 -0
- package/dist/session.js +546 -0
- package/dist/sql.d.ts +121 -0
- package/dist/sql.js +342 -0
- package/dist/store.d.ts +103 -0
- package/dist/store.js +153 -0
- package/dist/time.d.ts +35 -0
- package/dist/time.js +44 -0
- package/dist/trace.d.ts +18 -0
- package/dist/trace.js +22 -0
- package/dist/wire/codec.d.ts +90 -0
- package/dist/wire/codec.js +383 -0
- package/dist/wire/frame.d.ts +41 -0
- package/dist/wire/frame.js +102 -0
- package/dist/wire/messages.d.ts +1403 -0
- package/dist/wire/messages.js +472 -0
- package/dist/wire/msgpack.d.ts +93 -0
- package/dist/wire/msgpack.js +680 -0
- package/package.json +40 -0
- package/src/background.ts +108 -0
- package/src/blobs.ts +437 -0
- package/src/cancel.ts +26 -0
- package/src/clock.ts +45 -0
- package/src/config.ts +501 -0
- package/src/connection.ts +512 -0
- package/src/console.ts +228 -0
- package/src/errors.ts +211 -0
- package/src/handles.ts +68 -0
- package/src/index.ts +92 -0
- package/src/jobs.ts +963 -0
- package/src/kv.ts +1093 -0
- package/src/limiter.ts +99 -0
- package/src/logger.ts +326 -0
- package/src/metrics.ts +896 -0
- package/src/once.ts +142 -0
- package/src/quota.ts +137 -0
- package/src/records.ts +537 -0
- package/src/runtime/bun.ts +190 -0
- package/src/runtime/node.ts +177 -0
- package/src/runtime/shared.ts +61 -0
- package/src/runtime.ts +57 -0
- package/src/schema.ts +69 -0
- package/src/session.ts +665 -0
- package/src/sql.ts +478 -0
- package/src/store.ts +219 -0
- package/src/time.ts +87 -0
- package/src/trace.ts +32 -0
- package/src/wire/codec.ts +445 -0
- package/src/wire/frame.ts +139 -0
- package/src/wire/messages.ts +562 -0
- package/src/wire/msgpack.ts +712 -0
package/dist/metrics.js
ADDED
|
@@ -0,0 +1,610 @@
|
|
|
1
|
+
// Series of samples in metrics.db, as Go's metrics package keeps them: a
|
|
2
|
+
// sample is kept bit for bit, a range read exactly, an aggregate computed
|
|
3
|
+
// exactly and rounded once. Instruments live in the SDK and are ingested
|
|
4
|
+
// every flush.
|
|
5
|
+
import { FailureLog, messageOf } from './background.js';
|
|
6
|
+
import { download } from './connection.js';
|
|
7
|
+
import { errorOf, InvalidError, TinystoreError } from './errors.js';
|
|
8
|
+
import { sayOwn } from './logger.js';
|
|
9
|
+
import { ms, unixMs } from './time.js';
|
|
10
|
+
import { byCodePoint } from './wire/codec.js';
|
|
11
|
+
import { MetricsBatch, MetricsBuckets, MetricsDropped, MetricsLabels, MetricsPlan, MetricsRange, MetricsSeries, methods, } from './wire/messages.js';
|
|
12
|
+
/**
|
|
13
|
+
* The series of a name, of labels, or of both, each matched exactly, and
|
|
14
|
+
* their samples over the last `since` or from `from` to `to`.
|
|
15
|
+
*
|
|
16
|
+
* ```ts
|
|
17
|
+
* { name: 'cpu', since: '1h' } // the last hour of every cpu series
|
|
18
|
+
* { match: { host: 'web-1' }, from: start, to: end } // every series of web-1
|
|
19
|
+
* ```
|
|
20
|
+
*/
|
|
21
|
+
/**
|
|
22
|
+
* What a label's value must be beyond equality, made by oneOf, noneOf or
|
|
23
|
+
* prefix: an object of the SDK's own, so that a stored value is never read as
|
|
24
|
+
* a query.
|
|
25
|
+
*/
|
|
26
|
+
export class Condition {
|
|
27
|
+
kind;
|
|
28
|
+
values;
|
|
29
|
+
constructor(kind, values) {
|
|
30
|
+
this.kind = kind;
|
|
31
|
+
this.values = values;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** The label is one of the values. */
|
|
35
|
+
export function oneOf(...values) {
|
|
36
|
+
return new Condition('one_of', values);
|
|
37
|
+
}
|
|
38
|
+
/** The label is none of the values, or the series has none. */
|
|
39
|
+
export function noneOf(...values) {
|
|
40
|
+
return new Condition('none_of', values);
|
|
41
|
+
}
|
|
42
|
+
/** The label's value begins with the prefix. */
|
|
43
|
+
export function prefix(start) {
|
|
44
|
+
return new Condition('prefix', [start]);
|
|
45
|
+
}
|
|
46
|
+
const openEnd = 0x7fffffffffffffffn;
|
|
47
|
+
/** The label the wire carries a series' name as, the store's own spelling. */
|
|
48
|
+
const wireName = '__name__';
|
|
49
|
+
/** A series' name and labels as the wire spells them, its name among its labels. */
|
|
50
|
+
function wireLabels(name, labels) {
|
|
51
|
+
const spelled = {};
|
|
52
|
+
for (const [key, value] of Object.entries(labels ?? {})) {
|
|
53
|
+
if (key.startsWith('__')) {
|
|
54
|
+
throw new InvalidError(`the label ${key}: a name beginning with __ is the store's own`);
|
|
55
|
+
}
|
|
56
|
+
spelled[key] = value;
|
|
57
|
+
}
|
|
58
|
+
if (name !== undefined) {
|
|
59
|
+
spelled[wireName] = name;
|
|
60
|
+
}
|
|
61
|
+
return spelled;
|
|
62
|
+
}
|
|
63
|
+
/** A series as the wire spelled it: its name apart from its labels. */
|
|
64
|
+
function namedSeries(spelled) {
|
|
65
|
+
const { [wireName]: name = '', ...labels } = spelled ?? {};
|
|
66
|
+
return { name, labels };
|
|
67
|
+
}
|
|
68
|
+
function rangeOf(r, extra) {
|
|
69
|
+
const { match, where } = conditionsOf(r);
|
|
70
|
+
if (r.name === undefined && Object.keys(match).length === 0 && !where.some(finds)) {
|
|
71
|
+
throw new InvalidError('a range names a series, a label to match, or a oneOf or a prefix');
|
|
72
|
+
}
|
|
73
|
+
if (r.since !== undefined && r.from !== undefined) {
|
|
74
|
+
throw new InvalidError('a range starts since a span before now or from a time, not both');
|
|
75
|
+
}
|
|
76
|
+
const from = r.since !== undefined ? Date.now() - ms(r.since) : r.from === undefined ? 0 : unixMs(r.from);
|
|
77
|
+
return {
|
|
78
|
+
matchers: wireLabels(r.name, match),
|
|
79
|
+
where: where.length > 0 ? where : undefined,
|
|
80
|
+
from: BigInt(from),
|
|
81
|
+
to: r.to === undefined ? openEnd : BigInt(unixMs(r.to)),
|
|
82
|
+
limitSeries: r.limits?.series,
|
|
83
|
+
limitBlocks: r.limits?.blocks,
|
|
84
|
+
limitBytes: r.limits?.bytes,
|
|
85
|
+
limitDecoded: r.limits?.decoded,
|
|
86
|
+
limitAnswered: r.limits?.answered,
|
|
87
|
+
...extra,
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
/** A range's equality, plain values of where included, and its conditions in the order of their labels. */
|
|
91
|
+
function conditionsOf(r) {
|
|
92
|
+
const match = { ...r.match };
|
|
93
|
+
const where = [];
|
|
94
|
+
for (const [label, condition] of Object.entries(r.where ?? {}).sort(([a], [b]) => byCodePoint(a, b))) {
|
|
95
|
+
if (label in match) {
|
|
96
|
+
throw new InvalidError(`label ${label} is matched and has a condition`);
|
|
97
|
+
}
|
|
98
|
+
if (typeof condition === 'string') {
|
|
99
|
+
match[label] = condition;
|
|
100
|
+
}
|
|
101
|
+
else if (condition instanceof Condition) {
|
|
102
|
+
where.push({ label, kind: condition.kind, values: [...condition.values] });
|
|
103
|
+
}
|
|
104
|
+
else {
|
|
105
|
+
throw new InvalidError(`label ${label}: a condition is made by oneOf, noneOf or prefix`);
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
return { match, where };
|
|
109
|
+
}
|
|
110
|
+
function finds(condition) {
|
|
111
|
+
return condition.kind !== 'none_of';
|
|
112
|
+
}
|
|
113
|
+
function columnsOf(samples) {
|
|
114
|
+
if (Array.isArray(samples)) {
|
|
115
|
+
const pairs = samples;
|
|
116
|
+
return {
|
|
117
|
+
times: BigInt64Array.from(pairs, ([t]) => BigInt(unixMs(t))),
|
|
118
|
+
values: Float64Array.from(pairs, ([, v]) => v),
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
const columns = samples;
|
|
122
|
+
return {
|
|
123
|
+
times: columns.times instanceof BigInt64Array
|
|
124
|
+
? columns.times
|
|
125
|
+
: BigInt64Array.from(columns.times, t => BigInt(t)),
|
|
126
|
+
values: columns.values instanceof Float64Array ? columns.values : Float64Array.from(columns.values),
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
/** Joins the pieces a series longer than a body came in, one after another with its name and labels. */
|
|
130
|
+
function joined(pieces, join) {
|
|
131
|
+
const out = [];
|
|
132
|
+
for (const piece of pieces) {
|
|
133
|
+
const last = out.at(-1);
|
|
134
|
+
if (last !== undefined && last.name === piece.name && sameLabels(last.labels, piece.labels)) {
|
|
135
|
+
join(last, piece);
|
|
136
|
+
}
|
|
137
|
+
else {
|
|
138
|
+
out.push(piece);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
return out;
|
|
142
|
+
}
|
|
143
|
+
function sameLabels(a, b) {
|
|
144
|
+
const keys = Object.keys(a);
|
|
145
|
+
return keys.length === Object.keys(b).length && keys.every(k => a[k] === b[k]);
|
|
146
|
+
}
|
|
147
|
+
function concatFloats(a, b) {
|
|
148
|
+
const out = new Float64Array(a.length + b.length);
|
|
149
|
+
out.set(a);
|
|
150
|
+
out.set(b, a.length);
|
|
151
|
+
return out;
|
|
152
|
+
}
|
|
153
|
+
export class Metrics {
|
|
154
|
+
#link;
|
|
155
|
+
#instruments = new Map();
|
|
156
|
+
#timers = new Map();
|
|
157
|
+
#interval;
|
|
158
|
+
#failureLog = new FailureLog('metrics instruments', sayOwn);
|
|
159
|
+
/** instruments' flushes that failed, and why the last did */
|
|
160
|
+
failures = 0;
|
|
161
|
+
lastFailure;
|
|
162
|
+
constructor(link) {
|
|
163
|
+
this.#link = link;
|
|
164
|
+
}
|
|
165
|
+
/** Stores series and their samples, all or none; a refused series is named by its labels. */
|
|
166
|
+
async ingest(series) {
|
|
167
|
+
const batch = (Array.isArray(series) ? series : [series]).map(s => ({
|
|
168
|
+
labels: wireLabels(s.name, s.labels),
|
|
169
|
+
kind: s.kind,
|
|
170
|
+
...columnsOf(s.samples),
|
|
171
|
+
}));
|
|
172
|
+
await this.#link.run('write', connection => connection.session.call(methods['metrics.ingest'], MetricsBatch.encode({ series: batch })));
|
|
173
|
+
}
|
|
174
|
+
/** Every sample of the series a range matches, exactly, read whole before the first leaves the server. */
|
|
175
|
+
async read(range) {
|
|
176
|
+
const got = await this.#link.run('read', connection => download(connection, methods['metrics.read'], MetricsRange.encode(rangeOf(range))));
|
|
177
|
+
const pieces = got.items.map(item => {
|
|
178
|
+
const s = MetricsSeries.decode(item);
|
|
179
|
+
return {
|
|
180
|
+
...namedSeries(s.labels),
|
|
181
|
+
kind: (s.kind ?? 'gauge'),
|
|
182
|
+
times: Array.from(s.times ?? [], Number),
|
|
183
|
+
values: s.values ?? new Float64Array(0),
|
|
184
|
+
};
|
|
185
|
+
});
|
|
186
|
+
return joined(pieces, (into, piece) => {
|
|
187
|
+
into.times.push(...piece.times);
|
|
188
|
+
into.values = concatFloats(into.values, piece.values);
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
/** Buckets of a width from the range's start, each computed exactly: a counter's increase counts its resets. */
|
|
192
|
+
async aggregate(range) {
|
|
193
|
+
if (range.by !== undefined && range.without !== undefined) {
|
|
194
|
+
throw new InvalidError('an aggregate groups by labels or without them, not both');
|
|
195
|
+
}
|
|
196
|
+
const grouping = { by: range.by, without: range.without };
|
|
197
|
+
const got = await this.#link.run('read', connection => download(connection, methods['metrics.aggregate'], MetricsRange.encode(rangeOf(range, { width: ms(range.width), op: range.op, ...grouping }))));
|
|
198
|
+
const pieces = got.items.map(item => {
|
|
199
|
+
const b = MetricsBuckets.decode(item);
|
|
200
|
+
const values = b.values ?? new Float64Array(0);
|
|
201
|
+
const buckets = Array.from(values, (value, i) => ({
|
|
202
|
+
from: new Date(Number(b.from?.[i] ?? 0n)),
|
|
203
|
+
to: new Date(Number(b.to?.[i] ?? 0n)),
|
|
204
|
+
count: Number(b.count?.[i] ?? 0n),
|
|
205
|
+
resets: Number(b.resets?.[i] ?? 0n),
|
|
206
|
+
value,
|
|
207
|
+
overflow: ((b.flags?.[i] ?? 0) & 1) !== 0,
|
|
208
|
+
partial: ((b.flags?.[i] ?? 0) & 2) !== 0,
|
|
209
|
+
}));
|
|
210
|
+
return {
|
|
211
|
+
...namedSeries(b.labels),
|
|
212
|
+
kind: (b.kind ?? 'gauge'),
|
|
213
|
+
buckets,
|
|
214
|
+
};
|
|
215
|
+
});
|
|
216
|
+
return joined(pieces, (into, piece) => {
|
|
217
|
+
into.buckets.push(...piece.buckets);
|
|
218
|
+
});
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* What read(range), or aggregate(range) when it names an op, would spend
|
|
222
|
+
* of its limits, found without a payload fetched or a sample decoded: the
|
|
223
|
+
* series, the blocks, those an aggregate answers from their summaries, the
|
|
224
|
+
* bytes and the samples, beside the limits; stops is the LimitError the
|
|
225
|
+
* call would end with, undefined when it fits.
|
|
226
|
+
*/
|
|
227
|
+
async explain(range) {
|
|
228
|
+
const extra = range.op === undefined
|
|
229
|
+
? {}
|
|
230
|
+
: { width: ms(range.width ?? 0), op: range.op, by: range.by, without: range.without };
|
|
231
|
+
const body = await this.#link.run('read', connection => connection.session.call(methods['metrics.explain'], MetricsRange.encode(rangeOf(range, extra))));
|
|
232
|
+
const p = MetricsPlan.decode(body);
|
|
233
|
+
const stops = p.stops === undefined || p.stops === null ? undefined : p.stops;
|
|
234
|
+
return {
|
|
235
|
+
series: Number(p.series ?? 0),
|
|
236
|
+
blocks: Number(p.blocks ?? 0),
|
|
237
|
+
summarized: Number(p.summarized ?? 0),
|
|
238
|
+
bytes: Number(p.bytes ?? 0),
|
|
239
|
+
decoded: Number(p.decoded ?? 0),
|
|
240
|
+
limits: {
|
|
241
|
+
series: Number(p.limitSeries ?? 0),
|
|
242
|
+
blocks: Number(p.limitBlocks ?? 0),
|
|
243
|
+
bytes: Number(p.limitBytes ?? 0),
|
|
244
|
+
decoded: Number(p.limitDecoded ?? 0),
|
|
245
|
+
answered: Number(p.limitAnswered ?? 0),
|
|
246
|
+
},
|
|
247
|
+
stops: stops === undefined
|
|
248
|
+
? undefined
|
|
249
|
+
: errorOf(stops.code ?? 'limit', stops.message ?? '', stops.what ?? {}),
|
|
250
|
+
};
|
|
251
|
+
}
|
|
252
|
+
/** Removes one series and everything it holds, whether it still reads or not. */
|
|
253
|
+
async drop(series) {
|
|
254
|
+
const labels = wireLabels(series.name, series.labels);
|
|
255
|
+
const body = await this.#link.run('write', connection => connection.session.call(methods['metrics.drop'], MetricsLabels.encode({ labels })));
|
|
256
|
+
const dropped = MetricsDropped.decode(body);
|
|
257
|
+
return { found: dropped.found === true, unreadableGroups: dropped.unreadableGroups ?? 0 };
|
|
258
|
+
}
|
|
259
|
+
/** A counter: its total since this process started, ingested every flush; a restart is a reset. */
|
|
260
|
+
counter(name) {
|
|
261
|
+
return new Counter(this.#instrument(name, 'counter'), {});
|
|
262
|
+
}
|
|
263
|
+
/** A gauge: its value at each flush. */
|
|
264
|
+
gauge(name) {
|
|
265
|
+
return new Gauge(this.#instrument(name, 'gauge'), {});
|
|
266
|
+
}
|
|
267
|
+
/** A gauge read by a function at each flush; a function that throws skips that sample. */
|
|
268
|
+
gaugeFunc(name, read) {
|
|
269
|
+
this.#instrument(name, 'gauge').read = read;
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* A timer: how many durations it measured and their sum in milliseconds,
|
|
273
|
+
* ingested every flush as the counters name_count and name_sum, and the
|
|
274
|
+
* longest since the flush before as the gauge name_max, left out when it
|
|
275
|
+
* measured none. A range's mean is its sum's increase over its count's.
|
|
276
|
+
*/
|
|
277
|
+
timer(name) {
|
|
278
|
+
return new Timer(this.#timer(name), {});
|
|
279
|
+
}
|
|
280
|
+
#instrument(name, kind) {
|
|
281
|
+
let instrument = this.#instruments.get(name);
|
|
282
|
+
if (instrument === undefined) {
|
|
283
|
+
const timer = timerWriting(name, this.#timers);
|
|
284
|
+
if (timer !== undefined) {
|
|
285
|
+
throw new InvalidError(`${name} is written by the timer ${timer}`);
|
|
286
|
+
}
|
|
287
|
+
instrument = { name, kind, series: new Map(), refused: new Set(), lastRead: undefined };
|
|
288
|
+
this.#instruments.set(name, instrument);
|
|
289
|
+
this.#flushing();
|
|
290
|
+
}
|
|
291
|
+
else if (instrument.kind !== kind) {
|
|
292
|
+
throw new InvalidError(`${name} is a ${instrument.kind}, not a ${kind}`);
|
|
293
|
+
}
|
|
294
|
+
return instrument;
|
|
295
|
+
}
|
|
296
|
+
#timer(name) {
|
|
297
|
+
let timer = this.#timers.get(name);
|
|
298
|
+
if (timer === undefined) {
|
|
299
|
+
for (const { suffix } of timerSeries) {
|
|
300
|
+
const writer = this.#instruments.get(name + suffix);
|
|
301
|
+
if (writer !== undefined) {
|
|
302
|
+
throw new InvalidError(`${name + suffix} is a ${writer.kind}; the timer ${name} would write it`);
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
timer = { name, series: new Map(), refused: new Set() };
|
|
306
|
+
this.#timers.set(name, timer);
|
|
307
|
+
this.#flushing();
|
|
308
|
+
}
|
|
309
|
+
return timer;
|
|
310
|
+
}
|
|
311
|
+
#flushing() {
|
|
312
|
+
this.#interval ??= setInterval(() => void this.#flushInBackground(), flushEvery);
|
|
313
|
+
this.#interval.unref?.();
|
|
314
|
+
}
|
|
315
|
+
// a flush no caller awaits says its failure, as Go's background work does
|
|
316
|
+
async #flushInBackground() {
|
|
317
|
+
try {
|
|
318
|
+
await this.flush();
|
|
319
|
+
this.#failureLog.succeeded();
|
|
320
|
+
}
|
|
321
|
+
catch (err) {
|
|
322
|
+
this.#failureLog.failed(err);
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* Ingests every instrument's value now, as the timer does every 15 s. A
|
|
327
|
+
* series the store refuses is left out from then on, said once, so that one
|
|
328
|
+
* bad instrument keeps no other out.
|
|
329
|
+
*/
|
|
330
|
+
async flush() {
|
|
331
|
+
const at = BigInt(Date.now());
|
|
332
|
+
const batch = await this.#instrumentSamples(at);
|
|
333
|
+
const taken = this.#takeTimers(at, batch);
|
|
334
|
+
if (batch.length === 0) {
|
|
335
|
+
return;
|
|
336
|
+
}
|
|
337
|
+
try {
|
|
338
|
+
await this.#ingestLeavingRefusedOut(batch);
|
|
339
|
+
}
|
|
340
|
+
catch (err) {
|
|
341
|
+
for (const [timing, longest] of taken) {
|
|
342
|
+
timing.longest = Math.max(timing.longest, longest);
|
|
343
|
+
timing.measured = true;
|
|
344
|
+
}
|
|
345
|
+
this.failures++;
|
|
346
|
+
this.lastFailure = err;
|
|
347
|
+
throw err;
|
|
348
|
+
}
|
|
349
|
+
}
|
|
350
|
+
// every instrument's value now; a gauge whose function throws skips this
|
|
351
|
+
// flush, said once while its error stays the same
|
|
352
|
+
async #instrumentSamples(at) {
|
|
353
|
+
const batch = [];
|
|
354
|
+
for (const instrument of this.#instruments.values()) {
|
|
355
|
+
if (instrument.read !== undefined && !(await readGauge(instrument, instrument.read))) {
|
|
356
|
+
continue;
|
|
357
|
+
}
|
|
358
|
+
for (const [key, s] of instrument.series) {
|
|
359
|
+
batch.push({
|
|
360
|
+
sample: sampleAt(at, instrument.name, s.labels, instrument.kind, s.value),
|
|
361
|
+
owner: {
|
|
362
|
+
series: formatSeries(instrument.name, s.labels),
|
|
363
|
+
refuse: () => refuse(instrument, key),
|
|
364
|
+
},
|
|
365
|
+
});
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
return batch;
|
|
369
|
+
}
|
|
370
|
+
// sends the batch until the store takes what is left of it: a refusal that
|
|
371
|
+
// names one of its series leaves that series out, for good, and goes again
|
|
372
|
+
async #ingestLeavingRefusedOut(batch) {
|
|
373
|
+
let sending = batch;
|
|
374
|
+
while (sending.length > 0) {
|
|
375
|
+
try {
|
|
376
|
+
const series = sending.map(owned => owned.sample);
|
|
377
|
+
await this.#link.run('write', connection => connection.session.call(methods['metrics.ingest'], MetricsBatch.encode({ series })));
|
|
378
|
+
return;
|
|
379
|
+
}
|
|
380
|
+
catch (err) {
|
|
381
|
+
const refused = refusedIn(sending, err);
|
|
382
|
+
if (refused === undefined) {
|
|
383
|
+
throw err;
|
|
384
|
+
}
|
|
385
|
+
refused.refuse();
|
|
386
|
+
sayOwn('warn', 'instrument refused', { series: refused.series, error: messageOf(err) });
|
|
387
|
+
sending = sending.filter(owned => owned.owner !== refused);
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
// adds what the timers ingest to batch and starts their longest again,
|
|
392
|
+
// answering what it took so that a failed flush gives it back; a timer's
|
|
393
|
+
// series of one label set share an owner, so a refusal leaves all three out
|
|
394
|
+
#takeTimers(at, batch) {
|
|
395
|
+
const taken = [];
|
|
396
|
+
for (const timer of this.#timers.values()) {
|
|
397
|
+
for (const [key, t] of timer.series) {
|
|
398
|
+
const owner = {
|
|
399
|
+
series: formatSeries(timer.name, t.labels),
|
|
400
|
+
refuse: () => refuse(timer, key),
|
|
401
|
+
};
|
|
402
|
+
const add = (suffix, kind, value) => batch.push({ sample: sampleAt(at, timer.name + suffix, t.labels, kind, value), owner });
|
|
403
|
+
add('_count', 'counter', t.count);
|
|
404
|
+
add('_sum', 'counter', t.sum);
|
|
405
|
+
if (t.measured) {
|
|
406
|
+
add('_max', 'gauge', t.longest);
|
|
407
|
+
taken.push([t, t.longest]);
|
|
408
|
+
t.longest = 0;
|
|
409
|
+
t.measured = false;
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
}
|
|
413
|
+
return taken;
|
|
414
|
+
}
|
|
415
|
+
/** Stops flushing every 15 s and ingests the instruments' last values; the store's close calls it. */
|
|
416
|
+
async stop() {
|
|
417
|
+
if (this.#interval !== undefined) {
|
|
418
|
+
clearInterval(this.#interval);
|
|
419
|
+
this.#interval = undefined;
|
|
420
|
+
}
|
|
421
|
+
if (this.instruments > 0) {
|
|
422
|
+
await this.#flushInBackground();
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
get instruments() {
|
|
426
|
+
return this.#instruments.size + this.#timers.size;
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
const flushEvery = 15_000;
|
|
430
|
+
/** what a timer ingests, each series its name and a suffix */
|
|
431
|
+
const timerSeries = [
|
|
432
|
+
{ suffix: '_count', kind: 'counter' },
|
|
433
|
+
{ suffix: '_sum', kind: 'counter' },
|
|
434
|
+
{ suffix: '_max', kind: 'gauge' },
|
|
435
|
+
];
|
|
436
|
+
/** the timer that writes the series name, if one does */
|
|
437
|
+
function timerWriting(name, timers) {
|
|
438
|
+
for (const { suffix } of timerSeries) {
|
|
439
|
+
const base = name.slice(0, -suffix.length);
|
|
440
|
+
if (name.endsWith(suffix) && timers.has(base)) {
|
|
441
|
+
return base;
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
return undefined;
|
|
445
|
+
}
|
|
446
|
+
function sampleAt(at, name, labels, kind, value) {
|
|
447
|
+
return {
|
|
448
|
+
labels: { ...labels, [wireName]: name },
|
|
449
|
+
kind,
|
|
450
|
+
times: BigInt64Array.of(at),
|
|
451
|
+
values: Float64Array.of(value),
|
|
452
|
+
};
|
|
453
|
+
}
|
|
454
|
+
function keyOf(labels) {
|
|
455
|
+
return JSON.stringify(Object.entries(labels).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
|
|
456
|
+
}
|
|
457
|
+
function seriesOf(instrument, labels) {
|
|
458
|
+
const key = keyOf(labels);
|
|
459
|
+
let s = instrument.series.get(key);
|
|
460
|
+
if (s === undefined) {
|
|
461
|
+
s = { labels, value: 0 };
|
|
462
|
+
// a refused series' writes go to a value no flush reads
|
|
463
|
+
if (!instrument.refused.has(key)) {
|
|
464
|
+
instrument.series.set(key, s);
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
return s;
|
|
468
|
+
}
|
|
469
|
+
function refuse(instrument, key) {
|
|
470
|
+
instrument.series.delete(key);
|
|
471
|
+
instrument.refused.add(key);
|
|
472
|
+
}
|
|
473
|
+
/** the codes of a refusal that is the series' own doing, as Go's metrics tells them apart */
|
|
474
|
+
const seriesRefusals = new Set([
|
|
475
|
+
'invalid',
|
|
476
|
+
'limit',
|
|
477
|
+
'too_old',
|
|
478
|
+
'too_new',
|
|
479
|
+
'conflict',
|
|
480
|
+
'corrupt',
|
|
481
|
+
'suspended',
|
|
482
|
+
]);
|
|
483
|
+
/** the owner of the series a refusal names by its labels, when it names one of these */
|
|
484
|
+
function refusedIn(sending, err) {
|
|
485
|
+
if (!(err instanceof TinystoreError) || !seriesRefusals.has(err.code)) {
|
|
486
|
+
return undefined;
|
|
487
|
+
}
|
|
488
|
+
const named = Object.entries(err.what);
|
|
489
|
+
return sending.find(({ sample }) => named.length === Object.keys(sample.labels).length &&
|
|
490
|
+
named.every(([key, value]) => sample.labels[key] === value))?.owner;
|
|
491
|
+
}
|
|
492
|
+
/** a gauge's value from its function, or false when it threw: said once while the error stays the same */
|
|
493
|
+
async function readGauge(instrument, read) {
|
|
494
|
+
if (instrument.refused.size > 0) {
|
|
495
|
+
return false;
|
|
496
|
+
}
|
|
497
|
+
try {
|
|
498
|
+
instrument.series.set('{}', { labels: {}, value: await read() });
|
|
499
|
+
instrument.lastRead = undefined;
|
|
500
|
+
return true;
|
|
501
|
+
}
|
|
502
|
+
catch (err) {
|
|
503
|
+
const error = messageOf(err);
|
|
504
|
+
if (error !== instrument.lastRead) {
|
|
505
|
+
sayOwn('warn', 'gauge read failed', { series: instrument.name, error });
|
|
506
|
+
instrument.lastRead = error;
|
|
507
|
+
}
|
|
508
|
+
return false;
|
|
509
|
+
}
|
|
510
|
+
}
|
|
511
|
+
/** a series as Go prints one: its name, then its labels sorted and quoted */
|
|
512
|
+
function formatSeries(name, labels) {
|
|
513
|
+
const keys = Object.keys(labels).sort();
|
|
514
|
+
if (keys.length === 0) {
|
|
515
|
+
return name;
|
|
516
|
+
}
|
|
517
|
+
return `${name}{${keys.map(key => `${key}=${JSON.stringify(labels[key])}`).join(',')}}`;
|
|
518
|
+
}
|
|
519
|
+
export class Counter {
|
|
520
|
+
#instrument;
|
|
521
|
+
#labels;
|
|
522
|
+
constructor(instrument, labels) {
|
|
523
|
+
this.#instrument = instrument;
|
|
524
|
+
this.#labels = labels;
|
|
525
|
+
}
|
|
526
|
+
/** The counter of these labels besides its own: the same labels in any order are one series. */
|
|
527
|
+
with(labels) {
|
|
528
|
+
return new Counter(this.#instrument, { ...this.#labels, ...labels });
|
|
529
|
+
}
|
|
530
|
+
inc() {
|
|
531
|
+
this.add(1);
|
|
532
|
+
}
|
|
533
|
+
add(n) {
|
|
534
|
+
if (!(n >= 0)) {
|
|
535
|
+
throw new InvalidError(`a counter adds ${n}; it only grows`);
|
|
536
|
+
}
|
|
537
|
+
seriesOf(this.#instrument, this.#labels).value += n;
|
|
538
|
+
}
|
|
539
|
+
}
|
|
540
|
+
export class Gauge {
|
|
541
|
+
#instrument;
|
|
542
|
+
#labels;
|
|
543
|
+
constructor(instrument, labels) {
|
|
544
|
+
this.#instrument = instrument;
|
|
545
|
+
this.#labels = labels;
|
|
546
|
+
}
|
|
547
|
+
with(labels) {
|
|
548
|
+
return new Gauge(this.#instrument, { ...this.#labels, ...labels });
|
|
549
|
+
}
|
|
550
|
+
set(value) {
|
|
551
|
+
seriesOf(this.#instrument, this.#labels).value = value;
|
|
552
|
+
}
|
|
553
|
+
add(n) {
|
|
554
|
+
seriesOf(this.#instrument, this.#labels).value += n;
|
|
555
|
+
}
|
|
556
|
+
inc() {
|
|
557
|
+
this.add(1);
|
|
558
|
+
}
|
|
559
|
+
dec() {
|
|
560
|
+
this.add(-1);
|
|
561
|
+
}
|
|
562
|
+
}
|
|
563
|
+
/** A timer of labels; record and measure add a duration to the next flush. */
|
|
564
|
+
export class Timer {
|
|
565
|
+
#timer;
|
|
566
|
+
#labels;
|
|
567
|
+
constructor(timer, labels) {
|
|
568
|
+
this.#timer = timer;
|
|
569
|
+
this.#labels = labels;
|
|
570
|
+
}
|
|
571
|
+
/** The timer of these labels besides its own: the same labels in any order are one series. */
|
|
572
|
+
with(labels) {
|
|
573
|
+
return new Timer(this.#timer, { ...this.#labels, ...labels });
|
|
574
|
+
}
|
|
575
|
+
/** Adds one duration: milliseconds, their fractions kept, or text such as '250ms'. */
|
|
576
|
+
record(d) {
|
|
577
|
+
const millis = typeof d === 'number' ? d : ms(d);
|
|
578
|
+
if (!(Number.isFinite(millis) && millis >= 0)) {
|
|
579
|
+
throw new InvalidError(`a timer records ${d}; a duration is never negative`);
|
|
580
|
+
}
|
|
581
|
+
const key = keyOf(this.#labels);
|
|
582
|
+
if (this.#timer.refused.has(key)) {
|
|
583
|
+
return;
|
|
584
|
+
}
|
|
585
|
+
let t = this.#timer.series.get(key);
|
|
586
|
+
if (t === undefined) {
|
|
587
|
+
t = { labels: this.#labels, count: 0, sum: 0, longest: 0, measured: false };
|
|
588
|
+
this.#timer.series.set(key, t);
|
|
589
|
+
}
|
|
590
|
+
t.count++;
|
|
591
|
+
t.sum += millis;
|
|
592
|
+
t.longest = Math.max(t.longest, millis);
|
|
593
|
+
t.measured = true;
|
|
594
|
+
}
|
|
595
|
+
/**
|
|
596
|
+
* Runs fn and records how long it took, whether it returned or threw: its
|
|
597
|
+
* result comes back, and what it threw is thrown again.
|
|
598
|
+
*
|
|
599
|
+
* const user = await latency.with({ route: '/users' }).measure(() => users.get(id))
|
|
600
|
+
*/
|
|
601
|
+
async measure(fn) {
|
|
602
|
+
const start = performance.now();
|
|
603
|
+
try {
|
|
604
|
+
return await fn();
|
|
605
|
+
}
|
|
606
|
+
finally {
|
|
607
|
+
this.record(performance.now() - start);
|
|
608
|
+
}
|
|
609
|
+
}
|
|
610
|
+
}
|
package/dist/once.d.ts
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { Link } from './connection.ts';
|
|
2
|
+
import type { Values } from './kv.ts';
|
|
3
|
+
import type { Duration } from './time.ts';
|
|
4
|
+
import type { Key } from './wire/codec.ts';
|
|
5
|
+
export interface OnceOptions {
|
|
6
|
+
/** how long an answer is kept: a day when absent */
|
|
7
|
+
defaultTtl?: Duration;
|
|
8
|
+
}
|
|
9
|
+
/** Answers kept once a key: open them with `store.kv.once(name)`. */
|
|
10
|
+
export declare class Once<V> {
|
|
11
|
+
#private;
|
|
12
|
+
readonly name: string;
|
|
13
|
+
/** Answers come from `store.kv.once` and their `of`. */
|
|
14
|
+
constructor(link: Link, name: string, open: Uint8Array, values: Values<V>, owners: (string | Uint8Array)[]);
|
|
15
|
+
/** The answers of a branch, each key apart from the same key elsewhere. */
|
|
16
|
+
of(...owners: Key[]): Once<V>;
|
|
17
|
+
/**
|
|
18
|
+
* The answer kept under key, or fn's, which is kept. A call of a key
|
|
19
|
+
* another call is running waits for it and gets its answer; a throw of fn
|
|
20
|
+
* keeps nothing and is thrown, so the next call runs fn again. A
|
|
21
|
+
* connection lost after fn returned and before its answer was kept is
|
|
22
|
+
* OutcomeUnknownError.
|
|
23
|
+
*
|
|
24
|
+
* const receipt = await charges.run(requestId, () => pay.charge(order, requestId))
|
|
25
|
+
*/
|
|
26
|
+
run(key: Key, fn: () => V | Promise<V>): Promise<V>;
|
|
27
|
+
/** The answer kept under key, undefined when none is. */
|
|
28
|
+
get(key: Key): Promise<V | undefined>;
|
|
29
|
+
/** Forgets the answer kept under key, so that the next run runs again. */
|
|
30
|
+
delete(key: Key): Promise<void>;
|
|
31
|
+
}
|