hydo-assert 0.0.0-stage → 0.2.0
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 +234 -2
- package/history.d.mts +4 -0
- package/history.d.ts +56 -0
- package/history.js +268 -0
- package/history.mjs +18 -0
- package/index.d.mts +4 -0
- package/index.d.ts +77 -0
- package/index.js +585 -0
- package/index.mjs +20 -0
- package/package.json +63 -4
package/history.js
ADDED
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
// hydo-assert/history: hydo's operation-history recorder for Node.js guest programs.
|
|
3
|
+
//
|
|
4
|
+
// A workload client records every operation it performs -- the invocation before the request,
|
|
5
|
+
// the completion after the reply -- and the host checks the history after the run
|
|
6
|
+
// (linearizability of a register / CAS object per key, Elle-style list-append checks). The
|
|
7
|
+
// lines are byte for byte those of the Go recorder (hydo/stack/hydohist); the wire format and
|
|
8
|
+
// the checkers are in hydo/HISTORIES.md.
|
|
9
|
+
//
|
|
10
|
+
// const { History, enc, ver, valueOrNil } = require('hydo-assert/history');
|
|
11
|
+
// const kv = new History('kv');
|
|
12
|
+
// let op = kv.invoke(3, 'write', 'k1', enc(v)); // process 3, before the request
|
|
13
|
+
// try { const rev = await put('k1', v); op.ok('k1', ver(v, rev)); }
|
|
14
|
+
// catch (e) { if (rejected(e)) op.fail(); else op.info(); } // info = unknown outcome
|
|
15
|
+
// op = kv.invoke(3, 'read', 'k1');
|
|
16
|
+
// op.ok('k1', valueOrNil(await get('k1'))); // null / undefined = absent
|
|
17
|
+
//
|
|
18
|
+
// HYDO-HIST <history> <process> <invoke|ok|fail|info> <time-ns> <f> <arg>...
|
|
19
|
+
//
|
|
20
|
+
// One record = one line = one fs.writeSync() on the guest console (/dev/console;
|
|
21
|
+
// HYDO_HIST_OUT overrides it: a path, "stderr" or "off"). The host orders operations by the
|
|
22
|
+
// position of their records, so record the invocation before sending and the completion after
|
|
23
|
+
// receiving. A process has at most one operation in flight: give each concurrent client its
|
|
24
|
+
// own process number. The time field is CLOCK_MONOTONIC in ns (process.hrtime.bigint(),
|
|
25
|
+
// deterministic under hydo); the checkers do not order by it.
|
|
26
|
+
//
|
|
27
|
+
// Strings are written as UTF-8. A JavaScript string cannot hold invalid UTF-8; a lone
|
|
28
|
+
// surrogate in it is written (and encoded by enc) as U+FFFD, as Buffer.from and TextEncoder
|
|
29
|
+
// convert it.
|
|
30
|
+
//
|
|
31
|
+
// This module is separate from the assertion SDK (index.js) and has its own sink: requiring
|
|
32
|
+
// it changes nothing that the assertion SDK writes. history.mjs re-exports it for ESM, so a
|
|
33
|
+
// program that loads it both ways shares one sink.
|
|
34
|
+
|
|
35
|
+
const fs = require('fs');
|
|
36
|
+
|
|
37
|
+
/** The value of an absent key (register model); the empty list is "[]". */
|
|
38
|
+
const NIL = 'nil';
|
|
39
|
+
|
|
40
|
+
const INT64_MIN = -(1n << 63n);
|
|
41
|
+
const INT64_MAX = (1n << 63n) - 1n;
|
|
42
|
+
|
|
43
|
+
// formatInt: an integer (a number that is an integer, or a bigint) in decimal, as Go's
|
|
44
|
+
// strconv.FormatInt writes an int64.
|
|
45
|
+
function formatInt(x, what) {
|
|
46
|
+
let b;
|
|
47
|
+
if (typeof x === 'bigint') b = x;
|
|
48
|
+
else if (typeof x === 'number' && Number.isInteger(x)) b = BigInt(x);
|
|
49
|
+
else throw new TypeError(`hydo-assert/history: ${what} must be an integer (number or bigint), got ${typeof x === 'number' ? x : typeof x}`);
|
|
50
|
+
if (b < INT64_MIN || b > INT64_MAX) throw new RangeError(`hydo-assert/history: ${what} ${b} is outside int64`);
|
|
51
|
+
return b.toString();
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
// token: a record argument. A string is taken as is (it must already be one token: encode
|
|
55
|
+
// free-form values with enc); an integer is written in decimal.
|
|
56
|
+
function token(x, what) {
|
|
57
|
+
if (typeof x === 'string') return x;
|
|
58
|
+
return formatInt(x, what);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// Bytes 0x00-0x7f: the byte itself, or %XX for '%', '@', whitespace and control characters
|
|
62
|
+
// (<= ' '), DEL and the list / txn separators ',[]:' (Go's Enc).
|
|
63
|
+
const ASCII = [];
|
|
64
|
+
for (let c = 0; c < 0x80; c++) {
|
|
65
|
+
const esc = c === 0x25 || c === 0x40 || c <= 0x20 || c === 0x7f || ',[]:'.includes(String.fromCharCode(c));
|
|
66
|
+
ASCII.push(esc ? '%' + c.toString(16).toUpperCase().padStart(2, '0') : String.fromCharCode(c));
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* enc makes a value one token, working on the bytes of its UTF-8 form exactly as Go's
|
|
71
|
+
* hydohist.Enc does: '%', '@', whitespace, control characters, DEL and ',[]:' become %XX,
|
|
72
|
+
* other bytes (all of non-ASCII UTF-8) stay; "" is "%" and "nil" is "%6Eil" (the token nil
|
|
73
|
+
* means absent). An integer argument is first written in decimal.
|
|
74
|
+
*/
|
|
75
|
+
function enc(s) {
|
|
76
|
+
s = token(s, 'enc value');
|
|
77
|
+
if (s === '') return '%';
|
|
78
|
+
if (s === NIL) return '%6Eil';
|
|
79
|
+
const b = Buffer.from(s, 'utf8');
|
|
80
|
+
let out = '';
|
|
81
|
+
let i = 0;
|
|
82
|
+
while (i < b.length) {
|
|
83
|
+
const c = b[i];
|
|
84
|
+
if (c < 0x80) {
|
|
85
|
+
out += ASCII[c];
|
|
86
|
+
i++;
|
|
87
|
+
continue;
|
|
88
|
+
}
|
|
89
|
+
// A run of bytes >= 0x80 is a run of whole characters (ASCII never occurs inside a UTF-8
|
|
90
|
+
// sequence), so it decodes back to exactly those characters.
|
|
91
|
+
let j = i + 1;
|
|
92
|
+
while (j < b.length && b[j] >= 0x80) j++;
|
|
93
|
+
out += b.toString('utf8', i, j);
|
|
94
|
+
i = j;
|
|
95
|
+
}
|
|
96
|
+
return out;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** ver is value v (encoded) with the version the store assigned it: "v@83" (int64). */
|
|
100
|
+
function ver(v, version) {
|
|
101
|
+
return enc(v) + '@' + formatInt(version, 'version');
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* valueOrNil is enc(v) when the value is present, else NIL. With one argument a value of null
|
|
106
|
+
* or undefined is absent; with two (Go's ValOrNil(v, ok)) the second says whether it is
|
|
107
|
+
* present.
|
|
108
|
+
*/
|
|
109
|
+
function valueOrNil(v, ok) {
|
|
110
|
+
const present = ok === undefined ? v !== null && v !== undefined : Boolean(ok);
|
|
111
|
+
return present ? enc(v) : NIL;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** list is a list value "[e1,e2,...]" (list-append reads), each element encoded. */
|
|
115
|
+
function list(...elems) {
|
|
116
|
+
return '[' + elems.map((e) => enc(e)).join(',') + ']';
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** List-append txn micro-ops: "a:<k>:<e>", "r:<k>" (invocation), "r:<k>:[...]" (completion). */
|
|
120
|
+
function append(k, e) {
|
|
121
|
+
return 'a:' + enc(k) + ':' + enc(e);
|
|
122
|
+
}
|
|
123
|
+
function read(k) {
|
|
124
|
+
return 'r:' + enc(k);
|
|
125
|
+
}
|
|
126
|
+
function readResult(k, ...l) {
|
|
127
|
+
return 'r:' + enc(k) + ':' + list(...l);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// ---------------------------------------------------------------------------------------------
|
|
131
|
+
// Sink: opened once, at the first record, as the Go recorder opens it.
|
|
132
|
+
//
|
|
133
|
+
// HYDO_HIST_OUT unset or empty: /dev/console; "off": nothing; "stderr": standard error;
|
|
134
|
+
// anything else: that file, appended and created if missing (mode 0644). If it cannot be
|
|
135
|
+
// opened the records go to standard error.
|
|
136
|
+
|
|
137
|
+
const SINK_UNSET = 0;
|
|
138
|
+
const SINK_OFF = 1;
|
|
139
|
+
const SINK_FD = 2;
|
|
140
|
+
let sinkState = SINK_UNSET;
|
|
141
|
+
let sinkFd = -1;
|
|
142
|
+
|
|
143
|
+
function openSink() {
|
|
144
|
+
let p = process.env.HYDO_HIST_OUT || '';
|
|
145
|
+
if (p === 'off') {
|
|
146
|
+
sinkState = SINK_OFF;
|
|
147
|
+
return;
|
|
148
|
+
}
|
|
149
|
+
sinkState = SINK_FD;
|
|
150
|
+
if (p === 'stderr') {
|
|
151
|
+
sinkFd = 2;
|
|
152
|
+
return;
|
|
153
|
+
}
|
|
154
|
+
if (p === '') p = '/dev/console';
|
|
155
|
+
const c = fs.constants;
|
|
156
|
+
const flags = c.O_WRONLY | c.O_APPEND | c.O_CREAT | (c.O_NOCTTY || 0);
|
|
157
|
+
try {
|
|
158
|
+
sinkFd = fs.openSync(p, flags, 0o644);
|
|
159
|
+
} catch (e) {
|
|
160
|
+
sinkFd = 2;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
function writeLine(buf) {
|
|
165
|
+
let off = 0;
|
|
166
|
+
try {
|
|
167
|
+
while (off < buf.length) {
|
|
168
|
+
const n = fs.writeSync(sinkFd, buf, off, buf.length - off);
|
|
169
|
+
if (n <= 0) break;
|
|
170
|
+
off += n; // a short write (which the console never does) is continued, as Go's Write does
|
|
171
|
+
}
|
|
172
|
+
} catch (e) {
|
|
173
|
+
// like the Go recorder: a failed console write is ignored
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
function emit(name, proc, typ, f, args) {
|
|
178
|
+
if (sinkState === SINK_UNSET) openSink();
|
|
179
|
+
if (sinkState === SINK_OFF) return;
|
|
180
|
+
let s = 'HYDO-HIST ' + name + ' ' + proc + ' ' + typ + ' ' + process.hrtime.bigint().toString() + ' ' + f;
|
|
181
|
+
for (const a of args) s += ' ' + (a === '' ? '%' : a);
|
|
182
|
+
writeLine(Buffer.from(s + '\n', 'utf8')); // one write(): never interleaved with other output
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/** One named history (a check's `history:`; [A-Za-z0-9_.-]+). */
|
|
186
|
+
class History {
|
|
187
|
+
constructor(name) {
|
|
188
|
+
this.name = String(name);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* invoke records the invocation of f(args...) by process proc (an integer, or a token
|
|
193
|
+
* without spaces) and returns the operation. args are tokens: encode free-form values with
|
|
194
|
+
* enc (ver, list and NIL help); integers are written in decimal.
|
|
195
|
+
*/
|
|
196
|
+
invoke(proc, f, ...args) {
|
|
197
|
+
const op = new Op(this, token(proc, 'process'), String(f), args.map((a) => token(a, 'argument')));
|
|
198
|
+
emit(this.name, op.proc, 'invoke', op.f, op.args);
|
|
199
|
+
return op;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/** record writes one raw record (for programs that keep their own bookkeeping). */
|
|
203
|
+
record(proc, type, f, ...args) {
|
|
204
|
+
emit(this.name, token(proc, 'process'), String(type), String(f), args.map((a) => token(a, 'argument')));
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** An invoked operation waiting for its completion. */
|
|
209
|
+
class Op {
|
|
210
|
+
constructor(h, proc, f, args) {
|
|
211
|
+
this.history = h;
|
|
212
|
+
this.proc = proc;
|
|
213
|
+
this.f = f;
|
|
214
|
+
this.args = args;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* ok records a successful completion. args are the results in the invocation's layout (a
|
|
219
|
+
* read lists <key> <value> pairs, a txn its micro-ops with read results); with no args the
|
|
220
|
+
* invocation's are repeated.
|
|
221
|
+
*/
|
|
222
|
+
ok(...args) {
|
|
223
|
+
emit(this.history.name, this.proc, 'ok', this.f, args.length === 0 ? this.args : args.map((a) => token(a, 'argument')));
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** fail records that the operation definitely had no effect. */
|
|
227
|
+
fail() {
|
|
228
|
+
emit(this.history.name, this.proc, 'fail', this.f, this.args);
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/** info records that the outcome is unknown (it may take effect at any later time, or never). */
|
|
232
|
+
info() {
|
|
233
|
+
emit(this.history.name, this.proc, 'info', this.f, this.args);
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/** history(name) is new History(name). */
|
|
238
|
+
function history(name) {
|
|
239
|
+
return new History(name);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// _reset forgets the sink (tests): the next record re-reads HYDO_HIST_OUT.
|
|
243
|
+
function _reset() {
|
|
244
|
+
if (sinkState === SINK_FD && sinkFd > 2) {
|
|
245
|
+
try {
|
|
246
|
+
fs.closeSync(sinkFd);
|
|
247
|
+
} catch (e) {
|
|
248
|
+
// already closed
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
sinkState = SINK_UNSET;
|
|
252
|
+
sinkFd = -1;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
module.exports = {
|
|
256
|
+
NIL,
|
|
257
|
+
History,
|
|
258
|
+
Op,
|
|
259
|
+
history,
|
|
260
|
+
enc,
|
|
261
|
+
ver,
|
|
262
|
+
valueOrNil,
|
|
263
|
+
list,
|
|
264
|
+
append,
|
|
265
|
+
read,
|
|
266
|
+
readResult,
|
|
267
|
+
_reset,
|
|
268
|
+
};
|
package/history.mjs
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// ESM entry of hydo-assert/history: re-exports the CommonJS module, so a program that loads the
|
|
2
|
+
// recorder both with require() and with import uses ONE sink.
|
|
3
|
+
import m from './history.js';
|
|
4
|
+
|
|
5
|
+
export const {
|
|
6
|
+
NIL,
|
|
7
|
+
History,
|
|
8
|
+
Op,
|
|
9
|
+
history,
|
|
10
|
+
enc,
|
|
11
|
+
ver,
|
|
12
|
+
valueOrNil,
|
|
13
|
+
list,
|
|
14
|
+
append,
|
|
15
|
+
read,
|
|
16
|
+
readResult,
|
|
17
|
+
} = m;
|
|
18
|
+
export default m;
|
package/index.d.mts
ADDED
package/index.d.ts
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
// Types of hydo-assert (CommonJS entry). The wire format and verdict rules: hydo/ASSERTIONS.md.
|
|
2
|
+
|
|
3
|
+
/** A details value: encoded as Go's encoding/json encodes the corresponding Go value. */
|
|
4
|
+
export type DetailValue =
|
|
5
|
+
| null
|
|
6
|
+
| undefined
|
|
7
|
+
| boolean
|
|
8
|
+
| number
|
|
9
|
+
| bigint
|
|
10
|
+
| string
|
|
11
|
+
| Uint8Array
|
|
12
|
+
| DetailValue[]
|
|
13
|
+
| ReadonlyArray<DetailValue>
|
|
14
|
+
| Map<unknown, DetailValue>
|
|
15
|
+
| Set<DetailValue>
|
|
16
|
+
| { toJSON(): DetailValue }
|
|
17
|
+
| { [key: string]: DetailValue };
|
|
18
|
+
|
|
19
|
+
/** The free-form details object of an evaluation. Absent or empty: no "details" field. */
|
|
20
|
+
export type Details = { [key: string]: DetailValue } | Map<string, DetailValue> | null | undefined;
|
|
21
|
+
|
|
22
|
+
export type CmpOp = '<' | '<=' | '==' | '!=' | '>=' | '>';
|
|
23
|
+
|
|
24
|
+
/** One declared property. */
|
|
25
|
+
export declare class Assertion {
|
|
26
|
+
private constructor();
|
|
27
|
+
readonly id: string;
|
|
28
|
+
readonly msg: string;
|
|
29
|
+
/** Evaluates always / alwaysOrUnreachable / sometimes; returns the condition as a boolean. */
|
|
30
|
+
check(cond: unknown, details?: Details): boolean;
|
|
31
|
+
/** Marks a reachable (ok:true) or unreachable (ok:false, a violation) location as reached. */
|
|
32
|
+
hit(details?: Details): void;
|
|
33
|
+
/** Evaluates `left op right` as a check; left/op/right are added to the details. */
|
|
34
|
+
cmp(left: number | bigint, op: CmpOp, right: number | bigint, details?: Details): boolean;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** One episode of a Liveness property, started at its anchor. */
|
|
38
|
+
export declare class Watch {
|
|
39
|
+
private constructor();
|
|
40
|
+
/** The condition became true now: ok if within the deadline. Returns whether it was in time. */
|
|
41
|
+
done(details?: Details): boolean;
|
|
42
|
+
/** The deadline passed with the condition still false (a violation). */
|
|
43
|
+
expire(details?: Details): void;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** A declared bounded-liveness (eventually) property. */
|
|
47
|
+
export declare class Liveness {
|
|
48
|
+
private constructor();
|
|
49
|
+
readonly id: string;
|
|
50
|
+
readonly withinMs: number;
|
|
51
|
+
/** Starts an episode now (the anchor). */
|
|
52
|
+
begin(): Watch;
|
|
53
|
+
/** Polls cond every pollMs until true or the deadline passed; one record; resolves to the outcome. */
|
|
54
|
+
awaitCond(cond: () => boolean | Promise<boolean>, pollMs: number, details?: Details): Promise<boolean>;
|
|
55
|
+
/** As awaitCond, blocking the thread between evaluations. */
|
|
56
|
+
awaitCondSync(cond: () => boolean, pollMs: number, details?: Details): boolean;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** A declared BUGGIFY fault point. */
|
|
60
|
+
export declare class Point {
|
|
61
|
+
private constructor();
|
|
62
|
+
readonly id: string;
|
|
63
|
+
/** Whether the point misbehaves on this evaluation (always false without a BUGGIFY seed). */
|
|
64
|
+
fire(details?: Details): boolean;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export declare function always(id: string, msg: string): Assertion;
|
|
68
|
+
export declare function alwaysOrUnreachable(id: string, msg: string): Assertion;
|
|
69
|
+
export declare function sometimes(id: string, msg: string): Assertion;
|
|
70
|
+
export declare function reachable(id: string, msg: string): Assertion;
|
|
71
|
+
export declare function unreachable(id: string, msg: string): Assertion;
|
|
72
|
+
export declare function eventually(id: string, msg: string, withinMs: number): Liveness;
|
|
73
|
+
export declare function buggify(id: string, msg: string): Point;
|
|
74
|
+
/** Emits one HYDO-ASSERT-DECL line per declared assertion, in declaration order. */
|
|
75
|
+
export declare function catalog(): void;
|
|
76
|
+
/** Emits HYDO-SETUP-COMPLETE. */
|
|
77
|
+
export declare function setupComplete(): void;
|