hydo-assert 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +234 -2
- package/history.d.mts +4 -0
- package/history.d.ts +56 -0
- package/history.js +268 -0
- package/history.mjs +18 -0
- package/index.d.mts +4 -0
- package/index.d.ts +77 -0
- package/index.js +585 -0
- package/index.mjs +20 -0
- package/package.json +63 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,235 @@
|
|
|
1
|
-
#
|
|
1
|
+
# hydo-assert: the JavaScript assertion SDK (Node.js)
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
10
|
+
|
|
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:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
{ "dependencies": { "hydo-assert": "file:../hydo/sdk/js" } }
|
|
16
|
+
```
|
|
17
|
+
|
|
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
|
+
|
|
21
|
+
## Use
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
const ha = require('hydo-assert'); // or: import * as ha from 'hydo-assert'
|
|
25
|
+
|
|
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
|
|
44
|
+
```
|
|
45
|
+
|
|
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 |
|
|
89
|
+
|---|---|---|
|
|
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`.
|
|
150
|
+
|
|
151
|
+
```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
|
|
162
|
+
}
|
|
163
|
+
kv.invoke(3, 'read', 'k1').ok('k1', hh.valueOrNil(await get('k1'))); // null means absent
|
|
164
|
+
|
|
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'));
|
|
168
|
+
```
|
|
169
|
+
|
|
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.
|
package/history.d.mts
ADDED
package/history.d.ts
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
// Types of hydo-assert/history (CommonJS entry). The wire format and checkers: hydo/HISTORIES.md.
|
|
2
|
+
|
|
3
|
+
/** A record argument: a string that is already one token (see enc), or an integer. */
|
|
4
|
+
export type Token = string | number | bigint;
|
|
5
|
+
|
|
6
|
+
/** The value of an absent key (register model). */
|
|
7
|
+
export declare const NIL: 'nil';
|
|
8
|
+
|
|
9
|
+
/** One named history (a check's `history:`; [A-Za-z0-9_.-]+). */
|
|
10
|
+
export declare class History {
|
|
11
|
+
constructor(name: string);
|
|
12
|
+
readonly name: string;
|
|
13
|
+
/**
|
|
14
|
+
* Records the invocation of f(args...) by process `proc` (an integer, or a token without
|
|
15
|
+
* spaces) and returns the operation. Record it before sending the request.
|
|
16
|
+
*/
|
|
17
|
+
invoke(proc: number | bigint | string, f: string, ...args: Token[]): Op;
|
|
18
|
+
/** Writes one raw record (`type` is invoke, ok, fail or info). */
|
|
19
|
+
record(proc: number | bigint | string, type: 'invoke' | 'ok' | 'fail' | 'info' | string, f: string, ...args: Token[]): void;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** An invoked operation waiting for its completion. */
|
|
23
|
+
export declare class Op {
|
|
24
|
+
private constructor();
|
|
25
|
+
readonly history: History;
|
|
26
|
+
readonly proc: string;
|
|
27
|
+
readonly f: string;
|
|
28
|
+
readonly args: string[];
|
|
29
|
+
/** A successful completion; with no args the invocation's are repeated. */
|
|
30
|
+
ok(...args: Token[]): void;
|
|
31
|
+
/** The operation definitely had no effect. */
|
|
32
|
+
fail(): void;
|
|
33
|
+
/** The outcome is unknown (a timeout, a lost connection). */
|
|
34
|
+
info(): void;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** new History(name). */
|
|
38
|
+
export declare function history(name: string): History;
|
|
39
|
+
|
|
40
|
+
/** One token from a value: Go's hydohist.Enc on the UTF-8 bytes. */
|
|
41
|
+
export declare function enc(v: string | number | bigint): string;
|
|
42
|
+
/** "enc(v)@version" (version: an int64). */
|
|
43
|
+
export declare function ver(v: string | number | bigint, version: number | bigint): string;
|
|
44
|
+
/**
|
|
45
|
+
* enc(v) if present, else NIL. With one argument, null and undefined are absent; with two, the
|
|
46
|
+
* second says whether the value is present (Go's ValOrNil(v, ok)).
|
|
47
|
+
*/
|
|
48
|
+
export declare function valueOrNil(v: string | number | bigint | null | undefined, ok?: boolean): string;
|
|
49
|
+
/** "[e1,e2,...]" with each element encoded. */
|
|
50
|
+
export declare function list(...elems: Array<string | number | bigint>): string;
|
|
51
|
+
/** The txn micro-op "a:<k>:<e>". */
|
|
52
|
+
export declare function append(k: string | number | bigint, e: string | number | bigint): string;
|
|
53
|
+
/** The txn micro-op "r:<k>" (invocation). */
|
|
54
|
+
export declare function read(k: string | number | bigint): string;
|
|
55
|
+
/** The txn micro-op "r:<k>:[...]" (completion). */
|
|
56
|
+
export declare function readResult(k: string | number | bigint, ...l: Array<string | number | bigint>): string;
|