@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/trace.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** A trace's 16 bytes and the span's 8, as bytes or hex. */
|
|
2
|
+
export interface Trace {
|
|
3
|
+
traceId: Uint8Array | string;
|
|
4
|
+
spanId?: Uint8Array | string;
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Runs fn in a trace: a logger's lines, and records appended without a trace
|
|
8
|
+
* of their own, inside it and in what it awaits, take its trace and span.
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* await withTrace({ traceId, spanId }, async () => {
|
|
12
|
+
* log.info('charged') // a record of that trace and span
|
|
13
|
+
* })
|
|
14
|
+
* ```
|
|
15
|
+
*/
|
|
16
|
+
export declare function withTrace<T>(trace: Trace, fn: () => T): T;
|
|
17
|
+
/** The trace the caller runs in, from withTrace. */
|
|
18
|
+
export declare function currentTrace(): Trace | undefined;
|
package/dist/trace.js
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// The trace a call runs in, as Go's records.WithTrace carries one in a
|
|
2
|
+
// context: a logger's lines and appended records of no trace of their own
|
|
3
|
+
// take it.
|
|
4
|
+
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
5
|
+
const carried = new AsyncLocalStorage();
|
|
6
|
+
/**
|
|
7
|
+
* Runs fn in a trace: a logger's lines, and records appended without a trace
|
|
8
|
+
* of their own, inside it and in what it awaits, take its trace and span.
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* await withTrace({ traceId, spanId }, async () => {
|
|
12
|
+
* log.info('charged') // a record of that trace and span
|
|
13
|
+
* })
|
|
14
|
+
* ```
|
|
15
|
+
*/
|
|
16
|
+
export function withTrace(trace, fn) {
|
|
17
|
+
return carried.run(trace, fn);
|
|
18
|
+
}
|
|
19
|
+
/** The trace the caller runs in, from withTrace. */
|
|
20
|
+
export function currentTrace() {
|
|
21
|
+
return carried.getStore();
|
|
22
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { Reader, Writer } from './msgpack.ts';
|
|
2
|
+
/**
|
|
3
|
+
* How a field's value is written and read. In is what a caller may give, Out
|
|
4
|
+
* what a read returns: a key given as a number reads back as its decimal text.
|
|
5
|
+
*/
|
|
6
|
+
export interface Codec<Out, In = Out> {
|
|
7
|
+
/** what the value is, which the tests that read vectors go by */
|
|
8
|
+
readonly kind: string;
|
|
9
|
+
/** a list's items, or what a nullable holds when it holds something */
|
|
10
|
+
readonly item?: Codec<unknown, never>;
|
|
11
|
+
write(w: Writer, value: In): void;
|
|
12
|
+
read(r: Reader): Out;
|
|
13
|
+
}
|
|
14
|
+
export declare const uint: Codec<number>;
|
|
15
|
+
/** A signed integer a number holds exactly: unix milliseconds, a count. */
|
|
16
|
+
export declare const int: Codec<number>;
|
|
17
|
+
/** A signed 64-bit integer, read as a bigint: a record's nanoseconds. */
|
|
18
|
+
export declare const int64: Codec<bigint, bigint | number>;
|
|
19
|
+
export declare const float: Codec<number>;
|
|
20
|
+
export declare const bool: Codec<boolean>;
|
|
21
|
+
export declare const str: Codec<string>;
|
|
22
|
+
/** Bytes, read as a copy that outlives the frame they came in. */
|
|
23
|
+
export declare const bin: Codec<Uint8Array>;
|
|
24
|
+
/** The text bytes spell, or undefined when they are not UTF-8. */
|
|
25
|
+
export declare function textOf(bytes: Uint8Array): string | undefined;
|
|
26
|
+
/**
|
|
27
|
+
* Text: a str, or a bin whose bytes are text that is not UTF-8, as another
|
|
28
|
+
* program's output may be. Bytes that are UTF-8 travel as the str they spell.
|
|
29
|
+
*/
|
|
30
|
+
export declare const text: Codec<string | Uint8Array>;
|
|
31
|
+
/** A kv key's text: a str, a bin, or an integer, which is its decimal spelling. */
|
|
32
|
+
export type Key = string | Uint8Array | number | bigint;
|
|
33
|
+
export declare const key: Codec<string | Uint8Array, Key>;
|
|
34
|
+
/** A kv value as its row keeps it: nothing, an integer or bytes. */
|
|
35
|
+
export type Raw = null | bigint | Uint8Array;
|
|
36
|
+
export declare const kvValue: Codec<Raw, Raw | number>;
|
|
37
|
+
/** A value SQLite returns: NULL, an integer, a float, text or bytes. */
|
|
38
|
+
export type SqlValue = null | number | bigint | string | Uint8Array;
|
|
39
|
+
/**
|
|
40
|
+
* A value an SQL statement takes: SQLite's five, a boolean, which it keeps as
|
|
41
|
+
* 1 or 0, and a Date, which sqldb keeps as its unix milliseconds.
|
|
42
|
+
*/
|
|
43
|
+
export type SqlArg = SqlValue | boolean | Date | undefined;
|
|
44
|
+
export declare const sqlValue: Codec<SqlValue | boolean, SqlArg>;
|
|
45
|
+
/** Names mapped to text, in the byte order of their UTF-8, which is their code points' order. */
|
|
46
|
+
export declare function names<V, In = V>(value: Codec<V, In>): Codec<Record<string, V>, Record<string, In>>;
|
|
47
|
+
/** Orders strings as their UTF-8 bytes are ordered, which UTF-16's code units do not. */
|
|
48
|
+
export declare function byCodePoint(a: string, b: string): number;
|
|
49
|
+
/** A column of int64s as a bin, eight bytes little-endian each. */
|
|
50
|
+
export declare const ints: Codec<BigInt64Array, BigInt64Array | readonly (number | bigint)[]>;
|
|
51
|
+
/**
|
|
52
|
+
* A column of float64s as a bin, eight bytes of bits little-endian each: the
|
|
53
|
+
* bytes are copied rather than the numbers, so a NaN's payload survives.
|
|
54
|
+
*/
|
|
55
|
+
export declare const floats: Codec<Float64Array, Float64Array | readonly number[]>;
|
|
56
|
+
export declare function list<Out, In>(item: Codec<Out, In>): Codec<Out[], readonly In[]>;
|
|
57
|
+
/** A value that may be nil in its place, as a settlement's error. */
|
|
58
|
+
export declare function nullable<Out, In>(value: Codec<Out, In>): Codec<Out | null, In | null>;
|
|
59
|
+
type Fields = Record<string, readonly [key: number, codec: Codec<unknown, never>]>;
|
|
60
|
+
type OutOf<C> = C extends Codec<infer O, never> ? O : never;
|
|
61
|
+
type InOf<C> = C extends Codec<unknown, infer I> ? I : never;
|
|
62
|
+
/** What a message reads: every field it holds, a field it lacks undefined. */
|
|
63
|
+
export type Read<F extends Fields> = {
|
|
64
|
+
[K in keyof F]?: OutOf<F[K][1]>;
|
|
65
|
+
};
|
|
66
|
+
/** What a message is written from: a field undefined is left out. */
|
|
67
|
+
export type Written<F extends Fields> = {
|
|
68
|
+
[K in keyof F]?: InOf<F[K][1]> | undefined;
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* A message: a map of the fields its declaration names, keys ascending. A
|
|
72
|
+
* field is written when its value is not undefined, so an absent field and a
|
|
73
|
+
* zero one stay what the caller said; a key the declaration lacks is skipped
|
|
74
|
+
* as it reads, well formed and within bounds.
|
|
75
|
+
*/
|
|
76
|
+
export declare class Message<F extends Fields> implements Codec<Read<F>, Written<F>> {
|
|
77
|
+
#private;
|
|
78
|
+
readonly kind = "message";
|
|
79
|
+
readonly name: string;
|
|
80
|
+
readonly fields: F;
|
|
81
|
+
constructor(name: string, fields: F);
|
|
82
|
+
write(w: Writer, value: Written<F>): void;
|
|
83
|
+
/** The message's bytes. */
|
|
84
|
+
encode(value: Written<F>): Uint8Array;
|
|
85
|
+
/** Reads a body that is this message and nothing after it. */
|
|
86
|
+
decode(body: Uint8Array): Read<F>;
|
|
87
|
+
read(r: Reader): Read<F>;
|
|
88
|
+
}
|
|
89
|
+
export declare function message<const F extends Fields>(name: string, fields: F): Message<F>;
|
|
90
|
+
export {};
|
|
@@ -0,0 +1,383 @@
|
|
|
1
|
+
// A message is a map from small integer keys to values; each field's codec
|
|
2
|
+
// says how its value is written and read. A message's fields are declared by
|
|
3
|
+
// the names docs/wire.md gives them, in camelCase, so that the tests read
|
|
4
|
+
// every vector of messages.json through them without a table.
|
|
5
|
+
import { InvalidError } from '../errors.js';
|
|
6
|
+
import { Reader, Writer } from './msgpack.js';
|
|
7
|
+
export const uint = {
|
|
8
|
+
kind: 'uint',
|
|
9
|
+
write: (w, v) => w.uint(v),
|
|
10
|
+
read: r => r.uint(),
|
|
11
|
+
};
|
|
12
|
+
/** A signed integer a number holds exactly: unix milliseconds, a count. */
|
|
13
|
+
export const int = {
|
|
14
|
+
kind: 'int',
|
|
15
|
+
write: (w, v) => w.int(v),
|
|
16
|
+
read: r => r.int(),
|
|
17
|
+
};
|
|
18
|
+
/** A signed 64-bit integer, read as a bigint: a record's nanoseconds. */
|
|
19
|
+
export const int64 = {
|
|
20
|
+
kind: 'int',
|
|
21
|
+
write: (w, v) => w.int(v),
|
|
22
|
+
read: r => r.int64(),
|
|
23
|
+
};
|
|
24
|
+
export const float = {
|
|
25
|
+
kind: 'float',
|
|
26
|
+
write: (w, v) => w.float(v),
|
|
27
|
+
read: r => r.float(),
|
|
28
|
+
};
|
|
29
|
+
export const bool = {
|
|
30
|
+
kind: 'bool',
|
|
31
|
+
write: (w, v) => w.bool(v),
|
|
32
|
+
read: r => r.bool(),
|
|
33
|
+
};
|
|
34
|
+
export const str = {
|
|
35
|
+
kind: 'str',
|
|
36
|
+
write: (w, v) => w.str(v),
|
|
37
|
+
read: r => r.str(),
|
|
38
|
+
};
|
|
39
|
+
/** Bytes, read as a copy that outlives the frame they came in. */
|
|
40
|
+
export const bin = {
|
|
41
|
+
kind: 'bin',
|
|
42
|
+
write: (w, v) => w.bin(v),
|
|
43
|
+
read: r => r.bin().slice(),
|
|
44
|
+
};
|
|
45
|
+
const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
|
|
46
|
+
/** The text bytes spell, or undefined when they are not UTF-8. */
|
|
47
|
+
export function textOf(bytes) {
|
|
48
|
+
try {
|
|
49
|
+
return utf8.decode(bytes);
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Text: a str, or a bin whose bytes are text that is not UTF-8, as another
|
|
57
|
+
* program's output may be. Bytes that are UTF-8 travel as the str they spell.
|
|
58
|
+
*/
|
|
59
|
+
export const text = {
|
|
60
|
+
kind: 'text',
|
|
61
|
+
write: (w, v) => writeText(w, v),
|
|
62
|
+
read: r => (r.type() === 'bin' ? r.bin().slice() : r.str()),
|
|
63
|
+
};
|
|
64
|
+
function writeText(w, v) {
|
|
65
|
+
if (typeof v === 'string') {
|
|
66
|
+
w.str(v);
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
const spelled = textOf(v);
|
|
70
|
+
if (spelled === undefined) {
|
|
71
|
+
w.bin(v);
|
|
72
|
+
return;
|
|
73
|
+
}
|
|
74
|
+
w.str(spelled);
|
|
75
|
+
}
|
|
76
|
+
export const key = {
|
|
77
|
+
kind: 'key',
|
|
78
|
+
write: (w, v) => {
|
|
79
|
+
if (typeof v === 'number' || typeof v === 'bigint') {
|
|
80
|
+
if (typeof v === 'number' && !Number.isSafeInteger(v)) {
|
|
81
|
+
throw new InvalidError(`the key ${v} is not an integer; a key is text or an integer`);
|
|
82
|
+
}
|
|
83
|
+
w.str(String(v));
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
writeText(w, v);
|
|
87
|
+
},
|
|
88
|
+
read: r => {
|
|
89
|
+
switch (r.type()) {
|
|
90
|
+
case 'bin':
|
|
91
|
+
return r.bin().slice();
|
|
92
|
+
case 'int':
|
|
93
|
+
return String(r.int64());
|
|
94
|
+
}
|
|
95
|
+
return r.str();
|
|
96
|
+
},
|
|
97
|
+
};
|
|
98
|
+
export const kvValue = {
|
|
99
|
+
kind: 'kv value',
|
|
100
|
+
write: (w, v) => {
|
|
101
|
+
if (v === null) {
|
|
102
|
+
w.nil();
|
|
103
|
+
}
|
|
104
|
+
else if (v instanceof Uint8Array) {
|
|
105
|
+
w.bin(v);
|
|
106
|
+
}
|
|
107
|
+
else {
|
|
108
|
+
w.int(v);
|
|
109
|
+
}
|
|
110
|
+
},
|
|
111
|
+
read: r => {
|
|
112
|
+
if (r.nil()) {
|
|
113
|
+
return null;
|
|
114
|
+
}
|
|
115
|
+
return r.type() === 'bin' ? r.bin().slice() : r.int64();
|
|
116
|
+
},
|
|
117
|
+
};
|
|
118
|
+
export const sqlValue = {
|
|
119
|
+
kind: 'sql value',
|
|
120
|
+
write: (w, v) => writeSQL(w, v),
|
|
121
|
+
read: r => {
|
|
122
|
+
switch (r.type()) {
|
|
123
|
+
case 'nil':
|
|
124
|
+
r.nil();
|
|
125
|
+
return null;
|
|
126
|
+
case 'bool':
|
|
127
|
+
return r.bool();
|
|
128
|
+
case 'int': {
|
|
129
|
+
const n = r.int64();
|
|
130
|
+
return n >= Number.MIN_SAFE_INTEGER && n <= Number.MAX_SAFE_INTEGER ? Number(n) : n;
|
|
131
|
+
}
|
|
132
|
+
case 'float':
|
|
133
|
+
return r.float();
|
|
134
|
+
case 'bin':
|
|
135
|
+
return r.bin().slice();
|
|
136
|
+
}
|
|
137
|
+
return r.str();
|
|
138
|
+
},
|
|
139
|
+
};
|
|
140
|
+
function writeSQL(w, v) {
|
|
141
|
+
if (v === null || v === undefined) {
|
|
142
|
+
w.nil();
|
|
143
|
+
}
|
|
144
|
+
else if (typeof v === 'boolean') {
|
|
145
|
+
w.bool(v);
|
|
146
|
+
}
|
|
147
|
+
else if (typeof v === 'bigint') {
|
|
148
|
+
w.int(v);
|
|
149
|
+
}
|
|
150
|
+
else if (typeof v === 'number') {
|
|
151
|
+
if (Number.isNaN(v)) {
|
|
152
|
+
throw new InvalidError('NaN as an SQL argument, which SQLite would keep as NULL');
|
|
153
|
+
}
|
|
154
|
+
if (Number.isInteger(v) && !Object.is(v, -0)) {
|
|
155
|
+
w.int(v);
|
|
156
|
+
}
|
|
157
|
+
else {
|
|
158
|
+
w.float(v);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
else if (typeof v === 'string') {
|
|
162
|
+
w.str(v);
|
|
163
|
+
}
|
|
164
|
+
else if (v instanceof Date) {
|
|
165
|
+
const ms = v.getTime();
|
|
166
|
+
if (Number.isNaN(ms)) {
|
|
167
|
+
throw new InvalidError('an invalid Date as an SQL argument');
|
|
168
|
+
}
|
|
169
|
+
w.int(ms);
|
|
170
|
+
}
|
|
171
|
+
else {
|
|
172
|
+
w.bin(v);
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
/** Names mapped to text, in the byte order of their UTF-8, which is their code points' order. */
|
|
176
|
+
export function names(value) {
|
|
177
|
+
return {
|
|
178
|
+
kind: value.kind === 'sql value' ? 'sql names' : 'names',
|
|
179
|
+
write: (w, v) => {
|
|
180
|
+
const sorted = Object.keys(v).sort(byCodePoint);
|
|
181
|
+
w.map(sorted.length);
|
|
182
|
+
for (const name of sorted) {
|
|
183
|
+
w.str(name);
|
|
184
|
+
value.write(w, v[name]);
|
|
185
|
+
}
|
|
186
|
+
},
|
|
187
|
+
read: r => {
|
|
188
|
+
const named = {};
|
|
189
|
+
r.names(name => {
|
|
190
|
+
named[name] = value.read(r);
|
|
191
|
+
});
|
|
192
|
+
return named;
|
|
193
|
+
},
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
/** Orders strings as their UTF-8 bytes are ordered, which UTF-16's code units do not. */
|
|
197
|
+
export function byCodePoint(a, b) {
|
|
198
|
+
const x = a[Symbol.iterator]();
|
|
199
|
+
const y = b[Symbol.iterator]();
|
|
200
|
+
for (;;) {
|
|
201
|
+
const p = x.next();
|
|
202
|
+
const q = y.next();
|
|
203
|
+
if (p.done || q.done) {
|
|
204
|
+
return (p.done ? 0 : 1) - (q.done ? 0 : 1);
|
|
205
|
+
}
|
|
206
|
+
const d = p.value.codePointAt(0) - q.value.codePointAt(0);
|
|
207
|
+
if (d !== 0) {
|
|
208
|
+
return d;
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
// a column's values are little-endian, as typed arrays hold them on every
|
|
213
|
+
// platform this SDK runs on; one that holds them otherwise copies value by value
|
|
214
|
+
const littleEndian = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
|
|
215
|
+
/** A column of int64s as a bin, eight bytes little-endian each. */
|
|
216
|
+
export const ints = {
|
|
217
|
+
kind: 'ints',
|
|
218
|
+
write: (w, v) => {
|
|
219
|
+
const column = v instanceof BigInt64Array ? v : BigInt64Array.from(v, n => BigInt(n));
|
|
220
|
+
w.bin(bytesOf(column));
|
|
221
|
+
},
|
|
222
|
+
read: r => {
|
|
223
|
+
const bytes = column(r);
|
|
224
|
+
const values = new BigInt64Array(bytes.length / 8);
|
|
225
|
+
if (littleEndian) {
|
|
226
|
+
new Uint8Array(values.buffer).set(bytes);
|
|
227
|
+
}
|
|
228
|
+
else {
|
|
229
|
+
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
|
|
230
|
+
values.forEach((_, i) => {
|
|
231
|
+
values[i] = view.getBigInt64(8 * i, true);
|
|
232
|
+
});
|
|
233
|
+
}
|
|
234
|
+
return values;
|
|
235
|
+
},
|
|
236
|
+
};
|
|
237
|
+
/**
|
|
238
|
+
* A column of float64s as a bin, eight bytes of bits little-endian each: the
|
|
239
|
+
* bytes are copied rather than the numbers, so a NaN's payload survives.
|
|
240
|
+
*/
|
|
241
|
+
export const floats = {
|
|
242
|
+
kind: 'floats',
|
|
243
|
+
write: (w, v) => {
|
|
244
|
+
w.bin(bytesOf(v instanceof Float64Array ? v : Float64Array.from(v)));
|
|
245
|
+
},
|
|
246
|
+
read: r => {
|
|
247
|
+
const bytes = column(r);
|
|
248
|
+
const values = new Float64Array(bytes.length / 8);
|
|
249
|
+
if (littleEndian) {
|
|
250
|
+
new Uint8Array(values.buffer).set(bytes);
|
|
251
|
+
}
|
|
252
|
+
else {
|
|
253
|
+
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
|
|
254
|
+
values.forEach((_, i) => {
|
|
255
|
+
values[i] = view.getFloat64(8 * i, true);
|
|
256
|
+
});
|
|
257
|
+
}
|
|
258
|
+
return values;
|
|
259
|
+
},
|
|
260
|
+
};
|
|
261
|
+
function bytesOf(column) {
|
|
262
|
+
if (littleEndian) {
|
|
263
|
+
return new Uint8Array(column.buffer, column.byteOffset, column.byteLength);
|
|
264
|
+
}
|
|
265
|
+
const bytes = new Uint8Array(column.length * 8);
|
|
266
|
+
const view = new DataView(bytes.buffer);
|
|
267
|
+
column.forEach((n, i) => {
|
|
268
|
+
if (typeof n === 'bigint') {
|
|
269
|
+
view.setBigInt64(8 * i, n, true);
|
|
270
|
+
}
|
|
271
|
+
else {
|
|
272
|
+
view.setFloat64(8 * i, n, true);
|
|
273
|
+
}
|
|
274
|
+
});
|
|
275
|
+
return bytes;
|
|
276
|
+
}
|
|
277
|
+
function column(r) {
|
|
278
|
+
const bytes = r.bin();
|
|
279
|
+
if (bytes.length % 8 !== 0) {
|
|
280
|
+
throw new InvalidError(`a column of ${bytes.length} bytes, which holds no whole number of values`);
|
|
281
|
+
}
|
|
282
|
+
return bytes;
|
|
283
|
+
}
|
|
284
|
+
export function list(item) {
|
|
285
|
+
return {
|
|
286
|
+
kind: `[]${item.kind}`,
|
|
287
|
+
item,
|
|
288
|
+
write: (w, v) => {
|
|
289
|
+
w.array(v.length);
|
|
290
|
+
for (const each of v) {
|
|
291
|
+
item.write(w, each);
|
|
292
|
+
}
|
|
293
|
+
},
|
|
294
|
+
read: r => {
|
|
295
|
+
const items = [];
|
|
296
|
+
r.items(() => {
|
|
297
|
+
items.push(item.read(r));
|
|
298
|
+
});
|
|
299
|
+
return items;
|
|
300
|
+
},
|
|
301
|
+
};
|
|
302
|
+
}
|
|
303
|
+
/** A value that may be nil in its place, as a settlement's error. */
|
|
304
|
+
export function nullable(value) {
|
|
305
|
+
return {
|
|
306
|
+
kind: `${value.kind}?`,
|
|
307
|
+
item: value,
|
|
308
|
+
write: (w, v) => (v === null ? w.nil() : value.write(w, v)),
|
|
309
|
+
read: r => (r.nil() ? null : value.read(r)),
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
/**
|
|
313
|
+
* A message: a map of the fields its declaration names, keys ascending. A
|
|
314
|
+
* field is written when its value is not undefined, so an absent field and a
|
|
315
|
+
* zero one stay what the caller said; a key the declaration lacks is skipped
|
|
316
|
+
* as it reads, well formed and within bounds.
|
|
317
|
+
*/
|
|
318
|
+
export class Message {
|
|
319
|
+
kind = 'message';
|
|
320
|
+
name;
|
|
321
|
+
fields;
|
|
322
|
+
#order;
|
|
323
|
+
#byKey = [];
|
|
324
|
+
constructor(name, fields) {
|
|
325
|
+
this.name = name;
|
|
326
|
+
this.fields = fields;
|
|
327
|
+
this.#order = Object.entries(fields)
|
|
328
|
+
.map(([field, [key, codec]]) => ({
|
|
329
|
+
name: field,
|
|
330
|
+
key,
|
|
331
|
+
codec: codec,
|
|
332
|
+
}))
|
|
333
|
+
.sort((a, b) => a.key - b.key);
|
|
334
|
+
for (const f of this.#order) {
|
|
335
|
+
this.#byKey[f.key] = f;
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
write(w, value) {
|
|
339
|
+
const held = value;
|
|
340
|
+
let n = 0;
|
|
341
|
+
for (const f of this.#order) {
|
|
342
|
+
if (held[f.name] !== undefined) {
|
|
343
|
+
n++;
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
w.map(n);
|
|
347
|
+
for (const f of this.#order) {
|
|
348
|
+
const v = held[f.name];
|
|
349
|
+
if (v !== undefined) {
|
|
350
|
+
w.uint(f.key);
|
|
351
|
+
f.codec.write(w, v);
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
/** The message's bytes. */
|
|
356
|
+
encode(value) {
|
|
357
|
+
const w = new Writer();
|
|
358
|
+
this.write(w, value);
|
|
359
|
+
return w.bytes();
|
|
360
|
+
}
|
|
361
|
+
/** Reads a body that is this message and nothing after it. */
|
|
362
|
+
decode(body) {
|
|
363
|
+
const r = new Reader(body);
|
|
364
|
+
const value = this.read(r);
|
|
365
|
+
r.end();
|
|
366
|
+
return value;
|
|
367
|
+
}
|
|
368
|
+
read(r) {
|
|
369
|
+
const read = {};
|
|
370
|
+
r.fields(key => {
|
|
371
|
+
const f = this.#byKey[key];
|
|
372
|
+
if (f === undefined) {
|
|
373
|
+
return false;
|
|
374
|
+
}
|
|
375
|
+
read[f.name] = f.codec.read(r);
|
|
376
|
+
return true;
|
|
377
|
+
});
|
|
378
|
+
return read;
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
export function message(name, fields) {
|
|
382
|
+
return new Message(name, fields);
|
|
383
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
export declare const headerSize = 12;
|
|
2
|
+
export declare const Kind: {
|
|
3
|
+
readonly hello: 1;
|
|
4
|
+
readonly welcome: 2;
|
|
5
|
+
readonly request: 3;
|
|
6
|
+
readonly response: 4;
|
|
7
|
+
readonly data: 5;
|
|
8
|
+
readonly cancel: 6;
|
|
9
|
+
readonly credit: 7;
|
|
10
|
+
readonly ping: 8;
|
|
11
|
+
readonly pong: 9;
|
|
12
|
+
readonly goaway: 10;
|
|
13
|
+
};
|
|
14
|
+
export type Kind = (typeof Kind)[keyof typeof Kind];
|
|
15
|
+
/** END marks the sender's last frame on its stream; ERROR, only beside END, an error's body. */
|
|
16
|
+
export declare const Flag: {
|
|
17
|
+
readonly end: 1;
|
|
18
|
+
readonly error: 2;
|
|
19
|
+
};
|
|
20
|
+
export interface Header {
|
|
21
|
+
length: number;
|
|
22
|
+
kind: number;
|
|
23
|
+
flags: number;
|
|
24
|
+
method: number;
|
|
25
|
+
stream: number;
|
|
26
|
+
}
|
|
27
|
+
export declare function kindName(kind: number): string;
|
|
28
|
+
/** Reads a header from its twelve bytes without checking it. */
|
|
29
|
+
export declare function parseHeader(bytes: Uint8Array, at?: number): Header;
|
|
30
|
+
/**
|
|
31
|
+
* Refuses a header that breaks the protocol: an unknown kind, a flag its kind
|
|
32
|
+
* does not define, ERROR without END, a method outside a REQUEST or none in
|
|
33
|
+
* one, a stream where the kind names none or none where it names one, and a
|
|
34
|
+
* body of a length the kind cannot have or past the agreed maximum.
|
|
35
|
+
*/
|
|
36
|
+
export declare function checkHeader(h: Header, maxBody: number): void;
|
|
37
|
+
/** Writes a frame: its header, the body's length its own, then the body. */
|
|
38
|
+
export declare function frame(kind: number, flags: number, method: number, stream: number, body: Uint8Array): Uint8Array;
|
|
39
|
+
/** A CREDIT granting n bytes on a stream. */
|
|
40
|
+
export declare function credit(stream: number, n: number): Uint8Array;
|
|
41
|
+
export declare function granted(body: Uint8Array): number;
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
// A frame is a twelve-byte header, little-endian, and a body:
|
|
2
|
+
//
|
|
3
|
+
// 0 4 5 6 8 12
|
|
4
|
+
// │ body length │ kind │ flags │ method │ stream │ body …
|
|
5
|
+
// u32 u8 u8 u16 u32
|
|
6
|
+
import { ProtocolError } from '../errors.js';
|
|
7
|
+
export const headerSize = 12;
|
|
8
|
+
export const Kind = {
|
|
9
|
+
hello: 1,
|
|
10
|
+
welcome: 2,
|
|
11
|
+
request: 3,
|
|
12
|
+
response: 4,
|
|
13
|
+
data: 5,
|
|
14
|
+
cancel: 6,
|
|
15
|
+
credit: 7,
|
|
16
|
+
ping: 8,
|
|
17
|
+
pong: 9,
|
|
18
|
+
goaway: 10,
|
|
19
|
+
};
|
|
20
|
+
/** END marks the sender's last frame on its stream; ERROR, only beside END, an error's body. */
|
|
21
|
+
export const Flag = { end: 1, error: 2 };
|
|
22
|
+
const rules = {
|
|
23
|
+
[Kind.hello]: { name: 'HELLO', stream: 'none', flags: 0 },
|
|
24
|
+
[Kind.welcome]: { name: 'WELCOME', stream: 'none', flags: 0 },
|
|
25
|
+
[Kind.request]: { name: 'REQUEST', stream: 'own', flags: Flag.end },
|
|
26
|
+
[Kind.response]: { name: 'RESPONSE', stream: 'own', flags: Flag.end | Flag.error },
|
|
27
|
+
[Kind.data]: { name: 'DATA', stream: 'own', flags: Flag.end | Flag.error },
|
|
28
|
+
[Kind.cancel]: { name: 'CANCEL', stream: 'own', flags: 0, length: 0 },
|
|
29
|
+
[Kind.credit]: { name: 'CREDIT', stream: 'either', flags: 0, length: 4 },
|
|
30
|
+
[Kind.ping]: { name: 'PING', stream: 'none', flags: 0, length: 8 },
|
|
31
|
+
[Kind.pong]: { name: 'PONG', stream: 'none', flags: 0, length: 8 },
|
|
32
|
+
[Kind.goaway]: { name: 'GOAWAY', stream: 'none', flags: 0 },
|
|
33
|
+
};
|
|
34
|
+
export function kindName(kind) {
|
|
35
|
+
return rules[kind]?.name ?? `kind ${kind}`;
|
|
36
|
+
}
|
|
37
|
+
/** Reads a header from its twelve bytes without checking it. */
|
|
38
|
+
export function parseHeader(bytes, at = 0) {
|
|
39
|
+
const view = new DataView(bytes.buffer, bytes.byteOffset + at, headerSize);
|
|
40
|
+
return {
|
|
41
|
+
length: view.getUint32(0, true),
|
|
42
|
+
kind: view.getUint8(4),
|
|
43
|
+
flags: view.getUint8(5),
|
|
44
|
+
method: view.getUint16(6, true),
|
|
45
|
+
stream: view.getUint32(8, true),
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Refuses a header that breaks the protocol: an unknown kind, a flag its kind
|
|
50
|
+
* does not define, ERROR without END, a method outside a REQUEST or none in
|
|
51
|
+
* one, a stream where the kind names none or none where it names one, and a
|
|
52
|
+
* body of a length the kind cannot have or past the agreed maximum.
|
|
53
|
+
*/
|
|
54
|
+
export function checkHeader(h, maxBody) {
|
|
55
|
+
const rule = rules[h.kind];
|
|
56
|
+
if (rule === undefined) {
|
|
57
|
+
throw new ProtocolError(`a frame of kind ${h.kind}`);
|
|
58
|
+
}
|
|
59
|
+
const name = rule.name;
|
|
60
|
+
if ((h.flags & ~rule.flags) !== 0) {
|
|
61
|
+
throw new ProtocolError(`flags 0x${h.flags.toString(16)} on a ${name}`);
|
|
62
|
+
}
|
|
63
|
+
if ((h.flags & Flag.error) !== 0 && (h.flags & Flag.end) === 0) {
|
|
64
|
+
throw new ProtocolError(`ERROR without END on stream ${h.stream}`);
|
|
65
|
+
}
|
|
66
|
+
if (h.kind === Kind.request && h.method === 0) {
|
|
67
|
+
throw new ProtocolError(`a REQUEST without a method on stream ${h.stream}`);
|
|
68
|
+
}
|
|
69
|
+
if (h.kind !== Kind.request && h.method !== 0) {
|
|
70
|
+
throw new ProtocolError(`method 0x${h.method.toString(16)} on a ${name}`);
|
|
71
|
+
}
|
|
72
|
+
if ((rule.stream === 'none' && h.stream !== 0) || (rule.stream === 'own' && h.stream === 0)) {
|
|
73
|
+
throw new ProtocolError(`stream ${h.stream} on a ${name}`);
|
|
74
|
+
}
|
|
75
|
+
if (rule.length !== undefined && h.length !== rule.length) {
|
|
76
|
+
throw new ProtocolError(`a ${name} of ${h.length} bytes, not ${rule.length}`);
|
|
77
|
+
}
|
|
78
|
+
if (h.length > maxBody) {
|
|
79
|
+
throw new ProtocolError(`a ${name} of ${h.length} bytes, ${maxBody} agreed`);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/** Writes a frame: its header, the body's length its own, then the body. */
|
|
83
|
+
export function frame(kind, flags, method, stream, body) {
|
|
84
|
+
const bytes = new Uint8Array(headerSize + body.length);
|
|
85
|
+
const view = new DataView(bytes.buffer);
|
|
86
|
+
view.setUint32(0, body.length, true);
|
|
87
|
+
view.setUint8(4, kind);
|
|
88
|
+
view.setUint8(5, flags);
|
|
89
|
+
view.setUint16(6, method, true);
|
|
90
|
+
view.setUint32(8, stream, true);
|
|
91
|
+
bytes.set(body, headerSize);
|
|
92
|
+
return bytes;
|
|
93
|
+
}
|
|
94
|
+
/** A CREDIT granting n bytes on a stream. */
|
|
95
|
+
export function credit(stream, n) {
|
|
96
|
+
const body = new Uint8Array(4);
|
|
97
|
+
new DataView(body.buffer).setUint32(0, n, true);
|
|
98
|
+
return frame(Kind.credit, 0, 0, stream, body);
|
|
99
|
+
}
|
|
100
|
+
export function granted(body) {
|
|
101
|
+
return new DataView(body.buffer, body.byteOffset, 4).getUint32(0, true);
|
|
102
|
+
}
|