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/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,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;