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.
- package/README.md +231 -217
- package/history.d.ts +12 -2
- package/index.d.ts +67 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,235 +1,249 @@
|
|
|
1
|
-
# hydo-assert
|
|
1
|
+
# hydo-assert for JavaScript (Node.js)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
|
12
|
-
|
|
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
|
-
|
|
15
|
-
|
|
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`
|
|
19
|
-
|
|
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
|
-
|
|
26
|
+
A small key/value store that declares three properties and checks them:
|
|
22
27
|
|
|
23
28
|
```js
|
|
24
|
-
const ha = require('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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
|
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
|
-
|
|
|
91
|
-
|
|
|
92
|
-
| `
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
the
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
`
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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
|
|
153
|
-
|
|
154
|
-
const
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
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
|
-
|
|
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
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
-
|
|
190
|
-
(
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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:
|
|
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
|
-
/**
|
|
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:
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
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,
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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.
|
|
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": {
|