merkle_machines 0.6.3
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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +91 -0
- data/Cargo.lock +314 -0
- data/Cargo.toml +28 -0
- data/LICENSE.txt +21 -0
- data/README.md +326 -0
- data/ext/merkle_machines_native/core/CHANGELOG.md +66 -0
- data/ext/merkle_machines_native/core/Cargo.toml +20 -0
- data/ext/merkle_machines_native/core/README.md +114 -0
- data/ext/merkle_machines_native/core/src/lib.rs +16 -0
- data/ext/merkle_machines_native/core/src/refusal.rs +54 -0
- data/ext/merkle_machines_native/core/src/request.rs +60 -0
- data/ext/merkle_machines_native/core/src/schema.rs +193 -0
- data/ext/merkle_machines_native/core/src/survey/buffer.rs +61 -0
- data/ext/merkle_machines_native/core/src/survey.rs +552 -0
- data/ext/merkle_machines_native/extconf.rb +2 -0
- data/ext/merkle_machines_native/ffi/Cargo.toml +21 -0
- data/ext/merkle_machines_native/ffi/extconf.rb +14 -0
- data/ext/merkle_machines_native/ffi/src/init.rs +50 -0
- data/ext/merkle_machines_native/ffi/src/lib.rs +453 -0
- data/ext/merkle_machines_native/ffi/src/values.rs +47 -0
- data/lib/merkle_machines/survey.rb +43 -0
- data/lib/merkle_machines/values.rb +63 -0
- data/lib/merkle_machines/version.rb +5 -0
- data/lib/merkle_machines.rb +8 -0
- data/sig/merkle_machines.rbs +142 -0
- metadata +92 -0
|
@@ -0,0 +1,453 @@
|
|
|
1
|
+
//! Thin binding to the bounded digest-tree survey.
|
|
2
|
+
mod init;
|
|
3
|
+
mod values;
|
|
4
|
+
|
|
5
|
+
use values::{build, classes};
|
|
6
|
+
|
|
7
|
+
use std::{cell::RefCell, cmp::Ordering};
|
|
8
|
+
|
|
9
|
+
use magnus::{Error, RArray, RString, Range, Ruby, Symbol, Value, prelude::*, typed_data::Obj};
|
|
10
|
+
use matryona_machines::ruby::{
|
|
11
|
+
SymbolNames, Symbols, exact_array, exact_fields, exact_string, integer, keep, symbol,
|
|
12
|
+
};
|
|
13
|
+
use merkle_machines::{
|
|
14
|
+
Aborting, Begun, LeafRange, Mismatch, Node, Phase, Refusal, Request, Schema, Versions,
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
const PENDING_CAPACITY: usize = 64;
|
|
18
|
+
const OUTPUT_CAPACITY: usize = 64;
|
|
19
|
+
const MAX_FANOUT: u8 = merkle_machines::MAX_FANOUT;
|
|
20
|
+
|
|
21
|
+
/// A caller-supplied digest: a Ruby String compared byte for byte.
|
|
22
|
+
#[derive(Clone, Copy)]
|
|
23
|
+
struct Digest(RString);
|
|
24
|
+
|
|
25
|
+
impl Digest {
|
|
26
|
+
/// `value` as a digest: exactly a String, no subclass and no `to_str`;
|
|
27
|
+
/// `TypeError` `"<name> must be a String"` otherwise.
|
|
28
|
+
fn read(ruby: &Ruby, value: Value, name: &str) -> Result<Self, Error> {
|
|
29
|
+
exact_string(ruby, value, name).map(Self)
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
impl PartialEq for Digest {
|
|
34
|
+
fn eq(&self, other: &Self) -> bool {
|
|
35
|
+
self.0.cmp(other.0) == Ordering::Equal
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/// Read natively from exactly an `Array`: a subclass is a `TypeError`.
|
|
40
|
+
fn digests(ruby: &Ruby, list: Value) -> Result<Vec<Digest>, Error> {
|
|
41
|
+
let list = exact_array(ruby, list, "expected an Array of String digests")?;
|
|
42
|
+
list.into_iter()
|
|
43
|
+
.map(|digest| Digest::read(ruby, digest, "digest"))
|
|
44
|
+
.collect()
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
matryona_machines::symbols! {
|
|
48
|
+
/// One symbol per `Mismatch`, shared by `Schema#compatible` and
|
|
49
|
+
/// `Survey#begin`.
|
|
50
|
+
Mismatches for Mismatch as "a schema mismatch" {
|
|
51
|
+
Fanout => "fanout_mismatch",
|
|
52
|
+
Depth => "depth_mismatch",
|
|
53
|
+
Partitioning => "partitioning_mismatch",
|
|
54
|
+
Digest => "digest_mismatch",
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
matryona_machines::symbols! {
|
|
59
|
+
/// One symbol per `Refusal`. `Schema` carries the field the schemas
|
|
60
|
+
/// disagree on and leaves as that field's own symbol, through
|
|
61
|
+
/// `Mismatches`.
|
|
62
|
+
Refusals for Refusal as "a refusal" => names_only {
|
|
63
|
+
Schema(reason) => use Mismatches,
|
|
64
|
+
Undersized => "undersized",
|
|
65
|
+
Busy => "busy",
|
|
66
|
+
Exhausted => "exhausted",
|
|
67
|
+
Stale => "stale",
|
|
68
|
+
Unexpected => "unexpected",
|
|
69
|
+
VersionChanged => "version_changed",
|
|
70
|
+
Arity => "arity",
|
|
71
|
+
Inconsistent => "inconsistent",
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/// The refusal's symbol name.
|
|
76
|
+
fn refusal(refused: Refusal) -> &'static str {
|
|
77
|
+
Refusals::name(&refused)
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/// A `MerkleMachines::Schema`, as it arrives.
|
|
81
|
+
type Shape = Value;
|
|
82
|
+
|
|
83
|
+
/// A schema's fields as the core's types.
|
|
84
|
+
type Fields = (u8, u8, u64, u64);
|
|
85
|
+
|
|
86
|
+
/// Reads every field of `shape`, exactly a `Schema`, from the struct; the
|
|
87
|
+
/// core's `Schema::new` checks them after.
|
|
88
|
+
fn shape_of(ruby: &Ruby, shape: Shape) -> Result<Fields, Error> {
|
|
89
|
+
let class = classes(ruby)?.schema.get(ruby);
|
|
90
|
+
let [fanout, depth, partitioning, digest] =
|
|
91
|
+
exact_fields(ruby, shape, class, "expected a MerkleMachines::Schema")?;
|
|
92
|
+
fields_of(fanout, depth, partitioning, digest)
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
fn fields_of(
|
|
96
|
+
fanout: Value,
|
|
97
|
+
depth: Value,
|
|
98
|
+
partitioning: Value,
|
|
99
|
+
digest: Value,
|
|
100
|
+
) -> Result<Fields, Error> {
|
|
101
|
+
Ok((
|
|
102
|
+
integer(fanout, "fanout")?,
|
|
103
|
+
integer(depth, "depth")?,
|
|
104
|
+
integer(partitioning, "partitioning")?,
|
|
105
|
+
integer(digest, "digest")?,
|
|
106
|
+
))
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const INVALID_SCHEMA: &str =
|
|
110
|
+
"fanout must be in 2..=MAX_FANOUT and fanout**depth must fit in 64 bits";
|
|
111
|
+
|
|
112
|
+
/// The core's `Schema::new`, which Ruby's `Schema.new` answers for: a shape
|
|
113
|
+
/// the core has no value for is malformed input, not a refusal.
|
|
114
|
+
fn schema(ruby: &Ruby, (fanout, depth, partitioning, digest): Fields) -> Result<Schema, Error> {
|
|
115
|
+
Schema::new(fanout, depth, partitioning, digest)
|
|
116
|
+
.ok_or_else(|| Error::new(ruby.exception_range_error(), INVALID_SCHEMA))
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/// Raises exactly when the core cannot build this schema.
|
|
120
|
+
fn check_schema(
|
|
121
|
+
ruby: &Ruby,
|
|
122
|
+
fanout: Value,
|
|
123
|
+
depth: Value,
|
|
124
|
+
partitioning: Value,
|
|
125
|
+
digest: Value,
|
|
126
|
+
) -> Result<(), Error> {
|
|
127
|
+
let shape = fields_of(fanout, depth, partitioning, digest)?;
|
|
128
|
+
schema(ruby, shape).map(drop)
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
fn schema_leaves(ruby: &Ruby, shape: Shape) -> Result<u64, Error> {
|
|
132
|
+
Ok(schema(ruby, shape_of(ruby, shape)?)?.leaves())
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
fn schema_width(ruby: &Ruby, shape: Shape, level: Value) -> Result<u64, Error> {
|
|
136
|
+
let (shape, level) = (shape_of(ruby, shape)?, integer(level, "level")?);
|
|
137
|
+
Ok(schema(ruby, shape)?.width(level))
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
fn schema_span(ruby: &Ruby, shape: Shape, node: Place) -> Result<Option<Range>, Error> {
|
|
141
|
+
let (shape, node) = (shape_of(ruby, shape)?, self::node(ruby, node)?);
|
|
142
|
+
schema(ruby, shape)?
|
|
143
|
+
.span(node)
|
|
144
|
+
.map(|span| leaves(ruby, span))
|
|
145
|
+
.transpose()
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
fn schema_compatible(ruby: &Ruby, shape: Shape, other: Shape) -> Result<Symbol, Error> {
|
|
149
|
+
let (shape, other) = (shape_of(ruby, shape)?, shape_of(ruby, other)?);
|
|
150
|
+
let compatible = schema(ruby, shape)?.compatible(&schema(ruby, other)?);
|
|
151
|
+
Ok(symbol(
|
|
152
|
+
ruby,
|
|
153
|
+
match compatible {
|
|
154
|
+
Ok(()) => "compatible",
|
|
155
|
+
Err(reason) => Mismatches::name(reason),
|
|
156
|
+
},
|
|
157
|
+
))
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/// A leaf range as the half-open Ruby `Range` `start...end`.
|
|
161
|
+
fn leaves(ruby: &Ruby, range: LeafRange) -> Result<Range, Error> {
|
|
162
|
+
ruby.range_new(range.start(), range.end(), true)
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/// A `MerkleMachines::Node`, as it arrives.
|
|
166
|
+
type Place = Value;
|
|
167
|
+
/// A `MerkleMachines::Versions`, as it arrives.
|
|
168
|
+
type Pins = Value;
|
|
169
|
+
/// A `MerkleMachines::Request`, as it arrives.
|
|
170
|
+
type Ticket = Value;
|
|
171
|
+
|
|
172
|
+
fn versions(ruby: &Ruby, pins: Pins) -> Result<Versions, Error> {
|
|
173
|
+
let class = classes(ruby)?.versions.get(ruby);
|
|
174
|
+
let [local, remote] = exact_fields(ruby, pins, class, "expected a MerkleMachines::Versions")?;
|
|
175
|
+
versions_of(local, remote)
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
fn versions_of(local: Value, remote: Value) -> Result<Versions, Error> {
|
|
179
|
+
Ok(Versions {
|
|
180
|
+
local: integer(local, "local")?,
|
|
181
|
+
remote: integer(remote, "remote")?,
|
|
182
|
+
})
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
fn node(ruby: &Ruby, place: Place) -> Result<Node, Error> {
|
|
186
|
+
let class = classes(ruby)?.node.get(ruby);
|
|
187
|
+
let [level, index] = exact_fields(ruby, place, class, "expected a MerkleMachines::Node")?;
|
|
188
|
+
node_of(level, index)
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
fn node_of(level: Value, index: Value) -> Result<Node, Error> {
|
|
192
|
+
Ok(Node {
|
|
193
|
+
level: integer(level, "level")?,
|
|
194
|
+
index: integer(index, "index")?,
|
|
195
|
+
})
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/// A request's session and node, read before the core is asked for it.
|
|
199
|
+
fn ticket(ruby: &Ruby, ticket: Ticket) -> Result<(u64, Node), Error> {
|
|
200
|
+
let class = classes(ruby)?.request.get(ruby);
|
|
201
|
+
let [session, node] = exact_fields(ruby, ticket, class, "expected a MerkleMachines::Request")?;
|
|
202
|
+
ticket_of(ruby, session, node)
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
fn ticket_of(ruby: &Ruby, session: Value, node: Place) -> Result<(u64, Node), Error> {
|
|
206
|
+
Ok((integer(session, "session")?, self::node(ruby, node)?))
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/// The core's `Request::new`: a session of sequence zero names no session, so
|
|
210
|
+
/// no request exists for it.
|
|
211
|
+
fn request(ruby: &Ruby, (session, node): (u64, Node)) -> Result<Request, Error> {
|
|
212
|
+
Request::new(session, node).ok_or_else(|| {
|
|
213
|
+
Error::new(
|
|
214
|
+
ruby.exception_range_error(),
|
|
215
|
+
"session has sequence number zero, which no survey issues",
|
|
216
|
+
)
|
|
217
|
+
})
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/// `Node.new`: every field converts to the core's type or raises.
|
|
221
|
+
fn check_node(level: Value, index: Value) -> Result<(), Error> {
|
|
222
|
+
node_of(level, index).map(drop)
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/// `Versions.new`: every field converts to the core's type or raises.
|
|
226
|
+
fn check_versions(local: Value, remote: Value) -> Result<(), Error> {
|
|
227
|
+
versions_of(local, remote).map(drop)
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/// `Request.new`: raises exactly when the core has no request for it, or
|
|
231
|
+
/// `node` is not exactly a `Node`.
|
|
232
|
+
fn check_request(ruby: &Ruby, session: Value, node: Place) -> Result<(), Error> {
|
|
233
|
+
request(ruby, ticket_of(ruby, session, node)?).map(drop)
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/// `Request#scope`: the core's `Request::scope`, so the id layout stays the
|
|
237
|
+
/// core's business. The request is read natively, exactly a `Request` with
|
|
238
|
+
/// its fields from the struct and checked again, never through a reader.
|
|
239
|
+
fn request_scope(ruby: &Ruby, value: Ticket) -> Result<u16, Error> {
|
|
240
|
+
Ok(request(ruby, ticket(ruby, value)?)?.scope())
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
type Core = merkle_machines::Survey<PENDING_CAPACITY, OUTPUT_CAPACITY>;
|
|
244
|
+
|
|
245
|
+
#[magnus::wrap(class = "MerkleMachines::Survey", free_immediately, size)]
|
|
246
|
+
struct Survey {
|
|
247
|
+
core: RefCell<Core>,
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
impl Survey {
|
|
251
|
+
const fn new() -> Self {
|
|
252
|
+
Self {
|
|
253
|
+
core: RefCell::new(merkle_machines::Survey::new()),
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
fn with_scope(scope: Value) -> Result<Self, Error> {
|
|
258
|
+
Ok(Self {
|
|
259
|
+
core: RefCell::new(merkle_machines::Survey::with_scope(integer(
|
|
260
|
+
scope, "scope",
|
|
261
|
+
)?)),
|
|
262
|
+
})
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
fn resumed(ruby: &Ruby, scope: Value, issued: Value) -> Result<Self, Error> {
|
|
266
|
+
let (scope, issued) = (integer(scope, "scope")?, integer(issued, "issued")?);
|
|
267
|
+
let core = merkle_machines::Survey::resumed(scope, issued).ok_or_else(|| {
|
|
268
|
+
Error::new(
|
|
269
|
+
ruby.exception_range_error(),
|
|
270
|
+
"issued is past the last sequence of a scope (2**48 - 1)",
|
|
271
|
+
)
|
|
272
|
+
})?;
|
|
273
|
+
Ok(Self {
|
|
274
|
+
core: RefCell::new(core),
|
|
275
|
+
})
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
fn scope(&self) -> u16 {
|
|
279
|
+
self.core.borrow().scope()
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
fn issued(&self) -> u64 {
|
|
283
|
+
self.core.borrow().issued()
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
fn begin(
|
|
287
|
+
ruby: &Ruby,
|
|
288
|
+
this: Obj<Self>,
|
|
289
|
+
local: Shape,
|
|
290
|
+
remote: Shape,
|
|
291
|
+
pins: Pins,
|
|
292
|
+
local_root: Value,
|
|
293
|
+
remote_root: Value,
|
|
294
|
+
) -> Result<Symbol, Error> {
|
|
295
|
+
this.check_frozen()?;
|
|
296
|
+
let (local, remote) = (shape_of(ruby, local)?, shape_of(ruby, remote)?);
|
|
297
|
+
let pins = versions(ruby, pins)?;
|
|
298
|
+
let local_root = Digest::read(ruby, local_root, "local_root")?;
|
|
299
|
+
let remote_root = Digest::read(ruby, remote_root, "remote_root")?;
|
|
300
|
+
let (local, remote) = (schema(ruby, local)?, schema(ruby, remote)?);
|
|
301
|
+
let begun = this
|
|
302
|
+
.core
|
|
303
|
+
.borrow_mut()
|
|
304
|
+
.begin(local, remote, pins, &local_root, &remote_root);
|
|
305
|
+
Ok(symbol(
|
|
306
|
+
ruby,
|
|
307
|
+
match begun {
|
|
308
|
+
Ok(Begun::Identical) => "identical",
|
|
309
|
+
Ok(Begun::Diverged) => "diverged",
|
|
310
|
+
Err(refused) => refusal(refused),
|
|
311
|
+
},
|
|
312
|
+
))
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/// Decided on a copy, kept once the `Request` is built (see [`keep`]).
|
|
316
|
+
fn next_request(ruby: &Ruby, this: Obj<Self>) -> Result<Option<Value>, Error> {
|
|
317
|
+
let classes = classes(ruby)?;
|
|
318
|
+
keep(ruby, this, &this.core, Core::next_request, |request| {
|
|
319
|
+
let Some(request) = request else {
|
|
320
|
+
return Ok(None);
|
|
321
|
+
};
|
|
322
|
+
let Node { level, index } = request.node();
|
|
323
|
+
let node = build(
|
|
324
|
+
classes.node.get(ruby),
|
|
325
|
+
[
|
|
326
|
+
ruby.integer_from_u64(level.into()).as_value(),
|
|
327
|
+
ruby.integer_from_u64(index).as_value(),
|
|
328
|
+
],
|
|
329
|
+
)?;
|
|
330
|
+
let session = ruby.integer_from_u64(request.session()).as_value();
|
|
331
|
+
build(classes.request.get(ruby), [session, node]).map(Some)
|
|
332
|
+
})
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
fn answer(
|
|
336
|
+
ruby: &Ruby,
|
|
337
|
+
this: Obj<Self>,
|
|
338
|
+
ticket: Ticket,
|
|
339
|
+
pins: Pins,
|
|
340
|
+
local: Value,
|
|
341
|
+
remote: Value,
|
|
342
|
+
) -> Result<Symbol, Error> {
|
|
343
|
+
this.check_frozen()?;
|
|
344
|
+
let (ticket, pins) = (self::ticket(ruby, ticket)?, versions(ruby, pins)?);
|
|
345
|
+
let request = request(ruby, ticket)?;
|
|
346
|
+
let (local, remote) = (digests(ruby, local)?, digests(ruby, remote)?);
|
|
347
|
+
let answered = this
|
|
348
|
+
.core
|
|
349
|
+
.borrow_mut()
|
|
350
|
+
.answer(request, pins, &local, &remote);
|
|
351
|
+
Ok(symbol(ruby, answered.map_or_else(refusal, |()| "accepted")))
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
fn requeue(ruby: &Ruby, this: Obj<Self>, ticket: Ticket) -> Result<Symbol, Error> {
|
|
355
|
+
this.check_frozen()?;
|
|
356
|
+
let ticket = self::ticket(ruby, ticket)?;
|
|
357
|
+
let request = request(ruby, ticket)?;
|
|
358
|
+
let requeued = this.core.borrow_mut().requeue(request);
|
|
359
|
+
Ok(symbol(ruby, requeued.map_or_else(refusal, |()| "requeued")))
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
fn pop_range(ruby: &Ruby, this: Obj<Self>) -> Result<Option<Range>, Error> {
|
|
363
|
+
keep(ruby, this, &this.core, Core::pop_range, |range| {
|
|
364
|
+
range.map(|range| leaves(ruby, range)).transpose()
|
|
365
|
+
})
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/// The survey never buffers more than `OUTPUT_CAPACITY` ranges, so a
|
|
369
|
+
/// larger limit takes everything and loses nothing. The ranges are read
|
|
370
|
+
/// into a buffer on the copy, then built, inside one [`keep`].
|
|
371
|
+
fn drain(ruby: &Ruby, this: Obj<Self>, limit: Value) -> Result<RArray, Error> {
|
|
372
|
+
this.check_frozen()?;
|
|
373
|
+
let limit: u64 = integer(limit, "limit")?;
|
|
374
|
+
let limit = usize::try_from(limit).map_or(OUTPUT_CAPACITY, |n| n.min(OUTPUT_CAPACITY));
|
|
375
|
+
keep(
|
|
376
|
+
ruby,
|
|
377
|
+
this,
|
|
378
|
+
&this.core,
|
|
379
|
+
|core| {
|
|
380
|
+
let mut taken = [LeafRange::default(); OUTPUT_CAPACITY];
|
|
381
|
+
let count = core.drain(&mut taken[..limit]);
|
|
382
|
+
(taken, count)
|
|
383
|
+
},
|
|
384
|
+
|(taken, count)| {
|
|
385
|
+
let ranges = ruby.ary_new_capa(count);
|
|
386
|
+
for &range in &taken[..count] {
|
|
387
|
+
ranges.push(leaves(ruby, range)?)?;
|
|
388
|
+
}
|
|
389
|
+
Ok(ranges)
|
|
390
|
+
},
|
|
391
|
+
)
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
fn requeue_all(this: Obj<Self>) -> Result<usize, Error> {
|
|
395
|
+
this.check_frozen()?;
|
|
396
|
+
Ok(this.core.borrow_mut().requeue_all())
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
fn abort(ruby: &Ruby, this: Obj<Self>) -> Result<Symbol, Error> {
|
|
400
|
+
this.check_frozen()?;
|
|
401
|
+
let aborting = this.core.borrow_mut().abort();
|
|
402
|
+
Ok(symbol(
|
|
403
|
+
ruby,
|
|
404
|
+
match aborting {
|
|
405
|
+
Aborting::Aborted => "aborted",
|
|
406
|
+
Aborting::AlreadyIdle => "already_idle",
|
|
407
|
+
},
|
|
408
|
+
))
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
fn phase(ruby: &Ruby, this: &Self) -> Symbol {
|
|
412
|
+
symbol(
|
|
413
|
+
ruby,
|
|
414
|
+
match this.core.borrow().phase() {
|
|
415
|
+
Phase::Idle => "idle",
|
|
416
|
+
Phase::Surveying => "surveying",
|
|
417
|
+
Phase::Draining => "draining",
|
|
418
|
+
Phase::Complete => "complete",
|
|
419
|
+
},
|
|
420
|
+
)
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
fn session(&self) -> Option<u64> {
|
|
424
|
+
self.core.borrow().session()
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
fn schema(&self) -> Option<(u8, u8, u64, u64)> {
|
|
428
|
+
let schema = self.core.borrow().schema()?;
|
|
429
|
+
Some((
|
|
430
|
+
schema.fanout(),
|
|
431
|
+
schema.depth(),
|
|
432
|
+
schema.partitioning(),
|
|
433
|
+
schema.digest(),
|
|
434
|
+
))
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
fn versions(&self) -> Option<(u64, u64)> {
|
|
438
|
+
let versions = self.core.borrow().versions()?;
|
|
439
|
+
Some((versions.local, versions.remote))
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
fn pending(&self) -> usize {
|
|
443
|
+
self.core.borrow().pending()
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
fn in_flight(&self) -> usize {
|
|
447
|
+
self.core.borrow().in_flight()
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
fn buffered(&self) -> usize {
|
|
451
|
+
self.core.borrow().buffered()
|
|
452
|
+
}
|
|
453
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
//! The value classes the binding reads and builds, resolved once at init.
|
|
2
|
+
//!
|
|
3
|
+
//! `lib/merkle_machines/values.rb` defines `Node`, `Schema`, `Versions` and
|
|
4
|
+
//! `Request` before this extension loads. Sealing them stops accidents, not
|
|
5
|
+
//! reflection, so the binding is the authority on what Ruby hands in: an
|
|
6
|
+
//! instance of exactly the class asked for, whose members are read straight
|
|
7
|
+
//! from the `Data` struct with `exact_fields` (no reader runs) and then
|
|
8
|
+
//! checked again by the core constructor at each use.
|
|
9
|
+
|
|
10
|
+
use magnus::{Error, RClass, RModule, RStruct, Ruby, Value, prelude::*};
|
|
11
|
+
use matryona_machines::ruby::Class;
|
|
12
|
+
|
|
13
|
+
/// The classes as resolved at init.
|
|
14
|
+
pub struct Classes {
|
|
15
|
+
pub node: Class,
|
|
16
|
+
pub schema: Class,
|
|
17
|
+
pub versions: Class,
|
|
18
|
+
pub request: Class,
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
matryona_machines::registry! {
|
|
22
|
+
static CLASSES: Classes = "merkle_machines";
|
|
23
|
+
pub fn classes;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
pub fn resolve(ruby: &Ruby, module: RModule) -> Result<(), Error> {
|
|
27
|
+
let class = |name| Class::resolve(ruby, module, name);
|
|
28
|
+
let classes = Classes {
|
|
29
|
+
node: class("Node")?,
|
|
30
|
+
schema: class("Schema")?,
|
|
31
|
+
versions: class("Versions")?,
|
|
32
|
+
request: class("Request")?,
|
|
33
|
+
};
|
|
34
|
+
CLASSES.set(ruby, classes).map(drop)
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/// A frozen instance of the `Data` class `class` holding `members`, in order.
|
|
38
|
+
/// Runs no Ruby code (no `new`, no `initialize`): the members come from the
|
|
39
|
+
/// core, which only holds valid values.
|
|
40
|
+
pub fn build<const N: usize>(class: RClass, members: [Value; N]) -> Result<Value, Error> {
|
|
41
|
+
let instance = RStruct::try_convert(class.obj_alloc()?)?;
|
|
42
|
+
for (index, member) in members.into_iter().enumerate() {
|
|
43
|
+
instance.aset(index, member)?;
|
|
44
|
+
}
|
|
45
|
+
instance.freeze();
|
|
46
|
+
Ok(instance.as_value())
|
|
47
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module MerkleMachines
|
|
4
|
+
private_class_method :check_schema, :check_node, :check_versions, :check_request, :schema_leaves,
|
|
5
|
+
:schema_width, :schema_span, :schema_compatible, :request_scope
|
|
6
|
+
|
|
7
|
+
# The root of every tree.
|
|
8
|
+
Node::ROOT = Node.new(0, 0)
|
|
9
|
+
|
|
10
|
+
# The values are sealed. `initialize` is where each validates, and a
|
|
11
|
+
# subclass could override it, or `allocate` build an instance that never ran
|
|
12
|
+
# it: subclassing raises TypeError and `allocate` is gone. Sealing stops
|
|
13
|
+
# accidents, not reflection (a named subclass's constant is bound before
|
|
14
|
+
# `inherited` raises; `Marshal.load` skips `initialize`), so the binding is
|
|
15
|
+
# the authority: it takes an instance of exactly the class asked for, reads
|
|
16
|
+
# its fields from the struct (no reader runs) and the core's constructors
|
|
17
|
+
# check every field again.
|
|
18
|
+
[Node, Schema, Versions, Request].each do |value|
|
|
19
|
+
value.singleton_class.undef_method(:allocate)
|
|
20
|
+
value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
# Value objects around the native survey. The traversal itself is native,
|
|
24
|
+
# and so is every value a mutating call returns (`next_request`, `pop_range`,
|
|
25
|
+
# `drain`), built from a copy of the survey that is kept only once the answer
|
|
26
|
+
# exists: frozen meanwhile is FrozenError, changed meanwhile RuntimeError,
|
|
27
|
+
# and in both cases nothing is applied. Each mutating call (`begin`,
|
|
28
|
+
# `answer`, `requeue`, ...) is native and raises FrozenError on a frozen
|
|
29
|
+
# survey before any argument is read.
|
|
30
|
+
class Survey
|
|
31
|
+
# The schema of the open session, nil when the survey is idle.
|
|
32
|
+
def schema
|
|
33
|
+
shape = native_schema
|
|
34
|
+
shape && Schema.new(*shape)
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
# The versions the open session pinned, nil when the survey is idle.
|
|
38
|
+
def versions
|
|
39
|
+
pins = native_versions
|
|
40
|
+
pins && Versions.new(*pins)
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
end
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module MerkleMachines
|
|
4
|
+
# The value classes are defined before the native extension loads, so it
|
|
5
|
+
# resolves each one once, at init. Each `initialize` calls a private native
|
|
6
|
+
# hook that holds the value to the core's constructor.
|
|
7
|
+
|
|
8
|
+
# Address of a tree node: `level` 0 is the root, `index` counts left to right
|
|
9
|
+
# within the level. `level` is an Integer in 0..255, `index` in 0...2**64.
|
|
10
|
+
Node = Data.define(:level, :index) do
|
|
11
|
+
def initialize(level:, index:)
|
|
12
|
+
MerkleMachines.__send__(:check_node, level, index)
|
|
13
|
+
super
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
# Shape and identity of a fixed-depth digest tree. Two trees are comparable
|
|
17
|
+
# only when all four fields are equal. A shape the core has no schema for
|
|
18
|
+
# raises: `fanout` outside 2..MAX_FANOUT, or more leaves than fit in 64 bits.
|
|
19
|
+
Schema = Data.define(:fanout, :depth, :partitioning, :digest) do
|
|
20
|
+
def initialize(fanout:, depth:, partitioning:, digest:)
|
|
21
|
+
MerkleMachines.__send__(:check_schema, fanout, depth, partitioning, digest)
|
|
22
|
+
super
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
# Total number of leaves.
|
|
26
|
+
def leaves = MerkleMachines.__send__(:schema_leaves, self)
|
|
27
|
+
|
|
28
|
+
# Number of nodes at `level`, saturating past the leaf level.
|
|
29
|
+
def width(level) = MerkleMachines.__send__(:schema_width, self, level)
|
|
30
|
+
|
|
31
|
+
# Leaves below `node` as a half-open Range, nil when the node is not part
|
|
32
|
+
# of the tree.
|
|
33
|
+
def span(node) = MerkleMachines.__send__(:schema_span, self, node)
|
|
34
|
+
|
|
35
|
+
# :compatible, or the first field on which `other` differs:
|
|
36
|
+
# :fanout_mismatch, :depth_mismatch, :partitioning_mismatch, :digest_mismatch.
|
|
37
|
+
def compatible(other) = MerkleMachines.__send__(:schema_compatible, self, other)
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# Tree versions every digest of one session must be read from: Integers in
|
|
41
|
+
# 0...2**64.
|
|
42
|
+
Versions = Data.define(:local, :remote) do
|
|
43
|
+
def initialize(local:, remote:)
|
|
44
|
+
MerkleMachines.__send__(:check_versions, local, remote)
|
|
45
|
+
super
|
|
46
|
+
end
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# A request for the child digests of one node, on both trees. `session` is
|
|
50
|
+
# the scoped id of the session it belongs to; only the survey that issued it
|
|
51
|
+
# honours the request. A session of sequence number zero names no session
|
|
52
|
+
# and raises RangeError.
|
|
53
|
+
Request = Data.define(:session, :node) do
|
|
54
|
+
def initialize(session:, node:)
|
|
55
|
+
MerkleMachines.__send__(:check_request, session, node)
|
|
56
|
+
super
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
# The scope of the survey that issued the request's session.
|
|
60
|
+
# Read natively from the struct, never through the readers.
|
|
61
|
+
def scope = MerkleMachines.__send__(:request_scope, self)
|
|
62
|
+
end
|
|
63
|
+
end
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative 'merkle_machines/version'
|
|
4
|
+
require_relative 'merkle_machines/values'
|
|
5
|
+
# Native is required: no algorithm fallback. It resolves the value classes
|
|
6
|
+
# above once, at init.
|
|
7
|
+
require 'merkle_machines_native/merkle_machines_native'
|
|
8
|
+
require_relative 'merkle_machines/survey'
|