@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/session.js
ADDED
|
@@ -0,0 +1,546 @@
|
|
|
1
|
+
// A connection's protocol, without its bytes' way there and back: frames in,
|
|
2
|
+
// frames out, streams, credit both ways, PING, GOAWAY and cancelling, as
|
|
3
|
+
// docs/wire.md says them. The transport hands it what it read and takes what
|
|
4
|
+
// it writes; nothing here waits on a socket, so the same code serves a Unix
|
|
5
|
+
// socket, a Windows pipe, a child's stdio and TLS.
|
|
6
|
+
import { createHmac, timingSafeEqual } from 'node:crypto';
|
|
7
|
+
import { currentSignal } from './cancel.js';
|
|
8
|
+
import { CancelledError, ClosedError, errorOf, LimitError, ProtocolError, UnavailableError, } from './errors.js';
|
|
9
|
+
import { checkHeader, credit, Flag, frame, granted, Kind, kindName, parseHeader, } from './wire/frame.js';
|
|
10
|
+
import { Failure, GoAway, Hello, Welcome } from './wire/messages.js';
|
|
11
|
+
export const protocol = 1;
|
|
12
|
+
/** What this client lets the server send on a stream before it grants more: a body at least. */
|
|
13
|
+
export const downloadWindow = 2 << 20;
|
|
14
|
+
/** The largest body a WELCOME may come in, before a body is agreed. */
|
|
15
|
+
const welcomeMost = 1 << 20;
|
|
16
|
+
/**
|
|
17
|
+
* The connection was lost with a stream on it. Sent says whether its REQUEST
|
|
18
|
+
* had left: one that had not may go on another connection whatever it was,
|
|
19
|
+
* and one that had is a read to send again or a write whose outcome is
|
|
20
|
+
* unknown.
|
|
21
|
+
*/
|
|
22
|
+
export class LostError extends ClosedError {
|
|
23
|
+
sent;
|
|
24
|
+
constructor(message, sent) {
|
|
25
|
+
super(message);
|
|
26
|
+
this.sent = sent;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* One stream: a client's REQUEST from its frame to the server's final frame,
|
|
31
|
+
* the one span in which its number is in use.
|
|
32
|
+
*/
|
|
33
|
+
export class Stream {
|
|
34
|
+
id;
|
|
35
|
+
method;
|
|
36
|
+
/** the REQUEST has left, so the server may have acted on it */
|
|
37
|
+
sent = false;
|
|
38
|
+
/** the server's final frame came, or the connection ended */
|
|
39
|
+
finished = false;
|
|
40
|
+
#events = [];
|
|
41
|
+
#waiting;
|
|
42
|
+
#failure;
|
|
43
|
+
#session;
|
|
44
|
+
#uploadCredit;
|
|
45
|
+
#creditWaiters = [];
|
|
46
|
+
#granting = 0;
|
|
47
|
+
#cancelled = false;
|
|
48
|
+
constructor(session, id, method, uploadCredit) {
|
|
49
|
+
this.#session = session;
|
|
50
|
+
this.id = id;
|
|
51
|
+
this.method = method;
|
|
52
|
+
this.#uploadCredit = uploadCredit;
|
|
53
|
+
}
|
|
54
|
+
/** The next frame of the answer, or its error. */
|
|
55
|
+
next() {
|
|
56
|
+
const event = this.#events.shift();
|
|
57
|
+
if (event !== undefined) {
|
|
58
|
+
return Promise.resolve(event);
|
|
59
|
+
}
|
|
60
|
+
if (this.#failure !== undefined) {
|
|
61
|
+
return Promise.reject(this.#failure);
|
|
62
|
+
}
|
|
63
|
+
return new Promise((resolve, reject) => {
|
|
64
|
+
this.#waiting = { resolve, reject };
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Sends a body of an upload as DATA once the stream's credit lets it go;
|
|
69
|
+
* end says it is the last. Only an empty body ending the upload may be
|
|
70
|
+
* empty.
|
|
71
|
+
*/
|
|
72
|
+
async send(body, end) {
|
|
73
|
+
while (!this.finished && this.#uploadCredit < body.length) {
|
|
74
|
+
await new Promise((resolve, reject) => this.#creditWaiters.push({ resolve, reject }));
|
|
75
|
+
}
|
|
76
|
+
if (this.finished) {
|
|
77
|
+
throw this.#failure ?? new ClosedError('the stream ended before its upload did');
|
|
78
|
+
}
|
|
79
|
+
this.#uploadCredit -= body.length;
|
|
80
|
+
this.#session.enqueue(this, frame(Kind.data, end ? Flag.end : 0, 0, this.id, body), body.length);
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Gives back what a DATA the server sent took of the stream's credit, once
|
|
84
|
+
* the caller has done with it; a grant goes once half the window has.
|
|
85
|
+
*/
|
|
86
|
+
consumed(n) {
|
|
87
|
+
if (this.finished) {
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
this.#granting += n;
|
|
91
|
+
if (this.#granting >= downloadWindow / 2) {
|
|
92
|
+
this.#session.post(credit(this.id, this.#granting));
|
|
93
|
+
this.#granting = 0;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Asks the server to stop. A stream whose REQUEST has not left never
|
|
98
|
+
* leaves; one that has keeps its number until the server's final frame,
|
|
99
|
+
* which is dropped.
|
|
100
|
+
*/
|
|
101
|
+
cancel() {
|
|
102
|
+
if (this.finished || this.#cancelled) {
|
|
103
|
+
return;
|
|
104
|
+
}
|
|
105
|
+
this.#cancelled = true;
|
|
106
|
+
this.#session.cancel(this);
|
|
107
|
+
this.fail(new CancelledError('the call was cancelled'));
|
|
108
|
+
}
|
|
109
|
+
get cancelled() {
|
|
110
|
+
return this.#cancelled;
|
|
111
|
+
}
|
|
112
|
+
deliver(event) {
|
|
113
|
+
if (this.#cancelled) {
|
|
114
|
+
return;
|
|
115
|
+
}
|
|
116
|
+
const waiting = this.#waiting;
|
|
117
|
+
if (waiting !== undefined) {
|
|
118
|
+
this.#waiting = undefined;
|
|
119
|
+
waiting.resolve(event);
|
|
120
|
+
return;
|
|
121
|
+
}
|
|
122
|
+
this.#events.push(event);
|
|
123
|
+
}
|
|
124
|
+
/** Ends what waits on the stream with err; events already arrived are read first. */
|
|
125
|
+
fail(err) {
|
|
126
|
+
this.#failure ??= err;
|
|
127
|
+
const waiting = this.#waiting;
|
|
128
|
+
this.#waiting = undefined;
|
|
129
|
+
waiting?.reject(err);
|
|
130
|
+
for (const w of this.#creditWaiters.splice(0)) {
|
|
131
|
+
w.reject(err);
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
grant(n) {
|
|
135
|
+
this.#uploadCredit += n;
|
|
136
|
+
for (const w of this.#creditWaiters.splice(0)) {
|
|
137
|
+
w.resolve();
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
finish() {
|
|
141
|
+
this.finished = true;
|
|
142
|
+
for (const w of this.#creditWaiters.splice(0)) {
|
|
143
|
+
w.resolve();
|
|
144
|
+
}
|
|
145
|
+
this.#unwatch?.();
|
|
146
|
+
this.#unwatch = undefined;
|
|
147
|
+
}
|
|
148
|
+
/** Cancels the stream when the signal aborts, until the stream finishes. */
|
|
149
|
+
watchSignal(signal) {
|
|
150
|
+
this.#unwatch = watch(signal, this);
|
|
151
|
+
}
|
|
152
|
+
#unwatch;
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* The protocol of one connection. It writes through send, which the
|
|
156
|
+
* transport takes whole, and reads what receive is given, frames split
|
|
157
|
+
* anywhere.
|
|
158
|
+
*/
|
|
159
|
+
export class Session {
|
|
160
|
+
#send;
|
|
161
|
+
#options;
|
|
162
|
+
/** resolves with what the WELCOME agreed, or rejects with why there is none */
|
|
163
|
+
welcomed;
|
|
164
|
+
#welcome;
|
|
165
|
+
#agreed;
|
|
166
|
+
#streams = new Map();
|
|
167
|
+
#next = 0;
|
|
168
|
+
#waitingToOpen = [];
|
|
169
|
+
#queue = [];
|
|
170
|
+
#credit = 0;
|
|
171
|
+
#out = [];
|
|
172
|
+
#outBytes = 0;
|
|
173
|
+
#flushing = false;
|
|
174
|
+
#rest;
|
|
175
|
+
#goingAway = false;
|
|
176
|
+
#ended;
|
|
177
|
+
#endListeners = [];
|
|
178
|
+
constructor(send, options) {
|
|
179
|
+
this.#send = send;
|
|
180
|
+
this.#options = options;
|
|
181
|
+
let welcome;
|
|
182
|
+
this.welcomed = new Promise((resolve, reject) => {
|
|
183
|
+
welcome = { resolve, reject };
|
|
184
|
+
});
|
|
185
|
+
this.#welcome = welcome;
|
|
186
|
+
// a caller that never awaits the handshake still hears of its end
|
|
187
|
+
this.welcomed.catch(() => { });
|
|
188
|
+
this.post(frame(Kind.hello, 0, 0, 0, Hello.encode({
|
|
189
|
+
protocol,
|
|
190
|
+
client: options.client,
|
|
191
|
+
token: options.token,
|
|
192
|
+
streamCredit: downloadWindow,
|
|
193
|
+
challenge: options.challenge,
|
|
194
|
+
})));
|
|
195
|
+
}
|
|
196
|
+
get agreed() {
|
|
197
|
+
return this.#agreed;
|
|
198
|
+
}
|
|
199
|
+
/** The server said GOAWAY: no stream opens here any more. */
|
|
200
|
+
get goingAway() {
|
|
201
|
+
return this.#goingAway;
|
|
202
|
+
}
|
|
203
|
+
/** Why the connection ended, once it has. */
|
|
204
|
+
get ended() {
|
|
205
|
+
return this.#ended;
|
|
206
|
+
}
|
|
207
|
+
/** Streams in use, their final frames not yet come. */
|
|
208
|
+
get streams() {
|
|
209
|
+
return this.#streams.size;
|
|
210
|
+
}
|
|
211
|
+
onEnd(listener) {
|
|
212
|
+
if (this.#ended !== undefined) {
|
|
213
|
+
listener(this.#ended);
|
|
214
|
+
return;
|
|
215
|
+
}
|
|
216
|
+
this.#endListeners.push(listener);
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Opens a stream with its REQUEST. End says the REQUEST is the client's
|
|
220
|
+
* whole side; an upload's DATA follows through the stream otherwise. It
|
|
221
|
+
* waits while the streams in flight are all in use.
|
|
222
|
+
*/
|
|
223
|
+
async open(method, body, end) {
|
|
224
|
+
const signal = currentSignal();
|
|
225
|
+
signal?.throwIfAborted();
|
|
226
|
+
const agreed = await this.welcomed;
|
|
227
|
+
if (body.length > agreed.maxBody) {
|
|
228
|
+
throw new LimitError(`a request of ${body.length} bytes, past the ${agreed.maxBody} a body holds`);
|
|
229
|
+
}
|
|
230
|
+
while (this.#streams.size >= agreed.inFlight && this.#usable() === undefined) {
|
|
231
|
+
await new Promise((resolve, reject) => this.#waitingToOpen.push({ resolve, reject }));
|
|
232
|
+
}
|
|
233
|
+
const refused = this.#usable();
|
|
234
|
+
if (refused !== undefined) {
|
|
235
|
+
throw refused;
|
|
236
|
+
}
|
|
237
|
+
const stream = new Stream(this, this.#nextID(), method, agreed.streamCredit);
|
|
238
|
+
this.#streams.set(stream.id, stream);
|
|
239
|
+
this.#enqueue({
|
|
240
|
+
stream,
|
|
241
|
+
bytes: frame(Kind.request, end ? Flag.end : 0, method, stream.id, body),
|
|
242
|
+
counted: body.length,
|
|
243
|
+
request: true,
|
|
244
|
+
});
|
|
245
|
+
if (signal !== undefined) {
|
|
246
|
+
stream.watchSignal(signal);
|
|
247
|
+
}
|
|
248
|
+
return stream;
|
|
249
|
+
}
|
|
250
|
+
/** Why no stream may open now: the connection ended or is going away. */
|
|
251
|
+
#usable() {
|
|
252
|
+
if (this.#ended !== undefined) {
|
|
253
|
+
return new LostError(`the connection ended: ${this.#ended.message}`, false);
|
|
254
|
+
}
|
|
255
|
+
if (this.#goingAway) {
|
|
256
|
+
return new UnavailableError('the server is closing this connection');
|
|
257
|
+
}
|
|
258
|
+
return undefined;
|
|
259
|
+
}
|
|
260
|
+
/** A call: one REQUEST, and the RESPONSE that answers it. */
|
|
261
|
+
async call(method, body, signal) {
|
|
262
|
+
signal?.throwIfAborted();
|
|
263
|
+
const stream = await this.open(method, body, true);
|
|
264
|
+
const unwatch = watch(signal, stream);
|
|
265
|
+
try {
|
|
266
|
+
const event = await stream.next();
|
|
267
|
+
if (event.kind !== 'response' || !event.end) {
|
|
268
|
+
this.fault(new ProtocolError(`a ${event.kind} without END answering a call on stream ${stream.id}`));
|
|
269
|
+
}
|
|
270
|
+
return event.body;
|
|
271
|
+
}
|
|
272
|
+
finally {
|
|
273
|
+
unwatch();
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
// a stream's number: from 1, never 0 and never one in use, so that a frame
|
|
277
|
+
// for a stream that has ended never reaches the next one
|
|
278
|
+
#nextID() {
|
|
279
|
+
for (;;) {
|
|
280
|
+
this.#next = this.#next === 0xffff_ffff ? 1 : this.#next + 1;
|
|
281
|
+
if (!this.#streams.has(this.#next)) {
|
|
282
|
+
return this.#next;
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
enqueue(stream, bytes, counted) {
|
|
287
|
+
this.#enqueue({ stream, bytes, counted, request: false });
|
|
288
|
+
}
|
|
289
|
+
#enqueue(q) {
|
|
290
|
+
this.#queue.push(q);
|
|
291
|
+
this.#drain();
|
|
292
|
+
}
|
|
293
|
+
// frames that count against the connection's credit leave in the order
|
|
294
|
+
// they were asked for, as far as the credit goes
|
|
295
|
+
#drain() {
|
|
296
|
+
while (this.#queue.length > 0) {
|
|
297
|
+
const q = this.#queue[0];
|
|
298
|
+
if (q.counted > this.#credit) {
|
|
299
|
+
return;
|
|
300
|
+
}
|
|
301
|
+
this.#queue.shift();
|
|
302
|
+
this.#credit -= q.counted;
|
|
303
|
+
if (q.request) {
|
|
304
|
+
q.stream.sent = true;
|
|
305
|
+
}
|
|
306
|
+
this.post(q.bytes);
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
/** Writes a frame that does not wait for credit: a CREDIT, a CANCEL, a PONG. */
|
|
310
|
+
post(bytes) {
|
|
311
|
+
if (this.#ended !== undefined) {
|
|
312
|
+
return;
|
|
313
|
+
}
|
|
314
|
+
this.#out.push(bytes);
|
|
315
|
+
this.#outBytes += bytes.length;
|
|
316
|
+
if (!this.#flushing) {
|
|
317
|
+
this.#flushing = true;
|
|
318
|
+
queueMicrotask(() => this.#flush());
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
// the frames asked for in one turn leave in one write
|
|
322
|
+
#flush() {
|
|
323
|
+
this.#flushing = false;
|
|
324
|
+
if (this.#out.length === 0 || this.#ended !== undefined) {
|
|
325
|
+
return;
|
|
326
|
+
}
|
|
327
|
+
let bytes;
|
|
328
|
+
if (this.#out.length === 1) {
|
|
329
|
+
bytes = this.#out[0];
|
|
330
|
+
}
|
|
331
|
+
else {
|
|
332
|
+
bytes = new Uint8Array(this.#outBytes);
|
|
333
|
+
let at = 0;
|
|
334
|
+
for (const each of this.#out) {
|
|
335
|
+
bytes.set(each, at);
|
|
336
|
+
at += each.length;
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
this.#out = [];
|
|
340
|
+
this.#outBytes = 0;
|
|
341
|
+
this.#send(bytes);
|
|
342
|
+
}
|
|
343
|
+
cancel(stream) {
|
|
344
|
+
if (!stream.sent) {
|
|
345
|
+
this.#queue = this.#queue.filter(q => q.stream !== stream);
|
|
346
|
+
this.#release(stream);
|
|
347
|
+
return;
|
|
348
|
+
}
|
|
349
|
+
this.post(frame(Kind.cancel, 0, 0, stream.id, new Uint8Array(0)));
|
|
350
|
+
}
|
|
351
|
+
// takes a stream out of use, dropping what of it has not left: its number
|
|
352
|
+
// may be named again at once
|
|
353
|
+
#release(stream) {
|
|
354
|
+
stream.finish();
|
|
355
|
+
if (this.#streams.get(stream.id) === stream) {
|
|
356
|
+
this.#streams.delete(stream.id);
|
|
357
|
+
}
|
|
358
|
+
this.#queue = this.#queue.filter(q => q.stream !== stream || q.request);
|
|
359
|
+
this.#waitingToOpen.shift()?.resolve();
|
|
360
|
+
}
|
|
361
|
+
/** Takes bytes the transport read: any part of a frame, or several. */
|
|
362
|
+
receive(chunk) {
|
|
363
|
+
if (this.#ended !== undefined) {
|
|
364
|
+
return;
|
|
365
|
+
}
|
|
366
|
+
let bytes = chunk;
|
|
367
|
+
if (this.#rest !== undefined) {
|
|
368
|
+
bytes = new Uint8Array(this.#rest.length + chunk.length);
|
|
369
|
+
bytes.set(this.#rest);
|
|
370
|
+
bytes.set(chunk, this.#rest.length);
|
|
371
|
+
this.#rest = undefined;
|
|
372
|
+
}
|
|
373
|
+
let at = 0;
|
|
374
|
+
try {
|
|
375
|
+
while (bytes.length - at >= 12) {
|
|
376
|
+
const h = parseHeader(bytes, at);
|
|
377
|
+
checkHeader(h, this.#agreed?.maxBody ?? welcomeMost);
|
|
378
|
+
const stop = at + 12 + h.length;
|
|
379
|
+
if (stop > bytes.length) {
|
|
380
|
+
break;
|
|
381
|
+
}
|
|
382
|
+
// a body of its own, since events outlive the read's buffer
|
|
383
|
+
this.#take(h, bytes.slice(at + 12, stop));
|
|
384
|
+
at = stop;
|
|
385
|
+
}
|
|
386
|
+
}
|
|
387
|
+
catch (err) {
|
|
388
|
+
this.fault(err instanceof Error ? err : new ProtocolError(String(err)));
|
|
389
|
+
return;
|
|
390
|
+
}
|
|
391
|
+
if (at < bytes.length) {
|
|
392
|
+
this.#rest = bytes.slice(at);
|
|
393
|
+
}
|
|
394
|
+
}
|
|
395
|
+
#take(h, body) {
|
|
396
|
+
if (this.#agreed === undefined) {
|
|
397
|
+
this.#handshake(h.kind, body);
|
|
398
|
+
return;
|
|
399
|
+
}
|
|
400
|
+
switch (h.kind) {
|
|
401
|
+
case Kind.response:
|
|
402
|
+
case Kind.data:
|
|
403
|
+
this.#answer(h.kind, h.flags, h.stream, body);
|
|
404
|
+
return;
|
|
405
|
+
case Kind.credit:
|
|
406
|
+
this.#credited(h.stream, granted(body));
|
|
407
|
+
return;
|
|
408
|
+
case Kind.ping:
|
|
409
|
+
this.post(frame(Kind.pong, 0, 0, 0, body));
|
|
410
|
+
return;
|
|
411
|
+
case Kind.pong:
|
|
412
|
+
return;
|
|
413
|
+
case Kind.goaway:
|
|
414
|
+
this.#goAway(body);
|
|
415
|
+
return;
|
|
416
|
+
}
|
|
417
|
+
throw new ProtocolError(`a ${kindName(h.kind)} from the server`);
|
|
418
|
+
}
|
|
419
|
+
#handshake(kind, body) {
|
|
420
|
+
if (kind === Kind.goaway) {
|
|
421
|
+
const away = GoAway.decode(body);
|
|
422
|
+
this.end(errorOf(away.code ?? 'unavailable', away.message ?? 'the server refused the connection'));
|
|
423
|
+
return;
|
|
424
|
+
}
|
|
425
|
+
if (kind !== Kind.welcome) {
|
|
426
|
+
throw new ProtocolError(`a ${kindName(kind)} where the WELCOME belongs`);
|
|
427
|
+
}
|
|
428
|
+
const welcome = Welcome.decode(body);
|
|
429
|
+
if (welcome.protocol !== protocol) {
|
|
430
|
+
throw new ProtocolError(`the server speaks protocol ${welcome.protocol}, not ${protocol}`);
|
|
431
|
+
}
|
|
432
|
+
const { secret, challenge } = this.#options;
|
|
433
|
+
if (secret !== undefined &&
|
|
434
|
+
challenge !== undefined &&
|
|
435
|
+
!proves(secret, challenge, welcome.proof)) {
|
|
436
|
+
throw new ProtocolError('the server cannot prove it read SERVE: another process holds its endpoint');
|
|
437
|
+
}
|
|
438
|
+
const agreed = {
|
|
439
|
+
protocol: welcome.protocol,
|
|
440
|
+
server: welcome.server ?? '',
|
|
441
|
+
instance: welcome.instance ?? new Uint8Array(0),
|
|
442
|
+
capability: welcome.capability ?? 'data',
|
|
443
|
+
maxBody: welcome.maxBody ?? 0,
|
|
444
|
+
inFlight: welcome.inFlight ?? 1,
|
|
445
|
+
connectionCredit: welcome.connectionCredit ?? 0,
|
|
446
|
+
streamCredit: welcome.streamCredit ?? 0,
|
|
447
|
+
engines: welcome.engines ?? [],
|
|
448
|
+
now: welcome.now ?? 0,
|
|
449
|
+
};
|
|
450
|
+
this.#agreed = agreed;
|
|
451
|
+
this.#credit = agreed.connectionCredit;
|
|
452
|
+
this.#welcome.resolve(agreed);
|
|
453
|
+
}
|
|
454
|
+
#answer(kind, flags, id, body) {
|
|
455
|
+
const stream = this.#streams.get(id);
|
|
456
|
+
if (stream === undefined) {
|
|
457
|
+
throw new ProtocolError(`a ${kindName(kind)} on stream ${id}, which is not in use`);
|
|
458
|
+
}
|
|
459
|
+
const end = (flags & Flag.end) !== 0;
|
|
460
|
+
if (end) {
|
|
461
|
+
this.#release(stream);
|
|
462
|
+
}
|
|
463
|
+
if ((flags & Flag.error) !== 0) {
|
|
464
|
+
stream.fail(failureOf(body));
|
|
465
|
+
return;
|
|
466
|
+
}
|
|
467
|
+
stream.deliver({ kind: kind === Kind.response ? 'response' : 'data', body, end });
|
|
468
|
+
if (stream.cancelled && kind === Kind.data) {
|
|
469
|
+
stream.consumed(body.length);
|
|
470
|
+
}
|
|
471
|
+
}
|
|
472
|
+
#credited(id, n) {
|
|
473
|
+
if (id === 0) {
|
|
474
|
+
this.#credit += n;
|
|
475
|
+
this.#drain();
|
|
476
|
+
return;
|
|
477
|
+
}
|
|
478
|
+
this.#streams.get(id)?.grant(n);
|
|
479
|
+
}
|
|
480
|
+
// after a GOAWAY no stream opens; a REQUEST still waiting for credit goes
|
|
481
|
+
// nowhere and may be sent on another connection
|
|
482
|
+
#goAway(body) {
|
|
483
|
+
const away = GoAway.decode(body);
|
|
484
|
+
this.#goingAway = true;
|
|
485
|
+
const unsent = new UnavailableError(away.message ?? 'the server is closing this connection');
|
|
486
|
+
for (const q of this.#queue.filter(q => q.request)) {
|
|
487
|
+
q.stream.fail(unsent);
|
|
488
|
+
this.#release(q.stream);
|
|
489
|
+
}
|
|
490
|
+
for (const w of this.#waitingToOpen.splice(0)) {
|
|
491
|
+
w.reject(unsent);
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
/** A frame broke the protocol: the connection ends, and whoever runs it closes it. */
|
|
495
|
+
fault(err) {
|
|
496
|
+
this.end(err instanceof ProtocolError ? err : new ProtocolError(err.message));
|
|
497
|
+
}
|
|
498
|
+
/**
|
|
499
|
+
* Ends the session: the transport closed, or a frame broke the protocol.
|
|
500
|
+
* Every stream still open learns whether its REQUEST had left.
|
|
501
|
+
*/
|
|
502
|
+
end(err) {
|
|
503
|
+
if (this.#ended !== undefined) {
|
|
504
|
+
return;
|
|
505
|
+
}
|
|
506
|
+
this.#ended = err;
|
|
507
|
+
this.#welcome.reject(err);
|
|
508
|
+
for (const stream of this.#streams.values()) {
|
|
509
|
+
stream.fail(new LostError(`the connection ended: ${err.message}`, stream.sent));
|
|
510
|
+
stream.finish();
|
|
511
|
+
}
|
|
512
|
+
this.#streams.clear();
|
|
513
|
+
this.#queue = [];
|
|
514
|
+
for (const w of this.#waitingToOpen.splice(0)) {
|
|
515
|
+
w.reject(new LostError(`the connection ended: ${err.message}`, false));
|
|
516
|
+
}
|
|
517
|
+
for (const listener of this.#endListeners.splice(0)) {
|
|
518
|
+
listener(err);
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
}
|
|
522
|
+
/** Cancels a stream when a signal aborts; returns what stops watching. */
|
|
523
|
+
export function watch(signal, stream) {
|
|
524
|
+
if (signal === undefined) {
|
|
525
|
+
return () => { };
|
|
526
|
+
}
|
|
527
|
+
const cancel = () => stream.cancel();
|
|
528
|
+
if (signal.aborted) {
|
|
529
|
+
cancel();
|
|
530
|
+
return () => { };
|
|
531
|
+
}
|
|
532
|
+
signal.addEventListener('abort', cancel, { once: true });
|
|
533
|
+
return () => signal.removeEventListener('abort', cancel);
|
|
534
|
+
}
|
|
535
|
+
/** The error a final frame with ERROR carries. */
|
|
536
|
+
export function failureOf(body) {
|
|
537
|
+
const failure = Failure.decode(body);
|
|
538
|
+
return errorOf(failure.code ?? 'internal', failure.message ?? '', failure.what ?? {});
|
|
539
|
+
}
|
|
540
|
+
/** A WELCOME's proof is the HMAC-SHA256 of the challenge keyed with SERVE's secret. */
|
|
541
|
+
export function proves(secret, challenge, proof) {
|
|
542
|
+
if (proof === undefined || proof.length !== 32) {
|
|
543
|
+
return false;
|
|
544
|
+
}
|
|
545
|
+
return timingSafeEqual(createHmac('sha256', secret).update(challenge).digest(), proof);
|
|
546
|
+
}
|
package/dist/sql.d.ts
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
import type { Connection, Link } from './connection.ts';
|
|
2
|
+
import { type Settled } from './handles.ts';
|
|
3
|
+
import type { SqlArg, SqlValue } from './wire/codec.ts';
|
|
4
|
+
import { type JobsJob, SqlResults, SqlStatement } from './wire/messages.ts';
|
|
5
|
+
export type { SqlArg, SqlValue };
|
|
6
|
+
/** A row as SQLite returned it, by its columns' names. */
|
|
7
|
+
export type Row = Record<string, SqlValue>;
|
|
8
|
+
/**
|
|
9
|
+
* A database's migrations: a directory whose .sql files they are, at its root
|
|
10
|
+
* or in its one directory, or the files themselves by name.
|
|
11
|
+
*/
|
|
12
|
+
export type Migrations = string | Record<string, string> | readonly {
|
|
13
|
+
name: string;
|
|
14
|
+
text: string;
|
|
15
|
+
}[];
|
|
16
|
+
export interface SqlOptions {
|
|
17
|
+
/** what the first open applies, on an admin connection, and every later open checks */
|
|
18
|
+
migrations?: Migrations;
|
|
19
|
+
}
|
|
20
|
+
/** What a write changed: the rows, and the rowid of the last it inserted. */
|
|
21
|
+
export interface Done {
|
|
22
|
+
changes: number;
|
|
23
|
+
lastId: number;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* A statement's text and arguments, in any of the three ways a call takes
|
|
27
|
+
* them: positional after the text, one object of named ones, or a template
|
|
28
|
+
* whose values are its arguments.
|
|
29
|
+
*
|
|
30
|
+
* db.all('select * from notes where id = ?', id)
|
|
31
|
+
* db.all('select * from notes where id = :id', { id })
|
|
32
|
+
* db.all`select * from notes where id = ${id}`
|
|
33
|
+
*/
|
|
34
|
+
export type Statement = [sql: string | TemplateStringsArray, ...args: unknown[]];
|
|
35
|
+
/** Opens a database by its name, applying or checking its migrations. */
|
|
36
|
+
export declare function openDatabase(link: Link, name: string, options?: SqlOptions): Promise<Database>;
|
|
37
|
+
/**
|
|
38
|
+
* A database. What a call's name starts with says where it runs: exec and
|
|
39
|
+
* its kin may write and run on the file's one writer, grouped with the other
|
|
40
|
+
* writes; all, one, scalar and each read, on readers that refuse to write.
|
|
41
|
+
*/
|
|
42
|
+
export declare class Database {
|
|
43
|
+
#private;
|
|
44
|
+
readonly name: string;
|
|
45
|
+
constructor(link: Link, name: string, open: Uint8Array);
|
|
46
|
+
handle(connection: Connection): Promise<number>;
|
|
47
|
+
/** Every row a query answers, held in memory: the server refuses past 64 MiB of them. */
|
|
48
|
+
all<T = Row>(...statement: Statement): Promise<T[]>;
|
|
49
|
+
/** The one row a query answers, undefined for none; two is InvalidError. */
|
|
50
|
+
one<T = Row>(...statement: Statement): Promise<T | undefined>;
|
|
51
|
+
/** The one value of a query that always answers one row, as count(*) does. */
|
|
52
|
+
scalar<T = SqlValue>(...statement: Statement): Promise<T>;
|
|
53
|
+
/** The columns and rows of a query as SQLite returned them, arrays rather than objects. */
|
|
54
|
+
query(...statement: Statement): Promise<{
|
|
55
|
+
columns: string[];
|
|
56
|
+
rows: SqlValue[][];
|
|
57
|
+
}>;
|
|
58
|
+
/**
|
|
59
|
+
* Reads a query's rows one at a time as they arrive, within the credit
|
|
60
|
+
* the client grants: the client holds a row and the frames in flight.
|
|
61
|
+
*/
|
|
62
|
+
each<T = Row>(...statement: Statement): AsyncGenerator<T>;
|
|
63
|
+
/** Runs a statement on the writer and says what it changed. */
|
|
64
|
+
exec(...statement: Statement): Promise<Done>;
|
|
65
|
+
/** The rows a write's returning clause answers, run on the writer. */
|
|
66
|
+
execAll<T = Row>(...statement: Statement): Promise<T[]>;
|
|
67
|
+
execOne<T = Row>(...statement: Statement): Promise<T | undefined>;
|
|
68
|
+
execScalar<T = SqlValue>(...statement: Statement): Promise<T>;
|
|
69
|
+
/**
|
|
70
|
+
* Runs the statements fn asks for in one transaction, all or none: a
|
|
71
|
+
* failure names its statement as `call`. fn returns before anything is
|
|
72
|
+
* sent, since no transaction is held across the network, and what it
|
|
73
|
+
* returns comes back answered, an array's promises each:
|
|
74
|
+
*
|
|
75
|
+
* const [note] = await db.batch(tx => [tx.one`insert into notes (title) values (${t}) returning *`])
|
|
76
|
+
*/
|
|
77
|
+
batch<const T = void>(fn: (tx: SqlBatch) => T): Promise<Settled<T>>;
|
|
78
|
+
/**
|
|
79
|
+
* Runs the reads fn asks for from one snapshot, and gives back what fn
|
|
80
|
+
* returns, answered as batch answers it:
|
|
81
|
+
*
|
|
82
|
+
* const [notes, total] = await db.view(tx => [tx.all`select * from notes`, tx.scalar`select count(*) from notes`])
|
|
83
|
+
*/
|
|
84
|
+
view<const T = void>(fn: (tx: SqlBatch) => T): Promise<Settled<T>>;
|
|
85
|
+
}
|
|
86
|
+
type Result = ReturnType<typeof SqlResults.decode>['results'] extends (infer R)[] | undefined ? R : never;
|
|
87
|
+
interface Batched {
|
|
88
|
+
statement: Parameters<typeof SqlStatement.encode>[0];
|
|
89
|
+
settle: (result: Result) => void;
|
|
90
|
+
fail: (err: unknown) => void;
|
|
91
|
+
}
|
|
92
|
+
/** A job a batch enqueues after its statements, on a queue that lives in its database. */
|
|
93
|
+
interface Queued {
|
|
94
|
+
/** the queue's jobs.open, whose handle the batch opens on its connection */
|
|
95
|
+
open: Uint8Array;
|
|
96
|
+
job: Parameters<typeof JobsJob.encode>[0];
|
|
97
|
+
settle: () => void;
|
|
98
|
+
fail: (err: unknown) => void;
|
|
99
|
+
}
|
|
100
|
+
/** The statements of a batch or a view, whose promises settle with it. */
|
|
101
|
+
export declare class SqlBatch {
|
|
102
|
+
#private;
|
|
103
|
+
readonly read: boolean;
|
|
104
|
+
/** the database the batch runs in, whose queues alone take its jobs */
|
|
105
|
+
readonly database: string;
|
|
106
|
+
readonly statements: Batched[];
|
|
107
|
+
readonly jobs: Queued[];
|
|
108
|
+
constructor(read: boolean, database: string);
|
|
109
|
+
close(): void;
|
|
110
|
+
/** Whether the promise is one of this batch's statements', rather than an async function's. */
|
|
111
|
+
made(promise: Promise<unknown>): boolean;
|
|
112
|
+
/**
|
|
113
|
+
* Adds a job to the batch, for a queue's withTx: a program writes
|
|
114
|
+
* `queue.withTx(tx).enqueue(value)`, on a queue opened `in` this database.
|
|
115
|
+
*/
|
|
116
|
+
enqueue(open: Uint8Array, job: Queued['job']): Promise<void>;
|
|
117
|
+
exec(...statement: Statement): Promise<Done>;
|
|
118
|
+
all<T = Row>(...statement: Statement): Promise<T[]>;
|
|
119
|
+
one<T = Row>(...statement: Statement): Promise<T | undefined>;
|
|
120
|
+
scalar<T = SqlValue>(...statement: Statement): Promise<T>;
|
|
121
|
+
}
|