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.
@@ -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,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module MerkleMachines
4
+ VERSION = '0.6.3'
5
+ 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'