@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
|
@@ -0,0 +1,405 @@
|
|
|
1
|
+
// A connection is a transport and the session over it; a link is what gives
|
|
2
|
+
// the store its connection, dialling again once the last one ended: the
|
|
3
|
+
// directory's sidecar, found through SERVE or started, a private child, or a
|
|
4
|
+
// remote server.
|
|
5
|
+
import { randomBytes } from 'node:crypto';
|
|
6
|
+
import { join, resolve } from 'node:path';
|
|
7
|
+
import manifest from '../package.json' with { type: 'json' };
|
|
8
|
+
import { currentSignal } from './cancel.js';
|
|
9
|
+
import { ClosedError, OutcomeUnknownError, TinystoreError, UnavailableError } from './errors.js';
|
|
10
|
+
import { LostError, Session, watch } from './session.js';
|
|
11
|
+
import { Empty, methods } from './wire/messages.js';
|
|
12
|
+
/** How long a server may take to answer HELLO. */
|
|
13
|
+
const handshakeTime = 5000;
|
|
14
|
+
export class Connection {
|
|
15
|
+
session;
|
|
16
|
+
#transport;
|
|
17
|
+
/** what close waits for once the transport has ended: a private child's exit */
|
|
18
|
+
#closing;
|
|
19
|
+
/** the handles this connection opened, by what they are: a bucket's name and options */
|
|
20
|
+
handles = new Map();
|
|
21
|
+
constructor(session, transport, closing = () => Promise.resolve()) {
|
|
22
|
+
this.session = session;
|
|
23
|
+
this.#transport = transport;
|
|
24
|
+
this.#closing = closing;
|
|
25
|
+
}
|
|
26
|
+
/** Connects, shakes hands, and gives up after the handshake's time. */
|
|
27
|
+
static async dial(runtime, endpoint, options, tls) {
|
|
28
|
+
let session;
|
|
29
|
+
const early = [];
|
|
30
|
+
const transport = await runtime
|
|
31
|
+
.connect(endpoint, {
|
|
32
|
+
data: bytes => session === undefined ? early.push(bytes.slice()) : session.receive(bytes),
|
|
33
|
+
end: err => session?.end(err),
|
|
34
|
+
}, tls)
|
|
35
|
+
.catch((err) => {
|
|
36
|
+
// a socket that refuses fails as the platform says it; a caller sees one kind
|
|
37
|
+
if (err instanceof TinystoreError) {
|
|
38
|
+
throw err;
|
|
39
|
+
}
|
|
40
|
+
throw new ClosedError(`cannot reach ${endpoint}: ${err.message}`);
|
|
41
|
+
});
|
|
42
|
+
session = new Session(bytes => transport.write(bytes), options);
|
|
43
|
+
for (const bytes of early) {
|
|
44
|
+
session.receive(bytes);
|
|
45
|
+
}
|
|
46
|
+
const connection = new Connection(session, transport);
|
|
47
|
+
await connection.#handshake();
|
|
48
|
+
return connection;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Shakes hands over a private child's stdin and stdout. Closing waits for
|
|
52
|
+
* the child's exit, since until then it holds the directory: its LOCK, and
|
|
53
|
+
* on Windows every file it opened, which a removal fails on.
|
|
54
|
+
*/
|
|
55
|
+
static async overChild(child, session) {
|
|
56
|
+
const connection = new Connection(session, child.transport, () => child.exited);
|
|
57
|
+
await connection.#handshake();
|
|
58
|
+
return connection;
|
|
59
|
+
}
|
|
60
|
+
async #handshake() {
|
|
61
|
+
const timer = setTimeout(() => this.session.end(new ClosedError(`no WELCOME within ${handshakeTime / 1000} s`)), handshakeTime);
|
|
62
|
+
try {
|
|
63
|
+
await this.session.welcomed;
|
|
64
|
+
}
|
|
65
|
+
catch (err) {
|
|
66
|
+
this.#transport.close();
|
|
67
|
+
throw err;
|
|
68
|
+
}
|
|
69
|
+
finally {
|
|
70
|
+
clearTimeout(timer);
|
|
71
|
+
}
|
|
72
|
+
this.session.onEnd(() => this.#transport.close());
|
|
73
|
+
}
|
|
74
|
+
/** Ends the connection; a private child is waited for until it has exited. */
|
|
75
|
+
async close() {
|
|
76
|
+
this.session.end(new ClosedError('the store closed'));
|
|
77
|
+
this.#transport.close();
|
|
78
|
+
await this.#closing();
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
/** How long a client waits for a sidecar to answer, its own or another's, before it gives up. */
|
|
82
|
+
const startTime = 15_000;
|
|
83
|
+
/** The pause before a start that found the directory held starts again, doubling up to a second. */
|
|
84
|
+
const heldPause = 100;
|
|
85
|
+
/**
|
|
86
|
+
* Finds the directory's sidecar through SERVE or starts one, as docs/wire.md
|
|
87
|
+
* "Finding a local server" says: a sidecar found proves itself before the
|
|
88
|
+
* first call, and one started exits with 3 when another holds the directory,
|
|
89
|
+
* whose SERVE the client then waits for. A sidecar of an older release than
|
|
90
|
+
* this SDK's is stopped and replaced with this SDK's binary; another server
|
|
91
|
+
* of an older release, a person's or a program's own, is told of once.
|
|
92
|
+
*/
|
|
93
|
+
export function sidecar(runtime, dir, binary, idle, older = server => olderRelease(server, manifest.version)) {
|
|
94
|
+
const absolute = resolve(dir);
|
|
95
|
+
const serve = join(absolute, 'server', 'SERVE');
|
|
96
|
+
const log = join(absolute, 'server', 'serve.log');
|
|
97
|
+
const idling = idle === undefined ? [] : ['--idle', `${idle}ms`];
|
|
98
|
+
let told = false;
|
|
99
|
+
return async () => {
|
|
100
|
+
const found = await reachServe(runtime, serve);
|
|
101
|
+
let stoppedInstance;
|
|
102
|
+
if (found !== undefined) {
|
|
103
|
+
const server = (await found.connection.session.welcomed).server;
|
|
104
|
+
if (!older(server)) {
|
|
105
|
+
return found.connection;
|
|
106
|
+
}
|
|
107
|
+
if (found.sidecar && (await stopped(found.connection))) {
|
|
108
|
+
process.stderr.write(`${replacedSidecar(server, manifest.version, dir)}\n`);
|
|
109
|
+
stoppedInstance = found.instance;
|
|
110
|
+
}
|
|
111
|
+
else {
|
|
112
|
+
if (!told) {
|
|
113
|
+
process.stderr.write(`${olderServer(server, manifest.version, dir)}\n`);
|
|
114
|
+
}
|
|
115
|
+
told = true;
|
|
116
|
+
return found.connection;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
const command = [binary(), 'serve', '--dir', absolute, '--local', '--log', log, ...idling];
|
|
120
|
+
return startSidecar(runtime, serve, log, command, stoppedInstance);
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Starts a sidecar and waits for SERVE to name one that answers, its own or
|
|
125
|
+
* another client's that won the start. One that exits with 3 found the
|
|
126
|
+
* directory held, by a winner about to publish or by a sidecar still letting
|
|
127
|
+
* go, and is started again after a pause; any other exit is an error. A
|
|
128
|
+
* sidecar told to stop answers for a moment after it agreed, until SERVE
|
|
129
|
+
* goes, so the one of the instance stopped is passed over.
|
|
130
|
+
*/
|
|
131
|
+
async function startSidecar(runtime, serve, log, command, stoppedInstance) {
|
|
132
|
+
const deadline = Date.now() + startTime;
|
|
133
|
+
let held = false;
|
|
134
|
+
for (let pause = heldPause;; pause = Math.min(pause * 2, 1000)) {
|
|
135
|
+
const child = runtime.spawnDetached(command);
|
|
136
|
+
let exited;
|
|
137
|
+
child.exited.then(code => {
|
|
138
|
+
exited = code;
|
|
139
|
+
});
|
|
140
|
+
let again;
|
|
141
|
+
for (let wait = 5; Date.now() < deadline; wait = Math.min(wait * 2, 100)) {
|
|
142
|
+
const reached = await reachServe(runtime, serve);
|
|
143
|
+
if (reached !== undefined && reached.instance !== stoppedInstance) {
|
|
144
|
+
return reached.connection;
|
|
145
|
+
}
|
|
146
|
+
await reached?.connection.close();
|
|
147
|
+
if (exited !== undefined && exited !== 3) {
|
|
148
|
+
throw new ClosedError(`the sidecar exited with ${exited}: ${await tail(runtime, log)}`);
|
|
149
|
+
}
|
|
150
|
+
if (exited === 3) {
|
|
151
|
+
held = true;
|
|
152
|
+
again ??= Date.now() + pause;
|
|
153
|
+
if (Date.now() >= again) {
|
|
154
|
+
break;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
await sleep(wait);
|
|
158
|
+
}
|
|
159
|
+
if (Date.now() >= deadline) {
|
|
160
|
+
const why = held
|
|
161
|
+
? 'another process holds the directory but no sidecar answers'
|
|
162
|
+
: 'no sidecar answered';
|
|
163
|
+
throw new ClosedError(`${why} in ${startTime / 1000} s: ${await tail(runtime, log)}`);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Asks a sidecar to stop as tinystore stop does, closing the connection once
|
|
169
|
+
* it has answered; false when it refuses, and the connection stays open.
|
|
170
|
+
*/
|
|
171
|
+
async function stopped(connection) {
|
|
172
|
+
try {
|
|
173
|
+
await connection.session.call(methods['server.stop'], Empty.encode({}));
|
|
174
|
+
}
|
|
175
|
+
catch {
|
|
176
|
+
return false;
|
|
177
|
+
}
|
|
178
|
+
await connection.close();
|
|
179
|
+
return true;
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Whether a server's release is older than the SDK's own; a build that is no
|
|
183
|
+
* release, a development copy's or a Go pseudo-version, is neither.
|
|
184
|
+
*/
|
|
185
|
+
export function olderRelease(server, own) {
|
|
186
|
+
const theirs = release(server);
|
|
187
|
+
const ours = release(own);
|
|
188
|
+
return theirs !== undefined && ours !== undefined && compareReleases(theirs, ours) < 0;
|
|
189
|
+
}
|
|
190
|
+
/** What a program whose SDK replaced a sidecar of an older release is told. */
|
|
191
|
+
export function replacedSidecar(server, own, dir) {
|
|
192
|
+
return (`tinystore: the sidecar serving ${dir} was ${server}, older than this SDK's ${own}; it finishes ` +
|
|
193
|
+
"its calls, and this SDK's binary serves the directory from now on");
|
|
194
|
+
}
|
|
195
|
+
/** What a program whose SDK found a server of an older release that is no sidecar is told. */
|
|
196
|
+
export function olderServer(server, own, dir) {
|
|
197
|
+
return (`tinystore: ${dir} is served by ${server}, older than this SDK's ${own}; a person or a program ` +
|
|
198
|
+
'started that server, and it runs until they stop it');
|
|
199
|
+
}
|
|
200
|
+
/**
|
|
201
|
+
* A release's version, its v optional: 0.2.0, v0.2.0-rc.1. A development copy's
|
|
202
|
+
* 0.0.0, a Go pseudo-version and (devel) are none.
|
|
203
|
+
*/
|
|
204
|
+
function release(version) {
|
|
205
|
+
const parts = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.]+))?$/.exec(version);
|
|
206
|
+
if (parts === null) {
|
|
207
|
+
return undefined;
|
|
208
|
+
}
|
|
209
|
+
const core = [Number(parts[1]), Number(parts[2]), Number(parts[3])];
|
|
210
|
+
return core.every(n => n === 0)
|
|
211
|
+
? undefined
|
|
212
|
+
: { core, pre: parts[4] === undefined ? [] : parts[4].split('.') };
|
|
213
|
+
}
|
|
214
|
+
/** Semantic versioning's order: a release after its pre-releases, rc.2 before rc.10. */
|
|
215
|
+
function compareReleases(a, b) {
|
|
216
|
+
for (let i = 0; i < 3; i++) {
|
|
217
|
+
if (a.core[i] !== b.core[i]) {
|
|
218
|
+
return a.core[i] - b.core[i];
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
if (a.pre.length === 0 || b.pre.length === 0) {
|
|
222
|
+
return b.pre.length - a.pre.length;
|
|
223
|
+
}
|
|
224
|
+
for (let i = 0; i < Math.min(a.pre.length, b.pre.length); i++) {
|
|
225
|
+
const x = a.pre[i];
|
|
226
|
+
const y = b.pre[i];
|
|
227
|
+
const numbers = /^\d+$/.test(x) && /^\d+$/.test(y);
|
|
228
|
+
if (x !== y) {
|
|
229
|
+
return numbers ? Number(x) - Number(y) : x < y ? -1 : 1;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
return a.pre.length - b.pre.length;
|
|
233
|
+
}
|
|
234
|
+
/** The sidecar SERVE names, once its proof checks; undefined on any failure. */
|
|
235
|
+
async function reachServe(runtime, serve) {
|
|
236
|
+
let published;
|
|
237
|
+
try {
|
|
238
|
+
const text = await runtime.readFile(serve);
|
|
239
|
+
if (text === undefined) {
|
|
240
|
+
return undefined;
|
|
241
|
+
}
|
|
242
|
+
published = JSON.parse(new TextDecoder().decode(text));
|
|
243
|
+
}
|
|
244
|
+
catch {
|
|
245
|
+
return undefined;
|
|
246
|
+
}
|
|
247
|
+
const endpoint = published.endpoints?.[0];
|
|
248
|
+
const secret = Buffer.from(published.secret ?? '', 'base64url');
|
|
249
|
+
if (published.protocol !== 1 || endpoint === undefined || secret.length !== 32) {
|
|
250
|
+
return undefined;
|
|
251
|
+
}
|
|
252
|
+
try {
|
|
253
|
+
const connection = await Connection.dial(runtime, endpoint, {
|
|
254
|
+
client: runtime.client,
|
|
255
|
+
secret: new Uint8Array(secret),
|
|
256
|
+
challenge: new Uint8Array(randomBytes(16)),
|
|
257
|
+
});
|
|
258
|
+
return { connection, sidecar: published.sidecar === true, instance: published.instance };
|
|
259
|
+
}
|
|
260
|
+
catch {
|
|
261
|
+
return undefined;
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
function sleep(ms) {
|
|
265
|
+
return new Promise(resolve => setTimeout(resolve, ms));
|
|
266
|
+
}
|
|
267
|
+
async function tail(runtime, log) {
|
|
268
|
+
const text = await runtime.readFile(log).catch(() => undefined);
|
|
269
|
+
if (text === undefined) {
|
|
270
|
+
return 'it wrote no log';
|
|
271
|
+
}
|
|
272
|
+
const lines = new TextDecoder().decode(text).trimEnd().split('\n');
|
|
273
|
+
return lines.slice(-5).join('\n');
|
|
274
|
+
}
|
|
275
|
+
/** A private child: tinystore serve --stdio, living and dying with this process. */
|
|
276
|
+
export function privateChild(runtime, dir, binary, clock) {
|
|
277
|
+
// a test's clock starts where the first child's did, and a child started again starts it there
|
|
278
|
+
const clocked = clock === undefined ? [] : ['--clock', clock.toISOString()];
|
|
279
|
+
return async () => {
|
|
280
|
+
let session;
|
|
281
|
+
const argv = [binary(), 'serve', '--dir', resolve(dir), '--stdio', ...clocked];
|
|
282
|
+
const child = runtime.spawnPrivate(argv, {
|
|
283
|
+
data: bytes => session?.receive(bytes),
|
|
284
|
+
end: err => session?.end(err),
|
|
285
|
+
});
|
|
286
|
+
session = new Session(bytes => child.transport.write(bytes), { client: runtime.client });
|
|
287
|
+
session.onEnd(() => {
|
|
288
|
+
child.transport.close();
|
|
289
|
+
// a child told to leave by the end of its stdin drains and exits; one that does not is killed
|
|
290
|
+
const killer = setTimeout(() => child.kill(), 10_000);
|
|
291
|
+
child.exited.finally(() => clearTimeout(killer));
|
|
292
|
+
});
|
|
293
|
+
try {
|
|
294
|
+
return await Connection.overChild(child, session);
|
|
295
|
+
}
|
|
296
|
+
catch (err) {
|
|
297
|
+
child.kill();
|
|
298
|
+
throw new ClosedError(`the private server did not start: ${err.message}`);
|
|
299
|
+
}
|
|
300
|
+
};
|
|
301
|
+
}
|
|
302
|
+
/** A remote server: tls:// checks its certificate before the token leaves; tcp:// does not. */
|
|
303
|
+
export function remote(runtime, url, token, tls) {
|
|
304
|
+
return () => Connection.dial(runtime, url, { client: runtime.client, token }, tls);
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* Gives calls a connection, dialling again once the last one ended, and runs
|
|
308
|
+
* a call so that a lost connection costs it what it must: a call whose
|
|
309
|
+
* REQUEST had not left goes again, so does a read that had, and a write that
|
|
310
|
+
* had is OutcomeUnknownError.
|
|
311
|
+
*/
|
|
312
|
+
export class Link {
|
|
313
|
+
#dial;
|
|
314
|
+
#current;
|
|
315
|
+
#closed = false;
|
|
316
|
+
constructor(dial) {
|
|
317
|
+
this.#dial = dial;
|
|
318
|
+
}
|
|
319
|
+
/** The connection a call goes on. */
|
|
320
|
+
connection() {
|
|
321
|
+
if (this.#closed) {
|
|
322
|
+
return Promise.reject(new ClosedError('the store is closed'));
|
|
323
|
+
}
|
|
324
|
+
const current = this.#current;
|
|
325
|
+
if (current !== undefined) {
|
|
326
|
+
return current.then(c => (c.session.ended === undefined && !c.session.goingAway ? c : this.#redial(current)), () => this.#redial(current));
|
|
327
|
+
}
|
|
328
|
+
return this.#redial(undefined);
|
|
329
|
+
}
|
|
330
|
+
// one dial at a time: every caller that found the same dead connection
|
|
331
|
+
// waits for the one new one
|
|
332
|
+
#redial(dead) {
|
|
333
|
+
if (this.#current !== dead && this.#current !== undefined) {
|
|
334
|
+
return this.connection();
|
|
335
|
+
}
|
|
336
|
+
const dialled = this.#dial();
|
|
337
|
+
this.#current = dialled;
|
|
338
|
+
dialled.catch(() => {
|
|
339
|
+
if (this.#current === dialled) {
|
|
340
|
+
this.#current = undefined;
|
|
341
|
+
}
|
|
342
|
+
});
|
|
343
|
+
return dialled;
|
|
344
|
+
}
|
|
345
|
+
/**
|
|
346
|
+
* Runs a call on the link's connection. build makes its REQUEST's body for
|
|
347
|
+
* that connection, whose handles it may open; run sends it.
|
|
348
|
+
*/
|
|
349
|
+
async run(idempotence, attempt, signal) {
|
|
350
|
+
for (let tries = 0;; tries++) {
|
|
351
|
+
;
|
|
352
|
+
(signal ?? currentSignal())?.throwIfAborted();
|
|
353
|
+
const connection = await this.connection();
|
|
354
|
+
try {
|
|
355
|
+
return await attempt(connection);
|
|
356
|
+
}
|
|
357
|
+
catch (err) {
|
|
358
|
+
if (tries < 2 && (err instanceof LostError || err instanceof UnavailableError)) {
|
|
359
|
+
const sent = err instanceof LostError && err.sent;
|
|
360
|
+
if (!sent || idempotence === 'read') {
|
|
361
|
+
continue;
|
|
362
|
+
}
|
|
363
|
+
throw new OutcomeUnknownError(`the connection was lost with the write in flight; read what it wrote before writing again: ${err.message}`);
|
|
364
|
+
}
|
|
365
|
+
throw err;
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
/** Closes the connection and every one to come. */
|
|
370
|
+
async close() {
|
|
371
|
+
this.#closed = true;
|
|
372
|
+
const current = this.#current;
|
|
373
|
+
this.#current = undefined;
|
|
374
|
+
await current?.then(c => c.close(), () => { });
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
/**
|
|
378
|
+
* Runs a download to its end: the RESPONSE that heads it, an item a DATA, and
|
|
379
|
+
* the DATA that ends it, giving each item's credit back as it arrives, since
|
|
380
|
+
* the server bounds a page before it sends it. A download the server answers
|
|
381
|
+
* with a RESPONSE that ends it has no items and that RESPONSE for trailer.
|
|
382
|
+
*/
|
|
383
|
+
export async function download(connection, method, body, signal) {
|
|
384
|
+
signal?.throwIfAborted();
|
|
385
|
+
const stream = await connection.session.open(method, body, true);
|
|
386
|
+
const unwatch = watch(signal, stream);
|
|
387
|
+
try {
|
|
388
|
+
const head = await stream.next();
|
|
389
|
+
if (head.end) {
|
|
390
|
+
return { header: head.body, items: [], trailer: head.body };
|
|
391
|
+
}
|
|
392
|
+
const items = [];
|
|
393
|
+
for (;;) {
|
|
394
|
+
const event = await stream.next();
|
|
395
|
+
stream.consumed(event.body.length);
|
|
396
|
+
if (event.end) {
|
|
397
|
+
return { header: head.body, items, trailer: event.body };
|
|
398
|
+
}
|
|
399
|
+
items.push(event.body);
|
|
400
|
+
}
|
|
401
|
+
}
|
|
402
|
+
finally {
|
|
403
|
+
unwatch();
|
|
404
|
+
}
|
|
405
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/** How a logger writes its lines as they are logged; without one, pretty on a terminal and JSON otherwise. */
|
|
2
|
+
export type ConsoleFormat = 'pretty' | 'json' | 'off';
|
|
3
|
+
/** A line as a console writes it and the store keeps it: its fields already JSON. */
|
|
4
|
+
export interface ConsoleLine {
|
|
5
|
+
at: Date;
|
|
6
|
+
stream: string;
|
|
7
|
+
/** absent for an event */
|
|
8
|
+
level?: number;
|
|
9
|
+
/** an event's name; a log line has none */
|
|
10
|
+
event?: string;
|
|
11
|
+
msg?: string;
|
|
12
|
+
/** key, JSON, key, JSON…, as the wire carries fields */
|
|
13
|
+
context: readonly string[];
|
|
14
|
+
attrs: readonly string[];
|
|
15
|
+
/** 32 hex digits */
|
|
16
|
+
traceId?: string;
|
|
17
|
+
/** 16 hex digits */
|
|
18
|
+
spanId?: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* A line as one JSON object and a newline, its keys in this order: time,
|
|
22
|
+
* level, stream, event, msg, the context's fields, the attributes', the trace
|
|
23
|
+
* and span. The time is UTC to the millisecond; a key repeated stays repeated.
|
|
24
|
+
*/
|
|
25
|
+
export declare function jsonLine(line: ConsoleLine): string;
|
|
26
|
+
/**
|
|
27
|
+
* A line as a person reads it: the time of day, the level padded to five, the
|
|
28
|
+
* stream, the message, the context's fields and the attributes', and the
|
|
29
|
+
* trace's first eight digits. A value of several lines, a stack or a
|
|
30
|
+
* traceback, follows the line, indented. A key or a string shows without its
|
|
31
|
+
* quotes when it is one word with no '=', quote or backslash.
|
|
32
|
+
*/
|
|
33
|
+
export declare function prettyLine(line: ConsoleLine, color: boolean, utc?: boolean): string;
|
|
34
|
+
/** A level as slog spells it: INFO, WARN+2, DEBUG-4. */
|
|
35
|
+
export declare function levelLabel(level: number): string;
|
|
36
|
+
/**
|
|
37
|
+
* Says whether a field's key hides its value: the key, or the part of a dotted
|
|
38
|
+
* key after its last dot, is one of the names, the case ignored.
|
|
39
|
+
*/
|
|
40
|
+
export declare function redactor(names: readonly string[] | undefined): ((key: string) => boolean) | undefined;
|
|
41
|
+
/** What a hidden value becomes, in the store and on the console. */
|
|
42
|
+
export declare const redacted = "\"[redacted]\"";
|
|
43
|
+
/**
|
|
44
|
+
* A value as JSON, its keys at any depth hidden as hides says; a bigint is its
|
|
45
|
+
* digits, and what JSON cannot write is its text, so that a line is never lost
|
|
46
|
+
* to one field.
|
|
47
|
+
*/
|
|
48
|
+
export declare function jsonOf(value: unknown, hides?: (key: string) => boolean): string;
|
package/dist/console.js
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
// A logger's console line, as Go's records.Handler and Python's handler write
|
|
2
|
+
// it, byte for byte the lines of records/testdata/console.json: pretty for a
|
|
3
|
+
// person at a terminal, one JSON object a line for a collector.
|
|
4
|
+
//
|
|
5
|
+
// 11:02:11.123 WARN api slow request requestId=7f3a ms=1200
|
|
6
|
+
// {"time":"2026-10-02T11:02:11.123Z","level":"WARN","stream":"api","msg":"slow request","requestId":"7f3a","ms":1200}
|
|
7
|
+
/**
|
|
8
|
+
* A line as one JSON object and a newline, its keys in this order: time,
|
|
9
|
+
* level, stream, event, msg, the context's fields, the attributes', the trace
|
|
10
|
+
* and span. The time is UTC to the millisecond; a key repeated stays repeated.
|
|
11
|
+
*/
|
|
12
|
+
export function jsonLine(line) {
|
|
13
|
+
let out = `{"time":"${line.at.toISOString()}"`;
|
|
14
|
+
if (line.level !== undefined) {
|
|
15
|
+
out += `,"level":${JSON.stringify(levelLabel(line.level))}`;
|
|
16
|
+
}
|
|
17
|
+
out += `,"stream":${JSON.stringify(line.stream)}`;
|
|
18
|
+
if (line.event !== undefined) {
|
|
19
|
+
out += `,"event":${JSON.stringify(line.event)}`;
|
|
20
|
+
}
|
|
21
|
+
if (line.msg !== undefined) {
|
|
22
|
+
out += `,"msg":${JSON.stringify(line.msg)}`;
|
|
23
|
+
}
|
|
24
|
+
for (const fields of [line.context, line.attrs]) {
|
|
25
|
+
for (let i = 0; i < fields.length; i += 2) {
|
|
26
|
+
out += `,${JSON.stringify(fields[i])}:${fields[i + 1]}`;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
if (line.traceId !== undefined) {
|
|
30
|
+
out += `,"trace_id":"${line.traceId}"`;
|
|
31
|
+
}
|
|
32
|
+
if (line.spanId !== undefined) {
|
|
33
|
+
out += `,"span_id":"${line.spanId}"`;
|
|
34
|
+
}
|
|
35
|
+
return `${out}}\n`;
|
|
36
|
+
}
|
|
37
|
+
// the terminal's own sixteen colours, so that its theme chooses the shades
|
|
38
|
+
const reset = '\x1b[0m';
|
|
39
|
+
const dim = '\x1b[2m';
|
|
40
|
+
const red = '\x1b[31m';
|
|
41
|
+
const green = '\x1b[32m';
|
|
42
|
+
const yellow = '\x1b[33m';
|
|
43
|
+
const blue = '\x1b[34m';
|
|
44
|
+
const magenta = '\x1b[35m';
|
|
45
|
+
const cyan = '\x1b[36m';
|
|
46
|
+
/**
|
|
47
|
+
* A line as a person reads it: the time of day, the level padded to five, the
|
|
48
|
+
* stream, the message, the context's fields and the attributes', and the
|
|
49
|
+
* trace's first eight digits. A value of several lines, a stack or a
|
|
50
|
+
* traceback, follows the line, indented. A key or a string shows without its
|
|
51
|
+
* quotes when it is one word with no '=', quote or backslash.
|
|
52
|
+
*/
|
|
53
|
+
export function prettyLine(line, color, utc = false) {
|
|
54
|
+
const paint = (hue, text) => (color ? hue + text + reset : text);
|
|
55
|
+
const [label, hue] = prettyLevel(line.level);
|
|
56
|
+
let out = `${paint(dim, clock(line.at, utc))} ${paint(hue, label)}${' '.repeat(Math.max(0, 5 - label.length))}`;
|
|
57
|
+
out += ` ${paint(cyan, line.stream)}`;
|
|
58
|
+
const message = prettyMessage(line);
|
|
59
|
+
if (message !== '') {
|
|
60
|
+
out += ` ${message}`;
|
|
61
|
+
}
|
|
62
|
+
let separator = ' ';
|
|
63
|
+
const field = (key, text) => {
|
|
64
|
+
out += `${separator}${paint(dim, `${bare(key) ? key : JSON.stringify(key)}=`)}${text}`;
|
|
65
|
+
separator = ' ';
|
|
66
|
+
};
|
|
67
|
+
const below = [];
|
|
68
|
+
for (const fields of [line.context, line.attrs]) {
|
|
69
|
+
for (let i = 0; i < fields.length; i += 2) {
|
|
70
|
+
const [shown, lines] = prettyValue(fields[i + 1]);
|
|
71
|
+
if (lines) {
|
|
72
|
+
below.push([fields[i], shown]);
|
|
73
|
+
}
|
|
74
|
+
else {
|
|
75
|
+
field(fields[i], shown);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
if (line.traceId !== undefined) {
|
|
80
|
+
field('trace', line.traceId.slice(0, 8));
|
|
81
|
+
}
|
|
82
|
+
for (const [key, text] of below) {
|
|
83
|
+
text
|
|
84
|
+
.replace(/[\r\n]+$/, '')
|
|
85
|
+
.split('\n')
|
|
86
|
+
.forEach((part, i) => {
|
|
87
|
+
const shown = part.replace(/\r$/, '');
|
|
88
|
+
out += `\n ${paint(dim, i === 0 ? `${key}: ${shown}` : shown)}`;
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
return `${out}\n`;
|
|
92
|
+
}
|
|
93
|
+
/** A level as slog spells it: INFO, WARN+2, DEBUG-4. */
|
|
94
|
+
export function levelLabel(level) {
|
|
95
|
+
const spell = (base, from) => {
|
|
96
|
+
const off = level - from;
|
|
97
|
+
return off === 0 ? base : `${base}${off > 0 ? '+' : ''}${off}`;
|
|
98
|
+
};
|
|
99
|
+
if (level < 0) {
|
|
100
|
+
return spell('DEBUG', -4);
|
|
101
|
+
}
|
|
102
|
+
if (level < 4) {
|
|
103
|
+
return spell('INFO', 0);
|
|
104
|
+
}
|
|
105
|
+
if (level < 8) {
|
|
106
|
+
return spell('WARN', 4);
|
|
107
|
+
}
|
|
108
|
+
return spell('ERROR', 8);
|
|
109
|
+
}
|
|
110
|
+
function prettyLevel(level) {
|
|
111
|
+
if (level === undefined) {
|
|
112
|
+
return ['EVENT', magenta];
|
|
113
|
+
}
|
|
114
|
+
const hue = level < 0 ? blue : level < 4 ? green : level < 8 ? yellow : red;
|
|
115
|
+
return [levelLabel(level), hue];
|
|
116
|
+
}
|
|
117
|
+
function prettyMessage(line) {
|
|
118
|
+
const body = line.msg ?? '';
|
|
119
|
+
if (line.event === undefined) {
|
|
120
|
+
return body;
|
|
121
|
+
}
|
|
122
|
+
return body === '' ? line.event : `${line.event} ${body}`;
|
|
123
|
+
}
|
|
124
|
+
/** How a field's JSON shows, and whether it is text of several lines, which goes under the line. */
|
|
125
|
+
function prettyValue(json) {
|
|
126
|
+
if (!json.startsWith('"')) {
|
|
127
|
+
return [json, false];
|
|
128
|
+
}
|
|
129
|
+
const text = JSON.parse(json);
|
|
130
|
+
if (text.includes('\n')) {
|
|
131
|
+
return [text, true];
|
|
132
|
+
}
|
|
133
|
+
return [bare(text) ? text : json, false];
|
|
134
|
+
}
|
|
135
|
+
/** One word a person reads without its quotes: no character a space or below, DEL, '"', '=' or '\'. */
|
|
136
|
+
function bare(text) {
|
|
137
|
+
if (text === '') {
|
|
138
|
+
return false;
|
|
139
|
+
}
|
|
140
|
+
for (const c of text) {
|
|
141
|
+
const code = c.codePointAt(0);
|
|
142
|
+
if (code <= 0x20 || code === 0x7f || c === '"' || c === '=' || c === '\\') {
|
|
143
|
+
return false;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
return true;
|
|
147
|
+
}
|
|
148
|
+
function clock(at, utc) {
|
|
149
|
+
const parts = utc
|
|
150
|
+
? [at.getUTCHours(), at.getUTCMinutes(), at.getUTCSeconds()]
|
|
151
|
+
: [at.getHours(), at.getMinutes(), at.getSeconds()];
|
|
152
|
+
const millis = utc ? at.getUTCMilliseconds() : at.getMilliseconds();
|
|
153
|
+
return `${parts.map(n => String(n).padStart(2, '0')).join(':')}.${String(millis).padStart(3, '0')}`;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Says whether a field's key hides its value: the key, or the part of a dotted
|
|
157
|
+
* key after its last dot, is one of the names, the case ignored.
|
|
158
|
+
*/
|
|
159
|
+
export function redactor(names) {
|
|
160
|
+
if (names === undefined || names.length === 0) {
|
|
161
|
+
return undefined;
|
|
162
|
+
}
|
|
163
|
+
const hidden = new Set(names.map(name => name.toLowerCase()));
|
|
164
|
+
return key => {
|
|
165
|
+
const lower = key.toLowerCase();
|
|
166
|
+
return hidden.has(lower) || hidden.has(lower.slice(lower.lastIndexOf('.') + 1));
|
|
167
|
+
};
|
|
168
|
+
}
|
|
169
|
+
/** What a hidden value becomes, in the store and on the console. */
|
|
170
|
+
export const redacted = '"[redacted]"';
|
|
171
|
+
/**
|
|
172
|
+
* A value as JSON, its keys at any depth hidden as hides says; a bigint is its
|
|
173
|
+
* digits, and what JSON cannot write is its text, so that a line is never lost
|
|
174
|
+
* to one field.
|
|
175
|
+
*/
|
|
176
|
+
export function jsonOf(value, hides) {
|
|
177
|
+
if (typeof value === 'bigint') {
|
|
178
|
+
return value.toString();
|
|
179
|
+
}
|
|
180
|
+
try {
|
|
181
|
+
const json = JSON.stringify(value, (key, inner) => {
|
|
182
|
+
if (key !== '' && hides?.(key)) {
|
|
183
|
+
return '[redacted]';
|
|
184
|
+
}
|
|
185
|
+
return typeof inner === 'bigint' ? inner.toString() : inner;
|
|
186
|
+
});
|
|
187
|
+
if (json !== undefined) {
|
|
188
|
+
return json;
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
catch {
|
|
192
|
+
// a cycle, or a toJSON that throws: the value's text below
|
|
193
|
+
}
|
|
194
|
+
return JSON.stringify(String(value));
|
|
195
|
+
}
|