hydo-assert 0.0.0-stage → 0.3.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/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
@@ -0,0 +1,4 @@
1
+ // Types of hydo-assert (ESM entry): the same declarations as the CommonJS entry.
2
+ import m from './index.js';
3
+ export * from './index.js';
4
+ export default m;
package/index.d.ts ADDED
@@ -0,0 +1,131 @@
1
+ // Types of hydo-assert (CommonJS entry). The wire format and verdict rules:
2
+ // https://github.com/kakoc/hydo/blob/main/hydo/ASSERTIONS.md
3
+
4
+ /** A details value: encoded as Go's encoding/json encodes the corresponding Go value. */
5
+ export type DetailValue =
6
+ | null
7
+ | undefined
8
+ | boolean
9
+ | number
10
+ | bigint
11
+ | string
12
+ | Uint8Array
13
+ | DetailValue[]
14
+ | ReadonlyArray<DetailValue>
15
+ | Map<unknown, DetailValue>
16
+ | Set<DetailValue>
17
+ | { toJSON(): DetailValue }
18
+ | { [key: string]: DetailValue };
19
+
20
+ /** The free-form details object of an evaluation. Absent or empty: no "details" field. */
21
+ export type Details = { [key: string]: DetailValue } | Map<string, DetailValue> | null | undefined;
22
+
23
+ /** The operator of {@link Assertion.cmp}. */
24
+ export type CmpOp = '<' | '<=' | '==' | '!=' | '>=' | '>';
25
+
26
+ /** One declared property. Create it with {@link always}, {@link sometimes} and the other declaring functions. */
27
+ export declare class Assertion {
28
+ private constructor();
29
+ /** The property's id, as its records carry it. */
30
+ readonly id: string;
31
+ /** The property's message for people. */
32
+ readonly msg: string;
33
+ /**
34
+ * Checks an `always`, `alwaysOrUnreachable` or `sometimes` property and returns the condition
35
+ * as a boolean. Each outcome is written once per process; a false `sometimes` writes nothing.
36
+ * @example ACKED.check(got === want, { key, got });
37
+ */
38
+ check(cond: unknown, details?: Details): boolean;
39
+ /**
40
+ * Marks a `reachable` (written with ok:true) or `unreachable` (written with ok:false, a
41
+ * violation) location as reached.
42
+ */
43
+ hit(details?: Details): void;
44
+ /**
45
+ * Checks `left op right` as {@link Assertion.check} does, with `left`, `op` and `right` added
46
+ * to the details. Values that cannot be compared make the condition false.
47
+ * @example LOG_SIZE.cmp(size, '<=', 10000);
48
+ */
49
+ cmp(left: number | bigint, op: CmpOp, right: number | bigint, details?: Details): boolean;
50
+ }
51
+
52
+ /** One episode of a {@link Liveness} property, started by {@link Liveness.begin}. Only its first `done` or `expire` counts. */
53
+ export declare class Watch {
54
+ private constructor();
55
+ /** The condition became true now: ok if within the deadline. Returns whether it was in time. */
56
+ done(details?: Details): boolean;
57
+ /** The deadline passed with the condition still false (a violation). */
58
+ expire(details?: Details): void;
59
+ }
60
+
61
+ /** A declared `eventually` property: after an anchor, a condition becomes true within a deadline. */
62
+ export declare class Liveness {
63
+ private constructor();
64
+ /** The property's id. */
65
+ readonly id: string;
66
+ /** The deadline of an episode, in milliseconds after its start. */
67
+ readonly withinMs: number;
68
+ /** Starts an episode now (the anchor). */
69
+ begin(): Watch;
70
+ /**
71
+ * Starts an episode now, evaluates `cond` every `pollMs` (with `setTimeout`, so the event loop
72
+ * keeps running) until it is true or the deadline has passed, writes one record and resolves
73
+ * to the outcome. A condition that becomes true exactly at the deadline still counts.
74
+ * @example await BACK.awaitCond(async () => (await ping()) === 'pong', 100);
75
+ */
76
+ awaitCond(cond: () => boolean | Promise<boolean>, pollMs: number, details?: Details): Promise<boolean>;
77
+ /** As {@link Liveness.awaitCond}, but blocks the thread between evaluations (`Atomics.wait`). */
78
+ awaitCondSync(cond: () => boolean, pollMs: number, details?: Details): boolean;
79
+ }
80
+
81
+ /**
82
+ * A declared fault point (BUGGIFY): a place where the program misbehaves on purpose when hydo
83
+ * turns the point on for a run. Its catalog entry is the `sometimes` property `buggify.<id>`.
84
+ */
85
+ export declare class Point {
86
+ private constructor();
87
+ /** The point's id (without the `buggify.` prefix of its catalog entry). */
88
+ readonly id: string;
89
+ /**
90
+ * Whether the point misbehaves on this call. Always false, with no other effect, when no
91
+ * BUGGIFY seed is configured (`HYDO_BUGGIFY`, or the file `HYDO_BUGGIFY_FILE` names).
92
+ * @example if (LOST_REPLY.fire({ key })) return;
93
+ */
94
+ fire(details?: Details): boolean;
95
+ }
96
+
97
+ /**
98
+ * Declares a property that must hold every time it is checked, and be checked at least once.
99
+ * Declare properties at the top level of a module, so that {@link catalog} lists them.
100
+ * @param id a stable id, for example `'kv.acked_durable'`
101
+ * @param msg what the property says, for people
102
+ * @example const ACKED = ha.always('kv.acked_durable', 'every acknowledged write reads back');
103
+ */
104
+ export declare function always(id: string, msg: string): Assertion;
105
+ /** Declares a property that must hold every time it is checked; never being checked is fine. */
106
+ export declare function alwaysOrUnreachable(id: string, msg: string): Assertion;
107
+ /** Declares a property that must be true at least once across an exploration. */
108
+ export declare function sometimes(id: string, msg: string): Assertion;
109
+ /** Declares a code location that must be reached at least once across an exploration ({@link Assertion.hit}). */
110
+ export declare function reachable(id: string, msg: string): Assertion;
111
+ /** Declares a code location that must never be reached ({@link Assertion.hit} is a violation). */
112
+ export declare function unreachable(id: string, msg: string): Assertion;
113
+ /**
114
+ * Declares an `eventually` property: after an anchor, a condition becomes true within
115
+ * `withinMs` milliseconds of guest time.
116
+ * @example const BACK = ha.eventually('kv.back', 'the server answers within 5 s', 5000);
117
+ */
118
+ export declare function eventually(id: string, msg: string, withinMs: number): Liveness;
119
+ /**
120
+ * Declares a fault point (BUGGIFY).
121
+ * @example const LOST_REPLY = ha.buggify('kv.lost_reply', 'the write lands but the reply is lost');
122
+ */
123
+ export declare function buggify(id: string, msg: string): Point;
124
+ /**
125
+ * Writes one `HYDO-ASSERT-DECL` line per declared property, in declaration order, so that hydo
126
+ * can report the properties that were never evaluated. Call it once, early, in the process
127
+ * whose console hydo reads.
128
+ */
129
+ export declare function catalog(): void;
130
+ /** Writes `HYDO-SETUP-COMPLETE`: the system is ready, and hydo may start injecting faults. */
131
+ export declare function setupComplete(): void;