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