@tinyshed/tinystore 0.1.0-rc.4 → 0.1.0-rc.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -37
- package/bin/tinystore.js +12 -1
- package/dist/backup.d.ts +33 -0
- package/dist/backup.js +49 -0
- package/dist/blobs.d.ts +160 -79
- package/dist/blobs.js +510 -217
- package/dist/channels.d.ts +90 -0
- package/dist/channels.js +291 -0
- package/dist/clock.js +3 -3
- package/dist/config.d.ts +209 -86
- package/dist/config.js +581 -538
- package/dist/connection.d.ts +64 -2
- package/dist/connection.js +201 -16
- package/dist/console.d.ts +27 -3
- package/dist/console.js +165 -12
- package/dist/dotenv.d.ts +7 -0
- package/dist/dotenv.js +79 -0
- package/dist/errors.d.ts +61 -1
- package/dist/errors.js +81 -1
- package/dist/handles.d.ts +44 -2
- package/dist/handles.js +81 -2
- package/dist/index.d.ts +17 -11
- package/dist/index.js +5 -3
- package/dist/instruments.d.ts +177 -0
- package/dist/instruments.js +819 -0
- package/dist/jobs.d.ts +335 -239
- package/dist/jobs.js +716 -536
- package/dist/json.d.ts +2 -0
- package/dist/json.js +122 -0
- package/dist/kv.d.ts +130 -243
- package/dist/kv.js +273 -640
- package/dist/limits.d.ts +80 -0
- package/dist/limits.js +139 -0
- package/dist/locks.d.ts +62 -0
- package/dist/locks.js +237 -0
- package/dist/logger.d.ts +45 -9
- package/dist/logger.js +150 -38
- package/dist/metrics.d.ts +210 -209
- package/dist/metrics.js +319 -556
- package/dist/once.d.ts +19 -18
- package/dist/once.js +74 -63
- package/dist/query.d.ts +181 -0
- package/dist/query.js +788 -0
- package/dist/records.d.ts +241 -150
- package/dist/records.js +507 -291
- package/dist/runtime/addon.d.ts +14 -0
- package/dist/runtime/addon.js +69 -0
- package/dist/runtime/bun.js +5 -7
- package/dist/runtime/node.js +5 -7
- package/dist/runtime/pipe.d.ts +17 -0
- package/dist/runtime/pipe.js +133 -0
- package/dist/runtime/shared.d.ts +6 -0
- package/dist/runtime/shared.js +19 -0
- package/dist/runtime.d.ts +5 -2
- package/dist/search.d.ts +189 -0
- package/dist/search.js +281 -0
- package/dist/session.d.ts +31 -3
- package/dist/session.js +153 -41
- package/dist/sql.d.ts +228 -78
- package/dist/sql.js +745 -240
- package/dist/store.d.ts +244 -24
- package/dist/store.js +270 -67
- package/dist/time.d.ts +5 -1
- package/dist/time.js +22 -2
- package/dist/tx.d.ts +61 -0
- package/dist/tx.js +314 -0
- package/dist/wire/codec.d.ts +23 -7
- package/dist/wire/codec.js +56 -35
- package/dist/wire/frame.d.ts +2 -0
- package/dist/wire/frame.js +31 -14
- package/dist/wire/messages.d.ts +259 -0
- package/dist/wire/messages.js +22 -0
- package/dist/wire/msgpack.d.ts +49 -1
- package/dist/wire/msgpack.js +293 -56
- package/dist/wire/protocol.d.ts +2683 -0
- package/dist/wire/protocol.js +10846 -0
- package/package.json +39 -38
- package/src/backup.ts +81 -0
- package/src/blobs.ts +678 -301
- package/src/channels.ts +377 -0
- package/src/clock.ts +4 -4
- package/src/config.ts +902 -612
- package/src/connection.ts +279 -21
- package/src/console.ts +180 -12
- package/src/dotenv.ts +82 -0
- package/src/errors.ts +105 -0
- package/src/handles.ts +157 -8
- package/src/index.ts +158 -52
- package/src/instruments.ts +1042 -0
- package/src/jobs.ts +1017 -733
- package/src/json.ts +133 -0
- package/src/kv.ts +424 -847
- package/src/limits.ts +202 -0
- package/src/locks.ts +320 -0
- package/src/logger.ts +209 -40
- package/src/metrics.ts +557 -752
- package/src/once.ts +86 -83
- package/src/query.ts +1005 -0
- package/src/records.ts +795 -418
- package/src/runtime/addon.ts +99 -0
- package/src/runtime/bun.ts +5 -7
- package/src/runtime/node.ts +5 -7
- package/src/runtime/pipe.ts +178 -0
- package/src/runtime/shared.ts +20 -0
- package/src/runtime.ts +5 -2
- package/src/search.ts +480 -0
- package/src/session.ts +187 -41
- package/src/sql.ts +993 -306
- package/src/store.ts +473 -78
- package/src/time.ts +48 -3
- package/src/tx.ts +426 -0
- package/src/wire/codec.ts +78 -37
- package/src/wire/frame.ts +44 -14
- package/src/wire/messages.ts +25 -0
- package/src/wire/msgpack.ts +327 -56
- package/src/wire/protocol.ts +11709 -0
- package/dist/limiter.d.ts +0 -45
- package/dist/limiter.js +0 -68
- package/dist/quota.d.ts +0 -44
- package/dist/quota.js +0 -98
- package/src/limiter.ts +0 -99
- package/src/quota.ts +0 -137
package/dist/search.js
ADDED
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
// Search, as docs/guides/search/README.md has it: documents of one type set by id in a
|
|
2
|
+
// named index and found again by their words, by vectors the program's own
|
|
3
|
+
// model gives them, or by both, kept to the documents a `where` passes. A
|
|
4
|
+
// search answers the exact best ten, or `limit`, of what the index holds; an
|
|
5
|
+
// index opened with `recall` answers its vectors from clusters. A table's
|
|
6
|
+
// index, `db.searchIndex`, finds a database's rows, each hit its row.
|
|
7
|
+
import { InvalidError } from './errors.js';
|
|
8
|
+
import { checkName, viaLink } from './handles.js';
|
|
9
|
+
import { parseJson } from './json.js';
|
|
10
|
+
import { keyText } from './kv.js';
|
|
11
|
+
import { rowsOf } from './sql.js';
|
|
12
|
+
import { Empty, Handle, methods, SearchDeleted, SearchDropped, SearchFound, SearchGot, SearchKey, SearchListed, SearchName, SearchOpen, SearchQuery, SearchSet, SearchSetMany, SearchStatus, } from './wire/protocol.js';
|
|
13
|
+
/** Conditions joined: `search.or(…)`, `search.and(…)`. */
|
|
14
|
+
export class Group {
|
|
15
|
+
join;
|
|
16
|
+
parts;
|
|
17
|
+
/** A group comes from `search.or` and `search.and`. */
|
|
18
|
+
constructor(join, parts) {
|
|
19
|
+
this.join = join;
|
|
20
|
+
this.parts = parts;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
/** How often `ready` asks whether a rebuild switched in. */
|
|
24
|
+
const readyEvery = 100;
|
|
25
|
+
/** What every index answers: its searches, and where it stands. */
|
|
26
|
+
class Searchable {
|
|
27
|
+
name;
|
|
28
|
+
#via;
|
|
29
|
+
#open;
|
|
30
|
+
constructor(via, name, open) {
|
|
31
|
+
this.name = name;
|
|
32
|
+
this.#via = via;
|
|
33
|
+
this.#open = open;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* The best ten, or `limit`, by `text`'s words, a string being a search
|
|
37
|
+
* by its words; by a vector; or by both, each half's best hundred scaled
|
|
38
|
+
* and summed at the index's `vectorWeight`; kept to what `where` passes.
|
|
39
|
+
* Of equal scores the one set first comes first.
|
|
40
|
+
*/
|
|
41
|
+
async search(query) {
|
|
42
|
+
const asked = typeof query === 'string' ? { text: query } : query;
|
|
43
|
+
const vector = asked.vector === undefined ? undefined : vectorBytes(asked.vector);
|
|
44
|
+
const where = asked.where === undefined ? undefined : whereJson(asked.where);
|
|
45
|
+
const body = (handle) => SearchQuery.encode({
|
|
46
|
+
handle,
|
|
47
|
+
text: asked.text ?? '',
|
|
48
|
+
vector,
|
|
49
|
+
vectorWeight: asked.hybrid?.vectorWeight,
|
|
50
|
+
rerank: asked.hybrid?.rerank,
|
|
51
|
+
where,
|
|
52
|
+
offset: asked.offset,
|
|
53
|
+
limit: asked.limit,
|
|
54
|
+
});
|
|
55
|
+
const found = SearchFound.decode(await this.call('search.search', body, 'read'));
|
|
56
|
+
const columns = found.columns;
|
|
57
|
+
const hits = (found.hits ?? []).map(hit => ({
|
|
58
|
+
id: hit.id ?? '',
|
|
59
|
+
value: (columns === undefined
|
|
60
|
+
? parseJson(hit.value ?? 'null')
|
|
61
|
+
: rowsOf(columns, [(hit.row ?? [])])[0]),
|
|
62
|
+
score: hit.score ?? 0,
|
|
63
|
+
}));
|
|
64
|
+
return found.corrected === undefined ? { hits } : { hits, corrected: found.corrected };
|
|
65
|
+
}
|
|
66
|
+
/** Where the index stands; a search never waits, and answers by the settings it serves. */
|
|
67
|
+
async status() {
|
|
68
|
+
const answer = await this.call('search.status', handle => Handle.encode({ handle }), 'read');
|
|
69
|
+
return statusOf(SearchStatus.decode(answer));
|
|
70
|
+
}
|
|
71
|
+
/** Waits until the index serves the settings it was opened with; a rebuild that failed throws why. */
|
|
72
|
+
async ready() {
|
|
73
|
+
for (;;) {
|
|
74
|
+
const status = await this.status();
|
|
75
|
+
if (status.state === 'ready') {
|
|
76
|
+
return;
|
|
77
|
+
}
|
|
78
|
+
if (status.state === 'failed') {
|
|
79
|
+
throw new InvalidError(`index ${this.name}: its rebuild failed: ${status.error}`);
|
|
80
|
+
}
|
|
81
|
+
await new Promise(resolve => setTimeout(resolve, readyEvery));
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
call(method, body, idempotence) {
|
|
85
|
+
return this.#via.call(methods['search.open'], this.#open, methods[method], body, idempotence);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
/** Documents of one type by id, found again by their words, vectors or both: `store.index(name, options)`. */
|
|
89
|
+
export class SearchIndex extends Searchable {
|
|
90
|
+
/** An index comes from `store.index` and `store.reindex`. */
|
|
91
|
+
constructor(link, name, open) {
|
|
92
|
+
super(viaLink(link), name, open);
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Sets the document `id` to `value`, replacing it whole; the next search
|
|
96
|
+
* sees it. On an index with vectors a set gives its vector, or `null` for
|
|
97
|
+
* a document only its words find.
|
|
98
|
+
*/
|
|
99
|
+
async set(id, value, options) {
|
|
100
|
+
const said = vectorSaid(options?.vector);
|
|
101
|
+
const json = documentJson(this.name, value);
|
|
102
|
+
await this.call('search.set', handle => SearchSet.encode({ handle, id: keyText(id), value: json, ...said }), 'write');
|
|
103
|
+
}
|
|
104
|
+
/** Sets every document in one commit, all of them or none: 1,000 and 16 MiB at most. */
|
|
105
|
+
async setMany(documents) {
|
|
106
|
+
const encoded = documents.map(document => ({
|
|
107
|
+
id: keyText(document.id),
|
|
108
|
+
value: documentJson(this.name, document.value),
|
|
109
|
+
...vectorSaid(document.vector),
|
|
110
|
+
}));
|
|
111
|
+
await this.call('search.setMany', handle => SearchSetMany.encode({ handle, documents: encoded }), 'write');
|
|
112
|
+
}
|
|
113
|
+
/** Deletes the document `id`; says whether there was one. */
|
|
114
|
+
async delete(id) {
|
|
115
|
+
const answer = await this.call('search.delete', handle => SearchKey.encode({ handle, id: keyText(id) }), 'write');
|
|
116
|
+
return SearchDeleted.decode(answer).deleted ?? false;
|
|
117
|
+
}
|
|
118
|
+
/** The document `id`, or undefined. */
|
|
119
|
+
async get(id) {
|
|
120
|
+
const answer = await this.call('search.get', handle => SearchKey.encode({ handle, id: keyText(id) }), 'read');
|
|
121
|
+
const got = SearchGot.decode(answer);
|
|
122
|
+
return got.found && got.value !== undefined ? parseJson(got.value) : undefined;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* A table's rows found again by their words, vectors or both, each hit's
|
|
127
|
+
* value its row as `db.all` reads it: `db.searchIndex(name, options)`. The
|
|
128
|
+
* table owns the rows, and every change of one reaches the index in the
|
|
129
|
+
* commit that makes it.
|
|
130
|
+
*/
|
|
131
|
+
export class TableIndex extends Searchable {
|
|
132
|
+
}
|
|
133
|
+
/** The open of a table's index: its name, its table and settings, and its database's handle. */
|
|
134
|
+
export function tableIndexOpen(name, options, database, reindex = false) {
|
|
135
|
+
checkName(name, 'index');
|
|
136
|
+
return SearchOpen.encode({
|
|
137
|
+
name,
|
|
138
|
+
fields: fieldsOf(options.fields),
|
|
139
|
+
filters: [...(options.filters ?? [])],
|
|
140
|
+
typoTolerance: options.typoTolerance,
|
|
141
|
+
dimensions: options.vectors?.dimensions,
|
|
142
|
+
recall: options.vectors?.recall,
|
|
143
|
+
vectorWeight: options.hybrid?.vectorWeight,
|
|
144
|
+
rerank: options.hybrid?.rerank,
|
|
145
|
+
manual: options.rebuild === 'manual',
|
|
146
|
+
reindex,
|
|
147
|
+
database,
|
|
148
|
+
table: options.table,
|
|
149
|
+
key: options.key,
|
|
150
|
+
vectorColumn: options.vectors?.column,
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
function fieldsOf(fields) {
|
|
154
|
+
return Array.isArray(fields)
|
|
155
|
+
? fields.map(path => ({ path, weight: 1 }))
|
|
156
|
+
: Object.entries(fields ?? {}).map(([path, weight]) => ({ path, weight }));
|
|
157
|
+
}
|
|
158
|
+
/** The open of an index: its name, settings, and whether it reads the index again. */
|
|
159
|
+
export function indexOpen(name, options = {}, reindex = false) {
|
|
160
|
+
checkName(name, 'index');
|
|
161
|
+
return SearchOpen.encode({
|
|
162
|
+
name,
|
|
163
|
+
fields: fieldsOf(options.fields),
|
|
164
|
+
filters: [...(options.filters ?? [])],
|
|
165
|
+
typoTolerance: options.typoTolerance,
|
|
166
|
+
dimensions: options.vectors?.dimensions,
|
|
167
|
+
recall: options.vectors?.recall,
|
|
168
|
+
vectorWeight: options.hybrid?.vectorWeight,
|
|
169
|
+
rerank: options.hybrid?.rerank,
|
|
170
|
+
manual: options.rebuild === 'manual',
|
|
171
|
+
reindex,
|
|
172
|
+
});
|
|
173
|
+
}
|
|
174
|
+
/** Drops an index and every document it holds; says whether there was one. */
|
|
175
|
+
export async function dropIndex(link, name) {
|
|
176
|
+
checkName(name, 'index');
|
|
177
|
+
const answer = await link.run('write', connection => connection.session.call(methods['search.dropIndex'], SearchName.encode({ name })));
|
|
178
|
+
return SearchDropped.decode(answer).dropped ?? false;
|
|
179
|
+
}
|
|
180
|
+
/** Every index the store holds, by name. */
|
|
181
|
+
export async function listIndexes(link) {
|
|
182
|
+
const answer = await link.run('read', connection => connection.session.call(methods['search.list'], Empty.encode({})));
|
|
183
|
+
return (SearchListed.decode(answer).indexes ?? []).map(index => {
|
|
184
|
+
const info = {
|
|
185
|
+
name: index.name ?? '',
|
|
186
|
+
documents: index.documents ?? 0,
|
|
187
|
+
vectors: index.vectors ?? 0,
|
|
188
|
+
status: statusOf(index),
|
|
189
|
+
};
|
|
190
|
+
if (index.opened !== undefined) {
|
|
191
|
+
info.opened = new Date(index.opened);
|
|
192
|
+
}
|
|
193
|
+
return info;
|
|
194
|
+
});
|
|
195
|
+
}
|
|
196
|
+
function statusOf(status) {
|
|
197
|
+
switch (status.state) {
|
|
198
|
+
case 'rebuilding':
|
|
199
|
+
return { state: 'rebuilding', done: status.done ?? 0 };
|
|
200
|
+
case 'failed':
|
|
201
|
+
return { state: 'failed', error: status.error ?? '' };
|
|
202
|
+
default:
|
|
203
|
+
return { state: 'ready' };
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
function documentJson(name, value) {
|
|
207
|
+
const json = JSON.stringify(value);
|
|
208
|
+
if (json === undefined) {
|
|
209
|
+
throw new InvalidError(`index ${name}: a document that does not write as JSON`);
|
|
210
|
+
}
|
|
211
|
+
return json;
|
|
212
|
+
}
|
|
213
|
+
/** What a set says of its vector: its bytes, none, or nothing. */
|
|
214
|
+
function vectorSaid(vector) {
|
|
215
|
+
if (vector === undefined) {
|
|
216
|
+
return {};
|
|
217
|
+
}
|
|
218
|
+
return vector === null ? { noVector: true } : { vector: vectorBytes(vector) };
|
|
219
|
+
}
|
|
220
|
+
/** A vector's floats' bytes, little-endian, four a dimension. */
|
|
221
|
+
function vectorBytes(vector) {
|
|
222
|
+
const floats = vector instanceof Float32Array ? vector : Float32Array.from(vector);
|
|
223
|
+
const bytes = new Uint8Array(floats.length * 4);
|
|
224
|
+
const view = new DataView(bytes.buffer);
|
|
225
|
+
for (const [at, value] of floats.entries()) {
|
|
226
|
+
view.setFloat32(at * 4, value, true);
|
|
227
|
+
}
|
|
228
|
+
return bytes;
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* A `where` as the wire takes it, a JSON list of conditions joined by and:
|
|
232
|
+
* `{"eq":[path,value]}`, `{"in":[path,[values]]}`, `{"missing":path}`,
|
|
233
|
+
* `{"range":[path,{"gt"|"gte"|"lt"|"lte":n}]}`, `{"or":[…]}`, `{"and":[…]}`.
|
|
234
|
+
*/
|
|
235
|
+
export function whereJson(where) {
|
|
236
|
+
return `[${conditions(where).join(',')}]`;
|
|
237
|
+
}
|
|
238
|
+
function conditions(where) {
|
|
239
|
+
if (where instanceof Group) {
|
|
240
|
+
const parts = where.parts.map(part => `{"and":[${conditions(part).join(',')}]}`);
|
|
241
|
+
return [`{"${where.join}":[${parts.join(',')}]}`];
|
|
242
|
+
}
|
|
243
|
+
return Object.entries(where).map(([path, value]) => condition(path, value));
|
|
244
|
+
}
|
|
245
|
+
function condition(path, value) {
|
|
246
|
+
const at = JSON.stringify(path);
|
|
247
|
+
if (value === undefined) {
|
|
248
|
+
throw new InvalidError(`a where of ${path}: undefined; leave ${path} out to ask nothing of it, or null for no value`);
|
|
249
|
+
}
|
|
250
|
+
if (value === null) {
|
|
251
|
+
return `{"missing":${at}}`;
|
|
252
|
+
}
|
|
253
|
+
if (Array.isArray(value)) {
|
|
254
|
+
return `{"in":[${at},[${value.map(scalar).join(',')}]]}`;
|
|
255
|
+
}
|
|
256
|
+
if (typeof value === 'object') {
|
|
257
|
+
const bounds = Object.entries(value).map(([bound, n]) => {
|
|
258
|
+
if (!['gt', 'gte', 'lt', 'lte'].includes(bound)) {
|
|
259
|
+
throw new InvalidError(`a where of ${path}: ${bound}, not gt, gte, lt or lte`);
|
|
260
|
+
}
|
|
261
|
+
return `${JSON.stringify(bound)}:${scalar(n)}`;
|
|
262
|
+
});
|
|
263
|
+
return `{"range":[${at},{${bounds.join(',')}}]}`;
|
|
264
|
+
}
|
|
265
|
+
return `{"eq":[${at},${scalar(value)}]}`;
|
|
266
|
+
}
|
|
267
|
+
/** A value as JSON, a bigint as its digits so that an id of 19 digits matches as it is. */
|
|
268
|
+
function scalar(value) {
|
|
269
|
+
if (typeof value === 'bigint') {
|
|
270
|
+
return value.toString();
|
|
271
|
+
}
|
|
272
|
+
if (typeof value === 'number' && !Number.isFinite(value)) {
|
|
273
|
+
throw new InvalidError(`a where's value ${value}, which is no number JSON writes`);
|
|
274
|
+
}
|
|
275
|
+
return JSON.stringify(value);
|
|
276
|
+
}
|
|
277
|
+
/** The conditions a `where` groups: `search.or({ category: 'boots' }, { tags: 'sale' })`. */
|
|
278
|
+
export const search = {
|
|
279
|
+
or: (...parts) => new Group('or', parts),
|
|
280
|
+
and: (...parts) => new Group('and', parts),
|
|
281
|
+
};
|
package/dist/session.d.ts
CHANGED
|
@@ -1,10 +1,18 @@
|
|
|
1
1
|
import { ClosedError, type TinystoreError } from './errors.ts';
|
|
2
2
|
import type { Read } from './wire/codec.ts';
|
|
3
|
-
import {
|
|
3
|
+
import { Reader, Writer } from './wire/msgpack.ts';
|
|
4
|
+
import { Welcome } from './wire/protocol.ts';
|
|
4
5
|
export declare const protocol = 1;
|
|
5
6
|
/** What this client lets the server send on a stream before it grants more: a body at least. */
|
|
6
7
|
export declare const downloadWindow: number;
|
|
7
|
-
export type Agreed =
|
|
8
|
+
export type Agreed = Given<Omit<Read<typeof Welcome.fields>, 'proof' | 'durability'>> & {
|
|
9
|
+
/** how far the store's files' commits go, when it was opened with one: full or os */
|
|
10
|
+
durability: string | undefined;
|
|
11
|
+
};
|
|
12
|
+
/** Every field of a message read, each with a value: one the message left out is at its zero. */
|
|
13
|
+
type Given<T> = {
|
|
14
|
+
[K in keyof T]-?: Exclude<T[K], undefined>;
|
|
15
|
+
};
|
|
8
16
|
export interface SessionOptions {
|
|
9
17
|
/** a name and version, for the server's logs */
|
|
10
18
|
client: string;
|
|
@@ -21,7 +29,7 @@ export interface SessionOptions {
|
|
|
21
29
|
* and one that had is a read to send again or a write whose outcome is
|
|
22
30
|
* unknown.
|
|
23
31
|
*/
|
|
24
|
-
export declare class
|
|
32
|
+
export declare class ConnectionLostError extends ClosedError {
|
|
25
33
|
readonly sent: boolean;
|
|
26
34
|
constructor(message: string, sent: boolean);
|
|
27
35
|
}
|
|
@@ -96,6 +104,18 @@ export declare class Session {
|
|
|
96
104
|
* waits while the streams in flight are all in use.
|
|
97
105
|
*/
|
|
98
106
|
open(method: number, body: Uint8Array, end: boolean): Promise<Stream>;
|
|
107
|
+
/**
|
|
108
|
+
* Makes a call in place when nothing makes it wait: `write` writes its
|
|
109
|
+
* body into the bytes that leave next, and `read` reads its answer where
|
|
110
|
+
* it arrived, for `resolve`. It says false, having sent nothing, when the
|
|
111
|
+
* call must wait or may be cancelled: before the WELCOME, under a signal,
|
|
112
|
+
* with every stream in use, or past the connection's credit. Then `call`
|
|
113
|
+
* makes it.
|
|
114
|
+
*
|
|
115
|
+
* A call an event loop makes costs it a promise and nothing more this way.
|
|
116
|
+
* Through a stream it cost five, and a copy of its body three times.
|
|
117
|
+
*/
|
|
118
|
+
direct<T>(method: number, write: (w: Writer) => void, read: (r: Reader) => T, resolve: (value: T) => void, reject: (err: Error) => void): boolean;
|
|
99
119
|
/** A call: one REQUEST, and the RESPONSE that answers it. */
|
|
100
120
|
call(method: number, body: Uint8Array, signal?: AbortSignal): Promise<Uint8Array>;
|
|
101
121
|
enqueue(stream: Stream, bytes: Uint8Array, counted: number): void;
|
|
@@ -104,6 +124,13 @@ export declare class Session {
|
|
|
104
124
|
cancel(stream: Stream): void;
|
|
105
125
|
/** Takes bytes the transport read: any part of a frame, or several. */
|
|
106
126
|
receive(chunk: Uint8Array): void;
|
|
127
|
+
/**
|
|
128
|
+
* Takes the frames whole in the first `length` bytes and says how many
|
|
129
|
+
* bytes they were: the rest is a frame's first part, which whoever owns
|
|
130
|
+
* the bytes keeps for its end. Nothing of the bytes is kept here, so their
|
|
131
|
+
* owner may write them over once this returns.
|
|
132
|
+
*/
|
|
133
|
+
read(bytes: Uint8Array, length: number): number;
|
|
107
134
|
/** A frame broke the protocol: the connection ends, and whoever runs it closes it. */
|
|
108
135
|
fault(err: Error): void;
|
|
109
136
|
/**
|
|
@@ -118,3 +145,4 @@ export declare function watch(signal: AbortSignal | undefined, stream: Stream):
|
|
|
118
145
|
export declare function failureOf(body: Uint8Array): TinystoreError;
|
|
119
146
|
/** A WELCOME's proof is the HMAC-SHA256 of the challenge keyed with SERVE's secret. */
|
|
120
147
|
export declare function proves(secret: Uint8Array, challenge: Uint8Array, proof: Uint8Array | undefined): boolean;
|
|
148
|
+
export {};
|
package/dist/session.js
CHANGED
|
@@ -6,20 +6,23 @@
|
|
|
6
6
|
import { createHmac, timingSafeEqual } from 'node:crypto';
|
|
7
7
|
import { currentSignal } from './cancel.js';
|
|
8
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 {
|
|
9
|
+
import { checkHeader, credit, Flag, frame, granted, headerSize, Kind, kindName, parseHeader, putHeader, } from './wire/frame.js';
|
|
10
|
+
import { Reader, Writer } from './wire/msgpack.js';
|
|
11
|
+
import { Failure, GoAway, Hello, Welcome } from './wire/protocol.js';
|
|
11
12
|
export const protocol = 1;
|
|
12
13
|
/** What this client lets the server send on a stream before it grants more: a body at least. */
|
|
13
14
|
export const downloadWindow = 2 << 20;
|
|
14
15
|
/** The largest body a WELCOME may come in, before a body is agreed. */
|
|
15
16
|
const welcomeMost = 1 << 20;
|
|
17
|
+
/** A frame past this leaves by itself, so that what a turn's calls are written into stays small. */
|
|
18
|
+
const largeFrame = 1 << 15;
|
|
16
19
|
/**
|
|
17
20
|
* The connection was lost with a stream on it. Sent says whether its REQUEST
|
|
18
21
|
* had left: one that had not may go on another connection whatever it was,
|
|
19
22
|
* and one that had is a read to send again or a write whose outcome is
|
|
20
23
|
* unknown.
|
|
21
24
|
*/
|
|
22
|
-
export class
|
|
25
|
+
export class ConnectionLostError extends ClosedError {
|
|
23
26
|
sent;
|
|
24
27
|
constructor(message, sent) {
|
|
25
28
|
super(message);
|
|
@@ -151,6 +154,21 @@ export class Stream {
|
|
|
151
154
|
}
|
|
152
155
|
#unwatch;
|
|
153
156
|
}
|
|
157
|
+
/**
|
|
158
|
+
* A call that left the moment it was made, a REQUEST the RESPONSE answers:
|
|
159
|
+
* its answer is read where it arrives and given to whoever asked, with no
|
|
160
|
+
* stream's state between. Nothing cancels it.
|
|
161
|
+
*/
|
|
162
|
+
class Direct {
|
|
163
|
+
read;
|
|
164
|
+
resolve;
|
|
165
|
+
reject;
|
|
166
|
+
constructor(read, resolve, reject) {
|
|
167
|
+
this.read = read;
|
|
168
|
+
this.resolve = resolve;
|
|
169
|
+
this.reject = reject;
|
|
170
|
+
}
|
|
171
|
+
}
|
|
154
172
|
/**
|
|
155
173
|
* The protocol of one connection. It writes through send, which the
|
|
156
174
|
* transport takes whole, and reads what receive is given, frames split
|
|
@@ -168,9 +186,12 @@ export class Session {
|
|
|
168
186
|
#waitingToOpen = [];
|
|
169
187
|
#queue = [];
|
|
170
188
|
#credit = 0;
|
|
171
|
-
|
|
172
|
-
|
|
189
|
+
// what leaves in this turn's one write: every frame asked for is written
|
|
190
|
+
// here, a call's body straight from its fields
|
|
191
|
+
#out = new Writer(1 << 12);
|
|
173
192
|
#flushing = false;
|
|
193
|
+
#leave = () => this.#flush();
|
|
194
|
+
#reader = new Reader(new Uint8Array(0));
|
|
174
195
|
#rest;
|
|
175
196
|
#goingAway = false;
|
|
176
197
|
#ended;
|
|
@@ -250,13 +271,56 @@ export class Session {
|
|
|
250
271
|
/** Why no stream may open now: the connection ended or is going away. */
|
|
251
272
|
#usable() {
|
|
252
273
|
if (this.#ended !== undefined) {
|
|
253
|
-
return new
|
|
274
|
+
return new ConnectionLostError(`the connection ended: ${this.#ended.message}`, false);
|
|
254
275
|
}
|
|
255
276
|
if (this.#goingAway) {
|
|
256
277
|
return new UnavailableError('the server is closing this connection');
|
|
257
278
|
}
|
|
258
279
|
return undefined;
|
|
259
280
|
}
|
|
281
|
+
/**
|
|
282
|
+
* Makes a call in place when nothing makes it wait: `write` writes its
|
|
283
|
+
* body into the bytes that leave next, and `read` reads its answer where
|
|
284
|
+
* it arrived, for `resolve`. It says false, having sent nothing, when the
|
|
285
|
+
* call must wait or may be cancelled: before the WELCOME, under a signal,
|
|
286
|
+
* with every stream in use, or past the connection's credit. Then `call`
|
|
287
|
+
* makes it.
|
|
288
|
+
*
|
|
289
|
+
* A call an event loop makes costs it a promise and nothing more this way.
|
|
290
|
+
* Through a stream it cost five, and a copy of its body three times.
|
|
291
|
+
*/
|
|
292
|
+
direct(method, write, read, resolve, reject) {
|
|
293
|
+
const agreed = this.#agreed;
|
|
294
|
+
if (agreed === undefined ||
|
|
295
|
+
this.#ended !== undefined ||
|
|
296
|
+
this.#goingAway ||
|
|
297
|
+
this.#queue.length > 0 ||
|
|
298
|
+
this.#streams.size >= agreed.inFlight ||
|
|
299
|
+
currentSignal() !== undefined) {
|
|
300
|
+
return false;
|
|
301
|
+
}
|
|
302
|
+
const out = this.#out;
|
|
303
|
+
const start = out.reserve(headerSize);
|
|
304
|
+
let length;
|
|
305
|
+
try {
|
|
306
|
+
write(out);
|
|
307
|
+
length = out.length - start - headerSize;
|
|
308
|
+
}
|
|
309
|
+
catch (err) {
|
|
310
|
+
out.truncate(start);
|
|
311
|
+
throw err;
|
|
312
|
+
}
|
|
313
|
+
if (length > agreed.maxBody || length > this.#credit) {
|
|
314
|
+
out.truncate(start);
|
|
315
|
+
return false;
|
|
316
|
+
}
|
|
317
|
+
const id = this.#nextID();
|
|
318
|
+
putHeader(out.buffer, start, Kind.request, Flag.end, method, id, length);
|
|
319
|
+
this.#credit -= length;
|
|
320
|
+
this.#streams.set(id, new Direct(read, resolve, reject));
|
|
321
|
+
this.#soon();
|
|
322
|
+
return true;
|
|
323
|
+
}
|
|
260
324
|
/** A call: one REQUEST, and the RESPONSE that answers it. */
|
|
261
325
|
async call(method, body, signal) {
|
|
262
326
|
signal?.throwIfAborted();
|
|
@@ -311,11 +375,18 @@ export class Session {
|
|
|
311
375
|
if (this.#ended !== undefined) {
|
|
312
376
|
return;
|
|
313
377
|
}
|
|
314
|
-
|
|
315
|
-
|
|
378
|
+
if (bytes.length > largeFrame) {
|
|
379
|
+
this.#flush();
|
|
380
|
+
this.#send(bytes);
|
|
381
|
+
return;
|
|
382
|
+
}
|
|
383
|
+
this.#out.raw(bytes);
|
|
384
|
+
this.#soon();
|
|
385
|
+
}
|
|
386
|
+
#soon() {
|
|
316
387
|
if (!this.#flushing) {
|
|
317
388
|
this.#flushing = true;
|
|
318
|
-
queueMicrotask(
|
|
389
|
+
queueMicrotask(this.#leave);
|
|
319
390
|
}
|
|
320
391
|
}
|
|
321
392
|
// the frames asked for in one turn leave in one write
|
|
@@ -324,20 +395,8 @@ export class Session {
|
|
|
324
395
|
if (this.#out.length === 0 || this.#ended !== undefined) {
|
|
325
396
|
return;
|
|
326
397
|
}
|
|
327
|
-
|
|
328
|
-
|
|
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;
|
|
398
|
+
const bytes = this.#out.bytes();
|
|
399
|
+
this.#out.truncate(0);
|
|
341
400
|
this.#send(bytes);
|
|
342
401
|
}
|
|
343
402
|
cancel(stream) {
|
|
@@ -370,38 +429,52 @@ export class Session {
|
|
|
370
429
|
bytes.set(chunk, this.#rest.length);
|
|
371
430
|
this.#rest = undefined;
|
|
372
431
|
}
|
|
432
|
+
const at = this.read(bytes, bytes.length);
|
|
433
|
+
if (at < bytes.length && this.#ended === undefined) {
|
|
434
|
+
this.#rest = bytes.slice(at);
|
|
435
|
+
}
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* Takes the frames whole in the first `length` bytes and says how many
|
|
439
|
+
* bytes they were: the rest is a frame's first part, which whoever owns
|
|
440
|
+
* the bytes keeps for its end. Nothing of the bytes is kept here, so their
|
|
441
|
+
* owner may write them over once this returns.
|
|
442
|
+
*/
|
|
443
|
+
read(bytes, length) {
|
|
444
|
+
if (this.#ended !== undefined) {
|
|
445
|
+
return length;
|
|
446
|
+
}
|
|
373
447
|
let at = 0;
|
|
374
448
|
try {
|
|
375
|
-
while (
|
|
449
|
+
while (length - at >= headerSize) {
|
|
376
450
|
const h = parseHeader(bytes, at);
|
|
377
451
|
checkHeader(h, this.#agreed?.maxBody ?? welcomeMost);
|
|
378
|
-
const stop = at +
|
|
379
|
-
if (stop >
|
|
452
|
+
const stop = at + headerSize + h.length;
|
|
453
|
+
if (stop > length) {
|
|
380
454
|
break;
|
|
381
455
|
}
|
|
382
|
-
|
|
383
|
-
this.#take(h, bytes.slice(at + 12, stop));
|
|
456
|
+
this.#take(h, bytes, at + headerSize, stop);
|
|
384
457
|
at = stop;
|
|
385
458
|
}
|
|
386
459
|
}
|
|
387
460
|
catch (err) {
|
|
388
461
|
this.fault(err instanceof Error ? err : new ProtocolError(String(err)));
|
|
389
|
-
return;
|
|
390
|
-
}
|
|
391
|
-
if (at < bytes.length) {
|
|
392
|
-
this.#rest = bytes.slice(at);
|
|
462
|
+
return length;
|
|
393
463
|
}
|
|
464
|
+
return at;
|
|
394
465
|
}
|
|
395
|
-
|
|
466
|
+
// takes the frame whose body is the bytes from `from` to `to`
|
|
467
|
+
#take(h, bytes, from, to) {
|
|
468
|
+
if (this.#agreed !== undefined && (h.kind === Kind.response || h.kind === Kind.data)) {
|
|
469
|
+
this.#answer(h, bytes, from, to);
|
|
470
|
+
return;
|
|
471
|
+
}
|
|
472
|
+
const body = bytes.slice(from, to);
|
|
396
473
|
if (this.#agreed === undefined) {
|
|
397
474
|
this.#handshake(h.kind, body);
|
|
398
475
|
return;
|
|
399
476
|
}
|
|
400
477
|
switch (h.kind) {
|
|
401
|
-
case Kind.response:
|
|
402
|
-
case Kind.data:
|
|
403
|
-
this.#answer(h.kind, h.flags, h.stream, body);
|
|
404
|
-
return;
|
|
405
478
|
case Kind.credit:
|
|
406
479
|
this.#credited(h.stream, granted(body));
|
|
407
480
|
return;
|
|
@@ -446,16 +519,24 @@ export class Session {
|
|
|
446
519
|
streamCredit: welcome.streamCredit ?? 0,
|
|
447
520
|
engines: welcome.engines ?? [],
|
|
448
521
|
now: welcome.now ?? 0,
|
|
522
|
+
durability: welcome.durability,
|
|
449
523
|
};
|
|
450
524
|
this.#agreed = agreed;
|
|
451
525
|
this.#credit = agreed.connectionCredit;
|
|
452
526
|
this.#welcome.resolve(agreed);
|
|
453
527
|
}
|
|
454
|
-
#answer(
|
|
528
|
+
#answer(h, bytes, from, to) {
|
|
529
|
+
const { kind, flags, stream: id } = h;
|
|
455
530
|
const stream = this.#streams.get(id);
|
|
456
531
|
if (stream === undefined) {
|
|
457
532
|
throw new ProtocolError(`a ${kindName(kind)} on stream ${id}, which is not in use`);
|
|
458
533
|
}
|
|
534
|
+
if (stream instanceof Direct) {
|
|
535
|
+
this.#answerDirect(stream, h, bytes, from, to);
|
|
536
|
+
return;
|
|
537
|
+
}
|
|
538
|
+
// a body of its own, since events outlive the read's buffer
|
|
539
|
+
const body = bytes.slice(from, to);
|
|
459
540
|
const end = (flags & Flag.end) !== 0;
|
|
460
541
|
if (end) {
|
|
461
542
|
this.#release(stream);
|
|
@@ -469,13 +550,40 @@ export class Session {
|
|
|
469
550
|
stream.consumed(body.length);
|
|
470
551
|
}
|
|
471
552
|
}
|
|
553
|
+
// reads a call's answer where it arrived: what `read` returns holds none of these bytes
|
|
554
|
+
#answerDirect(call, h, bytes, from, to) {
|
|
555
|
+
if (h.kind !== Kind.response || (h.flags & Flag.end) === 0) {
|
|
556
|
+
throw new ProtocolError(`a ${kindName(h.kind)} without END answering a call on stream ${h.stream}`);
|
|
557
|
+
}
|
|
558
|
+
this.#streams.delete(h.stream);
|
|
559
|
+
this.#waitingToOpen.shift()?.resolve();
|
|
560
|
+
if ((h.flags & Flag.error) !== 0) {
|
|
561
|
+
call.reject(failureOf(bytes.slice(from, to)));
|
|
562
|
+
return;
|
|
563
|
+
}
|
|
564
|
+
const reader = this.#reader;
|
|
565
|
+
reader.reset(bytes, from, to);
|
|
566
|
+
let value;
|
|
567
|
+
try {
|
|
568
|
+
value = call.read(reader);
|
|
569
|
+
reader.end();
|
|
570
|
+
}
|
|
571
|
+
catch (err) {
|
|
572
|
+
call.reject(err instanceof Error ? err : new ProtocolError(String(err)));
|
|
573
|
+
return;
|
|
574
|
+
}
|
|
575
|
+
call.resolve(value);
|
|
576
|
+
}
|
|
472
577
|
#credited(id, n) {
|
|
473
578
|
if (id === 0) {
|
|
474
579
|
this.#credit += n;
|
|
475
580
|
this.#drain();
|
|
476
581
|
return;
|
|
477
582
|
}
|
|
478
|
-
this.#streams.get(id)
|
|
583
|
+
const stream = this.#streams.get(id);
|
|
584
|
+
if (stream instanceof Stream) {
|
|
585
|
+
stream.grant(n);
|
|
586
|
+
}
|
|
479
587
|
}
|
|
480
588
|
// after a GOAWAY no stream opens; a REQUEST still waiting for credit goes
|
|
481
589
|
// nowhere and may be sent on another connection
|
|
@@ -506,13 +614,17 @@ export class Session {
|
|
|
506
614
|
this.#ended = err;
|
|
507
615
|
this.#welcome.reject(err);
|
|
508
616
|
for (const stream of this.#streams.values()) {
|
|
509
|
-
|
|
617
|
+
if (stream instanceof Direct) {
|
|
618
|
+
stream.reject(new ConnectionLostError(`the connection ended: ${err.message}`, true));
|
|
619
|
+
continue;
|
|
620
|
+
}
|
|
621
|
+
stream.fail(new ConnectionLostError(`the connection ended: ${err.message}`, stream.sent));
|
|
510
622
|
stream.finish();
|
|
511
623
|
}
|
|
512
624
|
this.#streams.clear();
|
|
513
625
|
this.#queue = [];
|
|
514
626
|
for (const w of this.#waitingToOpen.splice(0)) {
|
|
515
|
-
w.reject(new
|
|
627
|
+
w.reject(new ConnectionLostError(`the connection ended: ${err.message}`, false));
|
|
516
628
|
}
|
|
517
629
|
for (const listener of this.#endListeners.splice(0)) {
|
|
518
630
|
listener(err);
|