hydo-assert 0.2.0 → 0.3.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.
Files changed (4) hide show
  1. package/README.md +231 -217
  2. package/history.d.ts +12 -2
  3. package/index.d.ts +67 -13
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,235 +1,249 @@
1
- # hydo-assert: the JavaScript assertion SDK (Node.js)
1
+ # hydo-assert for JavaScript (Node.js)
2
2
 
3
- A Node.js program running under hydo (the deterministic hypervisor of
4
- [github.com/kakoc/hydo](https://github.com/kakoc/hydo)) uses this package to say what must be
5
- true, what should happen at least once, what must happen within a deadline, and where a
6
- dependency may misbehave. It writes the same console records as the Go SDK (`sdk/go`), byte for
7
- byte, with the same deduplication rules, so `hydo run` and the explorer (`hydo explore`) read
8
- them unchanged. The wire format and the verdict rules are in
9
- `hydo/ASSERTIONS.md` of that repository; paths below are relative to it.
3
+ [hydo](https://github.com/kakoc/hydo) runs a whole system in a deterministic virtual machine,
4
+ injects faults (process kills, network faults, power cuts, disk errors) and replays every
5
+ failure bit for bit. This package lets a Node.js program that runs under hydo say, from the
6
+ inside, what must be true and what should happen. hydo collects what the program reports, and
7
+ an exploration (many runs with different faults) reports each property as passed, failed (with
8
+ a schedule that replays the failure) or never exercised.
10
9
 
11
- The package has no dependencies, works from CommonJS and ESM, and ships TypeScript types.
12
- Install it from npm (`npm install hydo-assert`), or depend on a checkout by path:
10
+ The package has no dependencies, and it works from CommonJS and from ES modules. It ships
11
+ TypeScript types, and it needs Node.js 16 or later. Outside hydo it does almost nothing: the records go to
12
+ standard error (or nowhere), and fault points stay off.
13
13
 
14
- ```json
15
- { "dependencies": { "hydo-assert": "file:../hydo/sdk/js" } }
14
+ ## Install
15
+
16
+ ```sh
17
+ npm install hydo-assert
16
18
  ```
17
19
 
18
- In a guest image, copy `package.json`, `index.js` and `index.mjs` to
19
- `/<app>/node_modules/hydo-assert/` (see `hydo/onboard/examples/node-kv/hydo-mac.yaml`).
20
+ In a guest image without npm, copy `package.json`, `index.js` and `index.mjs` (and
21
+ `history.js` and `history.mjs` for histories) to `node_modules/hydo-assert/` next to the
22
+ program.
23
+
24
+ ## A complete program
20
25
 
21
- ## Use
26
+ A small key/value store that declares three properties and checks them:
22
27
 
23
28
  ```js
24
- const ha = require('hydo-assert'); // or: import * as ha from 'hydo-assert'
29
+ const ha = require('hydo-assert'); // or: import * as ha from 'hydo-assert';
30
+
31
+ const READ_BACK = ha.always('kv.read_back', 'every acknowledged write reads back with its value');
32
+ const OVERWRITE = ha.sometimes('kv.overwrite', 'a write replaced an existing value');
33
+ const LOST_REPLY = ha.buggify('kv.lost_reply', 'the write lands but its reply is lost');
34
+
35
+ ha.catalog(); // list every property, also the ones that never run
36
+ const store = new Map();
37
+ ha.setupComplete(); // the system is ready: hydo may start injecting faults
38
+
39
+ for (const [key, value] of [['a', 1], ['b', 2], ['a', 3]]) {
40
+ const old = store.get(key);
41
+ store.set(key, value);
42
+ OVERWRITE.check(old !== undefined, { key });
43
+ if (LOST_REPLY.fire({ key })) {
44
+ continue; // the client never hears back (only when hydo turns this point on)
45
+ }
46
+ const acked = store.get(key) === value;
47
+ READ_BACK.check(acked, { key, value });
48
+ }
49
+ ```
25
50
 
26
- // Declare at module top level (load time), so the catalog knows every property up front.
27
- const ACKED = ha.always('kv.acked_durable', 'every acknowledged write reads back with its value');
28
- const RECOVERED = ha.sometimes('kv.recovered', 'the server replayed a non-empty log');
29
- const TORN = ha.reachable('kv.torn_tail', 'the log ended in a partial line');
30
- const OVERWRITE = ha.unreachable('kv.overwrite', 'a key is never overwritten with another value');
31
- const LOG_SIZE = ha.always('kv.log_size', 'the log stays under its cap');
32
- const BACK = ha.eventually('kv.back', 'the server answers within 5 s', 5000);
33
- const LOST_REPLY = ha.buggify('kv.put.lost_reply', 'the write lands but the reply is lost');
34
-
35
- ha.catalog(); // once, early, in one process: HYDO-ASSERT-DECL lines
36
- ACKED.check(got === want, { key: k, got });
37
- RECOVERED.check(n > 0, { keys: n });
38
- TORN.hit({ bytes });
39
- OVERWRITE.hit({ key });
40
- LOG_SIZE.cmp(size, '<=', cap); // details: left, op, right
41
- if (LOST_REPLY.fire({ key })) { socket.destroy(); return; }
42
- await BACK.awaitCond(async () => (await ping()) === 'pong', 100); // one record per episode
43
- ha.setupComplete(); // HYDO-SETUP-COMPLETE
51
+ Run it with `HYDO_ASSERT_OUT=stderr` to see what it reports. It writes these lines (under hydo
52
+ they go to the guest's console, where hydo reads them):
53
+
54
+ ```text
55
+ HYDO-ASSERT-DECL {"t":"always","id":"kv.read_back","msg":"every acknowledged write reads back with its value"}
56
+ HYDO-ASSERT-DECL {"t":"sometimes","id":"kv.overwrite","msg":"a write replaced an existing value"}
57
+ HYDO-ASSERT-DECL {"t":"sometimes","id":"buggify.kv.lost_reply","msg":"fault point fired: the write lands but its reply is lost"}
58
+ HYDO-SETUP-COMPLETE
59
+ HYDO-ASSERT {"t":"always","id":"kv.read_back","ok":true,"msg":"every acknowledged write reads back with its value","details":{"key":"a","value":1}}
60
+ HYDO-ASSERT {"t":"sometimes","id":"kv.overwrite","ok":true,"msg":"a write replaced an existing value","details":{"key":"a"}}
44
61
  ```
45
62
 
46
- | Go SDK (`hydoassert`) | JavaScript (`hydo-assert`) |
47
- |---|---|
48
- | `Always(id, msg)`, `AlwaysOrUnreachable`, `Sometimes`, `Reachable`, `Unreachable` | `always(id, msg)`, `alwaysOrUnreachable`, `sometimes`, `reachable`, `unreachable` |
49
- | `a.Check(cond, d)`, `a.Hit(d)` | `a.check(cond, d)` (returns the condition as a boolean), `a.hit(d)` |
50
- | `a.Cmp(left, op, right, d)` | `a.cmp(left, op, right, d)` (numbers or bigints; `op` is one of `<`, `<=`, `==`, `!=`, `>=`, `>`) |
51
- | `Eventually(id, msg, within)` | `eventually(id, msg, withinMs)` |
52
- | `l.Await(cond, poll, d)` | `await l.awaitCond(cond, pollMs, d)` (cond may return a promise); `l.awaitCondSync(cond, pollMs, d)` blocks the thread |
53
- | `l.Begin()`, `w.Done(d)`, `w.Expire(d)` | `l.begin()`, `w.done(d)`, `w.expire(d)` |
54
- | `Buggify(id, msg)`, `p.Fire(d)` | `buggify(id, msg)`, `p.fire(d)` |
55
- | `Catalog()`, `SetupComplete()` | `catalog()`, `setupComplete()` |
56
- | `D{...}` | a plain object (or a `Map`) |
57
-
58
- That table, the classes the calls return (`Assertion`, `Liveness`, `Watch`, `Point`) and the
59
- history recorder below are the whole API, as `index.d.ts` declares it: a comparison has one
60
- form, `cmp` with its operator. Exports and fields whose names start with `_` and fields that
61
- `index.d.ts` does not declare are the package's own and may change in any version.
62
-
63
- ## Records, deduplication, catalog
64
-
65
- - Records go to `/dev/ttyS0`, opened once (`O_WRONLY|O_APPEND|O_NOCTTY`), one synchronous
66
- `write` per record (`fs.writeSync`), so a record is never interleaved with other console
67
- output and is on the console before the call returns. `HYDO_ASSERT_OUT=<path>` writes to that
68
- existing file, `stderr` to standard error (plain logging outside hydo), `off` nowhere (a
69
- no-op; BUGGIFY still works). If the file cannot be opened, standard error is used.
70
- - A process writes each (assertion, outcome) pair once: the first pass and the first failure,
71
- with the details of that evaluation. A `sometimes` that evaluated false is never written.
72
- `unreachable` is written with `ok:false`. As in Go, a record whose details cannot be encoded
73
- (a NaN, an infinity, a cycle) is not written at all, and that outcome still counts as
74
- written.
75
- - `catalog()` writes one `HYDO-ASSERT-DECL` line per declared assertion, in declaration order
76
- (each call writes all of them again, as Go's `Catalog()` does). Declare at module top level,
77
- so a property in code that never runs is still in the catalog and is reported as never
78
- evaluated. Under hydo the explorer's runs start from a snapshot taken after the services are
79
- up, so a long-running server's start-up catalog is not in each run's console: let a
80
- short-lived process that runs in every run (the oracle, a client) call `catalog()` too, and
81
- declare the properties in one module that every program loads (as `node-kv/props.cjs` does).
82
- - "Per process": a worker thread (`worker_threads`) loads its own copy of the module, with its
83
- own deduplication table. The ESM entry re-exports the CommonJS module, so a program that uses
84
- both `require` and `import` has one state.
85
-
86
- ### How details are encoded (exactly as Go's `encoding/json`)
87
-
88
- | JavaScript value | written as | Go value it matches |
63
+ A process writes each outcome of a property once: the first pass and the first failure, with
64
+ the details of that evaluation. That is why the later passes of `kv.read_back` write nothing.
65
+
66
+ ## How to
67
+
68
+ ### Declare properties and check them
69
+
70
+ A property has an id (stable across versions of your program) and a message for people. Its
71
+ kind says what hydo expects:
72
+
73
+ | kind | the property holds when | hydo reports a failure when |
89
74
  |---|---|---|
90
- | object / `Map` | object, keys sorted by their UTF-8 bytes (not by JavaScript's UTF-16 order) | `map[string]any` |
91
- | array, `Set`, typed arrays other than `Uint8Array` | array | slice |
92
- | `Uint8Array`, `Buffer` | base64 string | `[]byte` |
93
- | number | shortest digits; exponent form below 1e-6 and from 1e21 (`1e+21`, `1.5e-7`); `-0` as `-0` | `float64` (and Go integers, which print the same) |
94
- | bigint | decimal integer | `int64`, `uint64` |
95
- | string | `"`, `\` escaped; `\b \f \n \r \t`; other control characters `\u00xx`; `<` `>` `&` as `<` `>` `&`; U+2028/U+2029 escaped; a lone surrogate as `�` | `string` (invalid UTF-8 as `�`) |
96
- | `true`, `false`, `null` | the same | |
97
- | a value with `toJSON()` (e.g. `Date`) | its result | |
98
- | `undefined`, function, symbol | left out of objects, `null` in arrays (as `JSON.stringify`) | |
99
- | NaN, ±Infinity, a cycle | the record is not written | `json.Marshal` fails |
100
- | details that are not an object (a string, an array) | `{"value": ...}` | |
101
-
102
- An absent or empty details object gives no `details` field (Go's `omitempty`). `cmp` adds
103
- `left`/`op`/`right`, `eventually` adds `elapsed_ms`/`within_ms`, and a
104
- fired fault point adds `hit`: each to the caller's own object (or `Map`) when one is given, as
105
- the Go SDK writes into the caller's map.
106
-
107
- **Go version note.** The shared cases hold the bytes of Go 1.26.5, the version this
108
- repository's Go programs are built with. Go 1.27 changed one detail of `encoding/json`: invalid
109
- UTF-8 is written as a raw U+FFFD character instead of the escape `\ufffd`. This package
110
- writes the escape (the Go 1.26 form); everything else is the same for both Go versions.
111
-
112
- ## Eventually
113
-
114
- `eventually(id, msg, withinMs)` declares a bounded-liveness property. One episode = one anchor
115
- and one deadline, measured on the monotonic clock (`process.hrtime`; deterministic under hydo):
116
-
117
- - `await l.awaitCond(cond, pollMs, d)` anchors now, evaluates `cond` (sync or async) every
118
- `pollMs` (with `setTimeout`, so the event loop keeps running) until it is true or the
119
- deadline has passed, writes one record and resolves to the outcome. The last evaluation
120
- happens at or after the deadline, so a condition that becomes true exactly then still counts.
121
- - `l.awaitCondSync(cond, pollMs, d)` does the same and blocks the thread between evaluations
122
- (`Atomics.wait`): only for scripts that have nothing else to do.
123
- - `w = l.begin()` anchors now; `w.done(d)` records "true now" (ok if in time), `w.expire(d)`
124
- records a miss. Only the first of them counts for one watch.
125
-
126
- ## BUGGIFY
127
-
128
- Same decisions as the Go SDK, bit for bit: configured by `$HYDO_BUGGIFY`, or else the file
129
- `$HYDO_BUGGIFY_FILE` (default `/tmp/hydo-buggify`), holding
130
- `<seed-hex>[,<enable-permille>[,<fire-permille>]]` (defaults 250 and 250, FoundationDB's values;
131
- parsed as Go parses it: hex seed without `0x`, Go's whitespace trimming, a bad enable or fire
132
- value keeps the default). It is read once, at the first evaluation of any point, which also
133
- writes `HYDO-BUGGIFY {"seed":..,"enable_pm":..,"fire_pm":..,"enabled":[..]}`. A point is enabled
134
- for the run when `splitmix64(seed ^ fnv1a(id)) % 1000 < enable`; its k-th evaluation fires when
135
- `splitmix64(splitmix64(seed ^ fnv1a(id)) + k·0x9e3779b97f4a7c15) % 1000 < fire` (64-bit
136
- arithmetic with `BigInt`). Each point is also a `sometimes` property `buggify.<id>`
137
- ("fault point fired: <msg>"), recorded at its first firing with `{"hit": k}`. Without a
138
- configuration every point returns false and has no other effect. Under hydo the schedule token
139
- `B=<seed>` (`hydo explore --buggify`) reaches the file through the guest init: an onboarded
140
- project gets it with `buggify: true` in its `hydo.yaml` (`hydo/onboard/MANIFEST.md`).
141
-
142
- ## History recorder
143
-
144
- The entry `hydo-assert/history` records operation histories for hydo's host-side checkers
145
- (linearizability of a register or compare-and-set object per key, and Elle-style list-append;
146
- the format and the checkers are in `hydo/HISTORIES.md`). It writes the same `HYDO-HIST` lines as
147
- the Go recorder (`sdk/go/hydohist`), byte for byte except the time field. It is separate from
148
- the assertion SDK, so loading it changes nothing the assertion records contain. In a guest
149
- image, also copy `history.js` and `history.mjs`.
75
+ | `always` | the condition is true every time, and it is checked at least once | it is false once, or never checked |
76
+ | `alwaysOrUnreachable` | the condition is true every time it is checked | it is false once |
77
+ | `sometimes` | the condition is true at least once in an exploration | it is never true |
78
+ | `reachable` | the code is reached at least once in an exploration | it is never reached |
79
+ | `unreachable` | the code is never reached | it is reached |
80
+
81
+ Declare properties at the top level of a module, so that the catalog lists them once the
82
+ module is loaded:
83
+
84
+ ```js
85
+ const ha = require('hydo-assert');
86
+
87
+ const STORED = ha.always('kv.stored', 'every acknowledged write is stored');
88
+ const PARSES = ha.alwaysOrUnreachable('kv.log_parses', 'every complete log line parses');
89
+ const RETRIED = ha.sometimes('kv.retried', 'a client retried a request');
90
+ const RECOVERED = ha.reachable('kv.recovered', 'the server replayed a non-empty log');
91
+ const UNKNOWN = ha.unreachable('kv.unknown_command', 'the server got a command it does not know');
92
+
93
+ STORED.check(true, { key: 'a' }); // returns the condition
94
+ PARSES.check(true); // the details are optional
95
+ RETRIED.check(false); // a false `sometimes` writes nothing
96
+ RECOVERED.hit({ entries: 3 });
97
+ const command = 'GET';
98
+ if (command !== 'GET' && command !== 'SET') {
99
+ UNKNOWN.hit({ command });
100
+ }
101
+ ```
102
+
103
+ ### Compare two values
104
+
105
+ `cmp` checks `left op right` and puts both values and the operator into the details, so a
106
+ failure shows them:
107
+
108
+ ```js
109
+ const ha = require('hydo-assert');
110
+
111
+ const LOG_SIZE = ha.always('kv.log_size', 'the log stays under its cap');
112
+ const size = 12;
113
+ LOG_SIZE.cmp(size, '<=', 10000); // details: {"left":12,"op":"<=","right":10000}
114
+ ```
115
+
116
+ The operator is one of `<`, `<=`, `==`, `!=`, `>=` and `>`; the values are numbers or bigints.
117
+
118
+ ### Check that something happens in time (eventually)
119
+
120
+ An `eventually` property says that after this point, the condition becomes true within a
121
+ deadline. For example: after a restart, the server answers within 5 seconds. Time inside a hydo
122
+ guest is deterministic, so the verdict is the same on every replay.
123
+
124
+ ```js
125
+ const ha = require('hydo-assert');
126
+
127
+ const BACK = ha.eventually('kv.back', 'the server answers within 5 s of its start', 5000); // ms
128
+ const started = Date.now();
129
+ const answers = async () => Date.now() - started >= 20; // stands for a real request
130
+
131
+ (async () => {
132
+ const inTime = await BACK.awaitCond(answers, 5); // polls every 5 ms
133
+ if (!inTime) throw new Error('late');
134
+
135
+ // Or mark the start and the end yourself:
136
+ const watch = BACK.begin();
137
+ // ... the server comes up ...
138
+ watch.done(); // or watch.expire() when you know it will not
139
+ })();
140
+ ```
141
+
142
+ `awaitCond` keeps the event loop running between checks, and its condition may return a
143
+ promise. `awaitCondSync` blocks the thread instead, for scripts that have nothing else to do.
144
+
145
+ ### Add a fault point (BUGGIFY)
146
+
147
+ A fault point is a place where your program misbehaves on purpose: it drops a reply, fails a
148
+ write, waits too long. Normally the point does nothing (`fire` returns false). hydo can turn
149
+ points on for a run, so that faults happen where only your program can make them. FoundationDB
150
+ calls this technique BUGGIFY.
150
151
 
151
152
  ```js
152
- const hh = require('hydo-assert/history'); // or: import * as hh from 'hydo-assert/history'
153
-
154
- const kv = new hh.History('kv'); // or hh.history('kv')
155
- let op = kv.invoke(3, 'write', 'k1', hh.enc(v)); // process 3, before the request
156
- try {
157
- const rev = await put('k1', v);
158
- op.ok('k1', hh.ver(v, rev)); // the version the store assigned, if any
159
- } catch (e) {
160
- if (rejected(e)) op.fail(); // it definitely had no effect
161
- else op.info(); // a timeout: the outcome is unknown
153
+ const ha = require('hydo-assert');
154
+
155
+ const LOST_REPLY = ha.buggify('kv.lost_reply_point', 'the write lands but its reply is lost');
156
+ const SLOW_DISK = ha.buggify('kv.slow_disk', 'a write takes 10 ms longer');
157
+
158
+ let reply = 'OK';
159
+ if (LOST_REPLY.fire()) {
160
+ reply = null; // misbehave: the client never gets the reply
162
161
  }
163
- kv.invoke(3, 'read', 'k1').ok('k1', hh.valueOrNil(await get('k1'))); // null means absent
162
+ const delay = SLOW_DISK.fire({ key: 'a' }) ? 10 : 0;
163
+ setTimeout(() => console.log(reply), delay);
164
+ ```
165
+
166
+ To let hydo turn the points on, add `buggify: true` to the project's `hydo.yaml` and explore
167
+ with `hydo explore --buggify`. Each run then gets a seed that turns some points on, and a point
168
+ that is on fires on some of its calls. To try it outside hydo, set
169
+ `HYDO_BUGGIFY=<seed in hex>,<points on, per mille>,<calls that fire, per mille>`; for example
170
+ `HYDO_BUGGIFY=2a,1000,1000` makes every point fire every time.
171
+
172
+ ### Record an operation history
173
+
174
+ hydo can check a whole history of operations after a run. It checks that every read is
175
+ consistent with the writes before it (linearizability per key), and that no list append goes
176
+ missing. Your workload's
177
+ client records each operation twice: when it starts (`invoke`) and when the outcome is known.
178
+
179
+ ```js
180
+ const hh = require('hydo-assert/history'); // or: import * as hh from 'hydo-assert/history';
181
+
182
+ const kv = hh.history('kv');
183
+ const write = kv.invoke(3, 'write', 'k1', hh.enc('v1')); // client 3, before the request
184
+ // ... send the request, then record the outcome:
185
+ write.ok(); // it happened; fail(): it did not; info(): the outcome is unknown
186
+ const read = kv.invoke(3, 'read', 'k1');
187
+ read.ok('k1', hh.valueOrNil('v1'));
188
+ ```
189
+
190
+ Then name the history in the project's `hydo.yaml`:
164
191
 
165
- const la = hh.history('la');
166
- const tx = la.invoke(4, 'txn', hh.append('x', '1'), hh.read('y'));
167
- tx.ok(hh.append('x', '1'), hh.readResult('y', '1', '2'));
192
+ ```yaml
193
+ checks:
194
+ - id: kv.linearizable
195
+ type: linearizable
196
+ model: register
197
+ history: kv
198
+ msg: every read sees the latest acknowledged write
168
199
  ```
169
200
 
170
- | Go (`hydohist`) | JavaScript (`hydo-assert/history`) |
171
- |---|---|
172
- | `New(name)` | `new History(name)` or `history(name)` |
173
- | `h.Invoke(proc, f, args...)`, `h.Record(proc, typ, f, args...)` | `h.invoke(proc, f, ...args)`, `h.record(proc, type, f, ...args)` |
174
- | `op.Ok(args...)`, `op.Fail()`, `op.Info()` | `op.ok(...args)` (no args repeats the invocation's), `op.fail()`, `op.info()` |
175
- | `Enc`, `Ver`, `ValOrNil(v, ok)`, `List` | `enc`, `ver`, `valueOrNil`, `list` |
176
- | `Append`, `Read`, `ReadResult`, `Nil` | `append`, `read`, `readResult`, `NIL` |
177
-
178
- - `valueOrNil(v)` treats `null` and `undefined` as absent. `valueOrNil(v, ok)` follows Go: the
179
- second argument says whether the value is present.
180
- - A process is an integer or a token without spaces. Arguments are tokens: a string is written
181
- as it is (encode free-form values with `enc`), and an integer (a number that is an integer,
182
- or a bigint) is written in decimal. Versions are int64 values; pass a bigint beyond 2^53.
183
- A value outside int64 throws a `RangeError`, and a value that is not an integer throws a
184
- `TypeError`.
185
- - Records go to `/dev/console`. `HYDO_HIST_OUT=<path>` appends to that file and creates it if
186
- it is missing (mode 0644), `stderr` writes to standard error, and `off` writes nothing. If the
187
- file cannot be opened, standard error is used. The setting is read once, at the first record,
188
- and is separate from `HYDO_ASSERT_OUT`.
189
- - Each record is one `fs.writeSync` call. The time field is `process.hrtime.bigint()`
190
- (CLOCK_MONOTONIC on Linux, deterministic under hydo). The ESM entry re-exports the CommonJS
191
- module, so a program that uses both has one sink; a worker thread opens its own.
192
- - Text is written as UTF-8, and `enc` works on the UTF-8 bytes exactly as Go's `Enc` does. A
193
- JavaScript string cannot hold invalid UTF-8; a lone surrogate is written (and encoded) as
194
- U+FFFD, as `Buffer.from` and `TextEncoder` convert it.
195
- - A process has at most one operation in flight: give each concurrent client its own process
196
- number. Record the invocation before sending the request and the completion after the reply,
197
- because the checkers order operations by the position of their records.
198
-
199
- ## Tests
200
-
201
- - `npm test` (`node --test test/unit.test.js test/history.test.js`): what the shared cases cannot
202
- express (cycles, `undefined`, `Map`/`Set`, `Date`, async liveness, the sink switches) and the
203
- BUGGIFY rates over 400 seeds; for the history recorder, the exact lines of the Go recorder's
204
- own unit test, the encoding of every byte class, the argument checks, the sink settings and
205
- one `fs.writeSync` per record.
206
- - `node --test` (every file in `test/`; `npm test` runs the two unit-test files only) also
207
- runs `test/cases.test.js`: the shared cases (`sdk/cases`, written by the reference SDK,
208
- `sdk/rust`; format and rules in `sdk/rust/README.md`, "The shared cases"). For every case
209
- and run it starts itself as a child process, once through the CommonJS and once through the
210
- ESM entry, makes the case's calls with this package and `hydo-assert/history`, and compares
211
- the bytes the sink received and the calls' results with the case's files. Cases that need a
212
- float32 (`f32`) or invalid UTF-8 bytes in a history record (`raw_hist`, which a JavaScript
213
- string cannot hold) are skipped and listed. To add a case, add it to the Rust SDK's
214
- `tests/cases/defs.rs` and run `HYDO_BLESS=1 cargo test --test cases` there; this test then
215
- runs it. A format change starts in the Rust SDK too: after it is blessed, this test fails on
216
- the lines this package must change. No other language is needed to run it.
217
- - `package.json`, `index.js` and `index.mjs` are copied into the node-kv example's images, so
218
- a change to any of them changes those images' bytes and every node-kv fingerprint (the last
219
- such change, the `Apache-2.0` license field and the removed `conformance` script of the
220
- deleted Go-binary harnesses, re-recorded them in milestone 152, and a reworded comment in
221
- `index.js` in milestone 157; docs/REBASELINE.md has the values).
222
-
223
- ## Example
224
-
225
- `hydo/onboard/examples/node-kv/` is a complete example for the Mac backend: a key/value server
226
- (ESM) and its client and oracle (CommonJS) using this package, the pinned aarch64 Node.js and a
227
- `hydo-mac.yaml`.
228
-
229
- ## Limits
230
-
231
- - Node.js only (it uses `fs`, `Buffer` and `process.hrtime`); not for browsers or Deno/Bun as
232
- tested targets. Node 16 or later (BigInt, `Atomics.wait`).
233
- - Each worker thread has its own deduplication table and console file descriptor.
234
- - No call-site helpers that capture the file and line (the Rust SDK's macros do); declare
235
- properties with explicit ids.
201
+ `hydo guide checks` describes the checks and their options.
202
+
203
+ ### Choose where the records go
204
+
205
+ Under hydo the records go to the guest's console (`/dev/ttyS0` for properties, `/dev/console`
206
+ for histories), which hydo reads even when the program's standard output goes to a log file.
207
+ Outside hydo, where the console cannot be opened, they go to standard error. Two variables
208
+ change this, and each is read once, at the first record:
209
+
210
+ - `HYDO_ASSERT_OUT`: a path of an existing file, `stderr`, or `off` for the properties;
211
+ - `HYDO_HIST_OUT`: a path (created if missing), `stderr`, or `off` for the histories.
212
+
213
+ ### Run a Node.js program in a hydo guest
214
+
215
+ A complete project with a `hydo.yaml` for hydo on a Mac is the node-kv example:
216
+ <https://github.com/kakoc/hydo/tree/main/hydo/onboard/examples/node-kv>.
217
+
218
+ ## Reference
219
+
220
+ - The API: the TypeScript declarations `index.d.ts` and `history.d.ts`, with a comment on every
221
+ call (your editor shows them).
222
+ - The records, and how hydo judges each property type:
223
+ <https://github.com/kakoc/hydo/blob/main/hydo/ASSERTIONS.md>.
224
+ - The history format and the checkers:
225
+ <https://github.com/kakoc/hydo/blob/main/hydo/HISTORIES.md>.
226
+ - The same SDK for Rust, Python and Go writes the same records, byte for byte:
227
+ <https://github.com/kakoc/hydo/tree/main/sdk>.
228
+
229
+ Rules of this package:
230
+
231
+ - The catalog (`catalog()`) lists the properties in the order they were declared. Call it
232
+ once, early, in the process whose console hydo reads.
233
+ - Details are encoded as Go's `encoding/json` encodes the same values:
234
+ - object and `Map` keys in UTF-8 byte order;
235
+ - a `Set` or a typed array as an array, and a `Uint8Array` or `Buffer` as base64;
236
+ - a bigint as an integer, with `undefined` and functions left out.
237
+
238
+ Details that are not an object are wrapped as `{"value": ...}`. A record whose details hold a
239
+ NaN, an infinity, or a cycle is not written.
240
+ - Every record is one synchronous write, so it is on the console before the call returns. The
241
+ ES module entry re-exports the CommonJS one, so a program that uses both has one state; a
242
+ worker thread has its own.
243
+ - A history's process is an integer or a token without spaces; its arguments are tokens
244
+ (encode free-form values with `enc`). Versions are int64 values (pass a bigint beyond 2^53).
245
+ A process has at most one operation in flight.
246
+
247
+ ## License
248
+
249
+ Apache-2.0.
package/history.d.ts CHANGED
@@ -1,4 +1,5 @@
1
- // Types of hydo-assert/history (CommonJS entry). The wire format and checkers: hydo/HISTORIES.md.
1
+ // Types of hydo-assert/history (CommonJS entry). The wire format and checkers:
2
+ // https://github.com/kakoc/hydo/blob/main/hydo/HISTORIES.md
2
3
 
3
4
  /** A record argument: a string that is already one token (see enc), or an integer. */
4
5
  export type Token = string | number | bigint;
@@ -6,9 +7,14 @@ export type Token = string | number | bigint;
6
7
  /** The value of an absent key (register model). */
7
8
  export declare const NIL: 'nil';
8
9
 
9
- /** One named history (a check's `history:`; [A-Za-z0-9_.-]+). */
10
+ /**
11
+ * One named history: the `history:` of a check in the project's `hydo.yaml`.
12
+ * @example const kv = new History('kv');
13
+ */
10
14
  export declare class History {
15
+ /** @param name the history's name, `[A-Za-z0-9_.-]+` */
11
16
  constructor(name: string);
17
+ /** The history's name. */
12
18
  readonly name: string;
13
19
  /**
14
20
  * Records the invocation of f(args...) by process `proc` (an integer, or a token without
@@ -22,9 +28,13 @@ export declare class History {
22
28
  /** An invoked operation waiting for its completion. */
23
29
  export declare class Op {
24
30
  private constructor();
31
+ /** The history the operation belongs to. */
25
32
  readonly history: History;
33
+ /** The process that invoked it. */
26
34
  readonly proc: string;
35
+ /** The operation's function, for example `'write'`. */
27
36
  readonly f: string;
37
+ /** The invocation's arguments, as tokens. */
28
38
  readonly args: string[];
29
39
  /** A successful completion; with no args the invocation's are repeated. */
30
40
  ok(...args: Token[]): void;
package/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
- // Types of hydo-assert (CommonJS entry). The wire format and verdict rules: hydo/ASSERTIONS.md.
1
+ // Types of hydo-assert (CommonJS entry). The wire format and verdict rules:
2
+ // https://github.com/kakoc/hydo/blob/main/hydo/ASSERTIONS.md
2
3
 
3
4
  /** A details value: encoded as Go's encoding/json encodes the corresponding Go value. */
4
5
  export type DetailValue =
@@ -19,22 +20,36 @@ export type DetailValue =
19
20
  /** The free-form details object of an evaluation. Absent or empty: no "details" field. */
20
21
  export type Details = { [key: string]: DetailValue } | Map<string, DetailValue> | null | undefined;
21
22
 
23
+ /** The operator of {@link Assertion.cmp}. */
22
24
  export type CmpOp = '<' | '<=' | '==' | '!=' | '>=' | '>';
23
25
 
24
- /** One declared property. */
26
+ /** One declared property. Create it with {@link always}, {@link sometimes} and the other declaring functions. */
25
27
  export declare class Assertion {
26
28
  private constructor();
29
+ /** The property's id, as its records carry it. */
27
30
  readonly id: string;
31
+ /** The property's message for people. */
28
32
  readonly msg: string;
29
- /** Evaluates always / alwaysOrUnreachable / sometimes; returns the condition as a boolean. */
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
+ */
30
38
  check(cond: unknown, details?: Details): boolean;
31
- /** Marks a reachable (ok:true) or unreachable (ok:false, a violation) location as reached. */
39
+ /**
40
+ * Marks a `reachable` (written with ok:true) or `unreachable` (written with ok:false, a
41
+ * violation) location as reached.
42
+ */
32
43
  hit(details?: Details): void;
33
- /** Evaluates `left op right` as a check; left/op/right are added to the details. */
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
+ */
34
49
  cmp(left: number | bigint, op: CmpOp, right: number | bigint, details?: Details): boolean;
35
50
  }
36
51
 
37
- /** One episode of a Liveness property, started at its anchor. */
52
+ /** One episode of a {@link Liveness} property, started by {@link Liveness.begin}. Only its first `done` or `expire` counts. */
38
53
  export declare class Watch {
39
54
  private constructor();
40
55
  /** The condition became true now: ok if within the deadline. Returns whether it was in time. */
@@ -43,35 +58,74 @@ export declare class Watch {
43
58
  expire(details?: Details): void;
44
59
  }
45
60
 
46
- /** A declared bounded-liveness (eventually) property. */
61
+ /** A declared `eventually` property: after an anchor, a condition becomes true within a deadline. */
47
62
  export declare class Liveness {
48
63
  private constructor();
64
+ /** The property's id. */
49
65
  readonly id: string;
66
+ /** The deadline of an episode, in milliseconds after its start. */
50
67
  readonly withinMs: number;
51
68
  /** Starts an episode now (the anchor). */
52
69
  begin(): Watch;
53
- /** Polls cond every pollMs until true or the deadline passed; one record; resolves to the outcome. */
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
+ */
54
76
  awaitCond(cond: () => boolean | Promise<boolean>, pollMs: number, details?: Details): Promise<boolean>;
55
- /** As awaitCond, blocking the thread between evaluations. */
77
+ /** As {@link Liveness.awaitCond}, but blocks the thread between evaluations (`Atomics.wait`). */
56
78
  awaitCondSync(cond: () => boolean, pollMs: number, details?: Details): boolean;
57
79
  }
58
80
 
59
- /** A declared BUGGIFY fault point. */
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
+ */
60
85
  export declare class Point {
61
86
  private constructor();
87
+ /** The point's id (without the `buggify.` prefix of its catalog entry). */
62
88
  readonly id: string;
63
- /** Whether the point misbehaves on this evaluation (always false without a BUGGIFY seed). */
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
+ */
64
94
  fire(details?: Details): boolean;
65
95
  }
66
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
+ */
67
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. */
68
106
  export declare function alwaysOrUnreachable(id: string, msg: string): Assertion;
107
+ /** Declares a property that must be true at least once across an exploration. */
69
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}). */
70
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). */
71
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
+ */
72
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
+ */
73
123
  export declare function buggify(id: string, msg: string): Point;
74
- /** Emits one HYDO-ASSERT-DECL line per declared assertion, in declaration order. */
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
+ */
75
129
  export declare function catalog(): void;
76
- /** Emits HYDO-SETUP-COMPLETE. */
130
+ /** Writes `HYDO-SETUP-COMPLETE`: the system is ready, and hydo may start injecting faults. */
77
131
  export declare function setupComplete(): void;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hydo-assert",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "description": "Assertion SDK for Node.js programs tested under hydo, a deterministic hypervisor: always/sometimes/reachable/unreachable/eventually properties, BUGGIFY fault points and operation histories",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {