@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.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. 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 { Welcome } from './wire/messages.ts';
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 = Required<Omit<Read<typeof Welcome.fields>, 'proof'>>;
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 LostError extends ClosedError {
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 { Failure, GoAway, Hello, Welcome } from './wire/messages.js';
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 LostError extends ClosedError {
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
- #out = [];
172
- #outBytes = 0;
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 LostError(`the connection ended: ${this.#ended.message}`, false);
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
- this.#out.push(bytes);
315
- this.#outBytes += bytes.length;
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(() => this.#flush());
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
- 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;
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 (bytes.length - at >= 12) {
449
+ while (length - at >= headerSize) {
376
450
  const h = parseHeader(bytes, at);
377
451
  checkHeader(h, this.#agreed?.maxBody ?? welcomeMost);
378
- const stop = at + 12 + h.length;
379
- if (stop > bytes.length) {
452
+ const stop = at + headerSize + h.length;
453
+ if (stop > length) {
380
454
  break;
381
455
  }
382
- // a body of its own, since events outlive the read's buffer
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
- #take(h, body) {
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(kind, flags, id, body) {
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)?.grant(n);
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
- stream.fail(new LostError(`the connection ended: ${err.message}`, stream.sent));
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 LostError(`the connection ended: ${err.message}`, false));
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);