merge_machines 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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +57 -0
- data/Cargo.lock +294 -0
- data/Cargo.toml +24 -0
- data/LICENSE.txt +21 -0
- data/README.md +252 -0
- data/ext/merge_machines_native/core/Cargo.toml +24 -0
- data/ext/merge_machines_native/core/src/gcounter.rs +242 -0
- data/ext/merge_machines_native/core/src/gset.rs +181 -0
- data/ext/merge_machines_native/core/src/hybrid.rs +222 -0
- data/ext/merge_machines_native/core/src/lib.rs +221 -0
- data/ext/merge_machines_native/core/src/logical.rs +139 -0
- data/ext/merge_machines_native/core/src/lww.rs +213 -0
- data/ext/merge_machines_native/core/src/orset.rs +334 -0
- data/ext/merge_machines_native/core/src/pncounter.rs +165 -0
- data/ext/merge_machines_native/extconf.rb +3 -0
- data/ext/merge_machines_native/ffi/Cargo.toml +20 -0
- data/ext/merge_machines_native/ffi/extconf.rb +21 -0
- data/ext/merge_machines_native/ffi/src/data.rs +44 -0
- data/ext/merge_machines_native/ffi/src/gcounter.rs +138 -0
- data/ext/merge_machines_native/ffi/src/gset.rs +187 -0
- data/ext/merge_machines_native/ffi/src/hash.rs +33 -0
- data/ext/merge_machines_native/ffi/src/hybrid.rs +110 -0
- data/ext/merge_machines_native/ffi/src/lib.rs +221 -0
- data/ext/merge_machines_native/ffi/src/logical.rs +89 -0
- data/ext/merge_machines_native/ffi/src/lww.rs +360 -0
- data/ext/merge_machines_native/ffi/src/names.rs +82 -0
- data/ext/merge_machines_native/ffi/src/orset.rs +240 -0
- data/ext/merge_machines_native/ffi/src/pncounter.rs +143 -0
- data/ext/merge_machines_native/ffi/src/shape.rs +116 -0
- data/ext/merge_machines_native/ffi/src/wall.rs +37 -0
- data/lib/merge_machines/version.rb +5 -0
- data/lib/merge_machines.rb +8 -0
- data/sig/merge_machines.rbs +238 -0
- metadata +98 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: a2f915c48b47912abc9c26b6e49031ac3ac667ac691c91bc7868ed2006d1c15b
|
|
4
|
+
data.tar.gz: bf52d7d950ed8a1ce47b7eea6de39b62c86e635570c36daa985fad182929328f
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: c251d58a14280b892c7d971ef846a5d60a7f0164fdc3d81eba6d98507894dac6c5078517ad4ff322a496a8c848fee767afb18ac4439c0db9cf6907c275fc31aa
|
|
7
|
+
data.tar.gz: 06caf6e3d8420d4bd412a682f0abc3167e9d1e0f630e8fd5656d96242da62ae09533b05744a983e7a12f2c787bc0ce52db296344ac62269506817da78cbdb5d3
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.2.0](https://github.com/seuros/merge_machines/compare/merge_machines-v0.1.0...merge_machines/v0.2.0) (2026-11-01)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ⚠ BREAKING CHANGES
|
|
7
|
+
|
|
8
|
+
* hybrid timestamps cross the boundary as nanoseconds, not Float seconds
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* CRDTs and the clocks they need ([0cf6b7f](https://github.com/seuros/merge_machines/commit/0cf6b7f8de95fc40b5cdb6f05a1bf4bcafe6e7af))
|
|
13
|
+
* pass a rubygems OTP through the environment ([6834db9](https://github.com/seuros/merge_machines/commit/6834db97472a0028a6fa837d2cb3b845620d97e6))
|
|
14
|
+
* Ruby gem, magnus FFI, and a codec for every state ([6be0bda](https://github.com/seuros/merge_machines/commit/6be0bdaea6317b2bc02087db28eb374c0eea88af))
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### Bug Fixes
|
|
18
|
+
|
|
19
|
+
* a crowded reading let the hybrid clock reissue one timestamp ([4c4d139](https://github.com/seuros/merge_machines/commit/4c4d13942d5ccb3b70a5666f0b7306d1487d367b))
|
|
20
|
+
* a merge that overran capacity kept the names of the keys it turned down ([fe5ac2a](https://github.com/seuros/merge_machines/commit/fe5ac2aaec8bf9db35e2131fb67951dcaf5c4c1b))
|
|
21
|
+
* a PNCounter balance was the difference of two clamped totals ([dde63bc](https://github.com/seuros/merge_machines/commit/dde63bca70683ed8ba57deb962f980fab854b776))
|
|
22
|
+
* a register that got its value by merging took a stale write ([ae393ef](https://github.com/seuros/merge_machines/commit/ae393efc1fdaf8bf3980d70e7ef0508a3296c36d))
|
|
23
|
+
* a single observed timestamp stopped a Lamport clock for good ([48f7788](https://github.com/seuros/merge_machines/commit/48f77882dffb7bdd6952c1175612ca60e69c0aae))
|
|
24
|
+
* a source install can build, and a failed gem push fails the release ([bf37071](https://github.com/seuros/merge_machines/commit/bf37071c1398ecc81d4185f24d89cd89e8a8abe0))
|
|
25
|
+
* a truncated register blob loaded as an empty one ([1aa9391](https://github.com/seuros/merge_machines/commit/1aa939148ba7f5161158b033a0a08c658ad3d9fa))
|
|
26
|
+
* an OrSet add vanished when a replica's tag counter ran out ([8f81ce8](https://github.com/seuros/merge_machines/commit/8f81ce8240ce9070bb50f685bd6d54750674089b))
|
|
27
|
+
* collect the built gems whatever depth the download puts them at ([29ccbdd](https://github.com/seuros/merge_machines/commit/29ccbddfbaee366919c2833925cfa989a5fb2a00))
|
|
28
|
+
* hybrid timestamps cross the boundary as nanoseconds, not Float seconds ([01c9d86](https://github.com/seuros/merge_machines/commit/01c9d8602d07be6bdfcb659ae90b8f42706130e4))
|
|
29
|
+
* keep the name table consistent when a merge overruns capacity ([3f34aa5](https://github.com/seuros/merge_machines/commit/3f34aa5c24bae838a1a3421f64ae061c5a6afb5b))
|
|
30
|
+
* refuse a fractional stamp instead of truncating it into a tie ([6d3be65](https://github.com/seuros/merge_machines/commit/6d3be65af48918f890544e8547cfeb0eb03b45a2))
|
|
31
|
+
* ship the core's test files so the packaged crate builds ([4651644](https://github.com/seuros/merge_machines/commit/4651644a58306aac0b6fd0e890f1f033b89adfa9))
|
|
32
|
+
* the hash let a short key collide with a longer zero-padded one ([0a53206](https://github.com/seuros/merge_machines/commit/0a532065246def302a6510f082779f7981a61ff3))
|
|
33
|
+
* the release tag carries the gem name, and the gate uses the aggregate output ([d048d8c](https://github.com/seuros/merge_machines/commit/d048d8cf92bf29b7a284a2f475c4e6f94280563d))
|
|
34
|
+
* two unrescuable panics, a non-commutative merge, and a lost first write ([6951483](https://github.com/seuros/merge_machines/commit/6951483b917a731359ac2b4d94c0b326439f0882))
|
|
35
|
+
|
|
36
|
+
## 0.1.0
|
|
37
|
+
|
|
38
|
+
- Initial release.
|
|
39
|
+
- `MergeMachines::GCounter` and `PNCounter`: one count per replica, summed for
|
|
40
|
+
a value that only grows, and two of those for one that moves both ways.
|
|
41
|
+
- `MergeMachines::LwwRegister`: one value, held by whichever write was stamped
|
|
42
|
+
last, with the replica id as the tie-break, stamped by either clock.
|
|
43
|
+
- `MergeMachines::GSet` and `OrSet`: a set nothing leaves, and one where a
|
|
44
|
+
remove only takes out the adds it has seen, so a concurrent add survives it.
|
|
45
|
+
- `MergeMachines::LogicalClock` and `HybridClock`: Lamport's counter, and a
|
|
46
|
+
wall-clock reading paired with a counter that breaks its ties. The hybrid
|
|
47
|
+
clock reads `Process::CLOCK_REALTIME`, which may step backwards, and no
|
|
48
|
+
deadline may be derived from it.
|
|
49
|
+
- Keys and register values are Ruby strings, carried as 64-bit hashes with a
|
|
50
|
+
side table that `dump` and `load` round-trip.
|
|
51
|
+
- Replica counts and set capacities are const generics in the crate, so each
|
|
52
|
+
size is a separately compiled type and anything off the menu raises
|
|
53
|
+
`ArgumentError`.
|
|
54
|
+
- `merge-machines` core crate: the states and the clocks in `no_std` Rust with
|
|
55
|
+
zero dependencies, plus a fixed-length codec per state. Builds and lints
|
|
56
|
+
clean on bare metal.
|
|
57
|
+
- RBS signatures for the whole public API.
|
data/Cargo.lock
ADDED
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
# This file is automatically @generated by Cargo.
|
|
2
|
+
# It is not intended for manual editing.
|
|
3
|
+
version = 4
|
|
4
|
+
|
|
5
|
+
[[package]]
|
|
6
|
+
name = "aho-corasick"
|
|
7
|
+
version = "1.1.5"
|
|
8
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
9
|
+
checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
|
|
10
|
+
dependencies = [
|
|
11
|
+
"memchr",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
[[package]]
|
|
15
|
+
name = "bindgen"
|
|
16
|
+
version = "0.72.1"
|
|
17
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
18
|
+
checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
|
|
19
|
+
dependencies = [
|
|
20
|
+
"bitflags",
|
|
21
|
+
"cexpr",
|
|
22
|
+
"clang-sys",
|
|
23
|
+
"itertools",
|
|
24
|
+
"proc-macro2",
|
|
25
|
+
"quote",
|
|
26
|
+
"regex",
|
|
27
|
+
"rustc-hash",
|
|
28
|
+
"shlex",
|
|
29
|
+
"syn",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[[package]]
|
|
33
|
+
name = "bitflags"
|
|
34
|
+
version = "2.13.2"
|
|
35
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
36
|
+
checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
|
|
37
|
+
|
|
38
|
+
[[package]]
|
|
39
|
+
name = "bytes"
|
|
40
|
+
version = "1.12.1"
|
|
41
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
42
|
+
checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
|
|
43
|
+
|
|
44
|
+
[[package]]
|
|
45
|
+
name = "cexpr"
|
|
46
|
+
version = "0.6.0"
|
|
47
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
48
|
+
checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
|
|
49
|
+
dependencies = [
|
|
50
|
+
"nom",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[[package]]
|
|
54
|
+
name = "cfg-if"
|
|
55
|
+
version = "1.0.5"
|
|
56
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
57
|
+
checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
|
|
58
|
+
|
|
59
|
+
[[package]]
|
|
60
|
+
name = "clang-sys"
|
|
61
|
+
version = "1.9.1"
|
|
62
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
63
|
+
checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
|
|
64
|
+
dependencies = [
|
|
65
|
+
"glob",
|
|
66
|
+
"libc",
|
|
67
|
+
"libloading",
|
|
68
|
+
]
|
|
69
|
+
|
|
70
|
+
[[package]]
|
|
71
|
+
name = "either"
|
|
72
|
+
version = "1.19.0"
|
|
73
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
74
|
+
checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
|
|
75
|
+
|
|
76
|
+
[[package]]
|
|
77
|
+
name = "glob"
|
|
78
|
+
version = "0.3.4"
|
|
79
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
80
|
+
checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
|
|
81
|
+
|
|
82
|
+
[[package]]
|
|
83
|
+
name = "itertools"
|
|
84
|
+
version = "0.13.0"
|
|
85
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
86
|
+
checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
|
|
87
|
+
dependencies = [
|
|
88
|
+
"either",
|
|
89
|
+
]
|
|
90
|
+
|
|
91
|
+
[[package]]
|
|
92
|
+
name = "lazy_static"
|
|
93
|
+
version = "1.5.1"
|
|
94
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
95
|
+
checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
|
|
96
|
+
|
|
97
|
+
[[package]]
|
|
98
|
+
name = "libc"
|
|
99
|
+
version = "0.2.191"
|
|
100
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
101
|
+
checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
|
|
102
|
+
|
|
103
|
+
[[package]]
|
|
104
|
+
name = "libloading"
|
|
105
|
+
version = "0.8.9"
|
|
106
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
107
|
+
checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
|
|
108
|
+
dependencies = [
|
|
109
|
+
"cfg-if",
|
|
110
|
+
"windows-link",
|
|
111
|
+
]
|
|
112
|
+
|
|
113
|
+
[[package]]
|
|
114
|
+
name = "magnus"
|
|
115
|
+
version = "0.9.3"
|
|
116
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
117
|
+
checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
|
|
118
|
+
dependencies = [
|
|
119
|
+
"bytes",
|
|
120
|
+
"magnus-macros",
|
|
121
|
+
"rb-sys",
|
|
122
|
+
"rb-sys-env",
|
|
123
|
+
"seq-macro",
|
|
124
|
+
]
|
|
125
|
+
|
|
126
|
+
[[package]]
|
|
127
|
+
name = "magnus-macros"
|
|
128
|
+
version = "0.9.1"
|
|
129
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
130
|
+
checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
|
|
131
|
+
dependencies = [
|
|
132
|
+
"proc-macro2",
|
|
133
|
+
"quote",
|
|
134
|
+
"syn",
|
|
135
|
+
]
|
|
136
|
+
|
|
137
|
+
[[package]]
|
|
138
|
+
name = "memchr"
|
|
139
|
+
version = "2.8.3"
|
|
140
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
141
|
+
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
|
|
142
|
+
|
|
143
|
+
[[package]]
|
|
144
|
+
name = "merge-machines"
|
|
145
|
+
version = "0.2.0"
|
|
146
|
+
|
|
147
|
+
[[package]]
|
|
148
|
+
name = "merge_machines_native"
|
|
149
|
+
version = "0.1.1"
|
|
150
|
+
dependencies = [
|
|
151
|
+
"bytes",
|
|
152
|
+
"magnus",
|
|
153
|
+
"merge-machines",
|
|
154
|
+
]
|
|
155
|
+
|
|
156
|
+
[[package]]
|
|
157
|
+
name = "minimal-lexical"
|
|
158
|
+
version = "0.2.1"
|
|
159
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
160
|
+
checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
|
|
161
|
+
|
|
162
|
+
[[package]]
|
|
163
|
+
name = "nom"
|
|
164
|
+
version = "7.1.3"
|
|
165
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
166
|
+
checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
|
|
167
|
+
dependencies = [
|
|
168
|
+
"memchr",
|
|
169
|
+
"minimal-lexical",
|
|
170
|
+
]
|
|
171
|
+
|
|
172
|
+
[[package]]
|
|
173
|
+
name = "proc-macro2"
|
|
174
|
+
version = "1.0.107"
|
|
175
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
176
|
+
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
|
|
177
|
+
dependencies = [
|
|
178
|
+
"unicode-ident",
|
|
179
|
+
]
|
|
180
|
+
|
|
181
|
+
[[package]]
|
|
182
|
+
name = "quote"
|
|
183
|
+
version = "1.0.47"
|
|
184
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
185
|
+
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
|
|
186
|
+
dependencies = [
|
|
187
|
+
"proc-macro2",
|
|
188
|
+
]
|
|
189
|
+
|
|
190
|
+
[[package]]
|
|
191
|
+
name = "rb-sys"
|
|
192
|
+
version = "0.9.130"
|
|
193
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
194
|
+
checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
|
|
195
|
+
dependencies = [
|
|
196
|
+
"rb-sys-build",
|
|
197
|
+
]
|
|
198
|
+
|
|
199
|
+
[[package]]
|
|
200
|
+
name = "rb-sys-build"
|
|
201
|
+
version = "0.9.130"
|
|
202
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
203
|
+
checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
|
|
204
|
+
dependencies = [
|
|
205
|
+
"bindgen",
|
|
206
|
+
"lazy_static",
|
|
207
|
+
"proc-macro2",
|
|
208
|
+
"quote",
|
|
209
|
+
"regex",
|
|
210
|
+
"shell-words",
|
|
211
|
+
"syn",
|
|
212
|
+
]
|
|
213
|
+
|
|
214
|
+
[[package]]
|
|
215
|
+
name = "rb-sys-env"
|
|
216
|
+
version = "0.2.3"
|
|
217
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
218
|
+
checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
|
|
219
|
+
|
|
220
|
+
[[package]]
|
|
221
|
+
name = "regex"
|
|
222
|
+
version = "1.13.1"
|
|
223
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
224
|
+
checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
|
|
225
|
+
dependencies = [
|
|
226
|
+
"aho-corasick",
|
|
227
|
+
"memchr",
|
|
228
|
+
"regex-automata",
|
|
229
|
+
"regex-syntax",
|
|
230
|
+
]
|
|
231
|
+
|
|
232
|
+
[[package]]
|
|
233
|
+
name = "regex-automata"
|
|
234
|
+
version = "0.4.18"
|
|
235
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
236
|
+
checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
|
|
237
|
+
dependencies = [
|
|
238
|
+
"aho-corasick",
|
|
239
|
+
"memchr",
|
|
240
|
+
"regex-syntax",
|
|
241
|
+
]
|
|
242
|
+
|
|
243
|
+
[[package]]
|
|
244
|
+
name = "regex-syntax"
|
|
245
|
+
version = "0.8.11"
|
|
246
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
247
|
+
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
|
|
248
|
+
|
|
249
|
+
[[package]]
|
|
250
|
+
name = "rustc-hash"
|
|
251
|
+
version = "2.1.3"
|
|
252
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
253
|
+
checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
|
|
254
|
+
|
|
255
|
+
[[package]]
|
|
256
|
+
name = "seq-macro"
|
|
257
|
+
version = "0.3.6"
|
|
258
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
259
|
+
checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
|
|
260
|
+
|
|
261
|
+
[[package]]
|
|
262
|
+
name = "shell-words"
|
|
263
|
+
version = "1.1.1"
|
|
264
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
265
|
+
checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
|
|
266
|
+
|
|
267
|
+
[[package]]
|
|
268
|
+
name = "shlex"
|
|
269
|
+
version = "1.3.0"
|
|
270
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
271
|
+
checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
|
|
272
|
+
|
|
273
|
+
[[package]]
|
|
274
|
+
name = "syn"
|
|
275
|
+
version = "2.0.119"
|
|
276
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
277
|
+
checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
|
|
278
|
+
dependencies = [
|
|
279
|
+
"proc-macro2",
|
|
280
|
+
"quote",
|
|
281
|
+
"unicode-ident",
|
|
282
|
+
]
|
|
283
|
+
|
|
284
|
+
[[package]]
|
|
285
|
+
name = "unicode-ident"
|
|
286
|
+
version = "1.0.27"
|
|
287
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
288
|
+
checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
|
|
289
|
+
|
|
290
|
+
[[package]]
|
|
291
|
+
name = "windows-link"
|
|
292
|
+
version = "0.2.1"
|
|
293
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
294
|
+
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
|
data/Cargo.toml
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
[workspace]
|
|
2
|
+
members = ["ext/merge_machines_native/core", "ext/merge_machines_native/ffi"]
|
|
3
|
+
resolver = "3"
|
|
4
|
+
|
|
5
|
+
[workspace.package]
|
|
6
|
+
edition = "2024"
|
|
7
|
+
rust-version = "1.99"
|
|
8
|
+
|
|
9
|
+
[workspace.dependencies]
|
|
10
|
+
merge-machines = { path = "ext/merge_machines_native/core" }
|
|
11
|
+
|
|
12
|
+
[workspace.lints.rust]
|
|
13
|
+
unsafe_code = "forbid"
|
|
14
|
+
unused_must_use = "warn"
|
|
15
|
+
|
|
16
|
+
[workspace.lints.clippy]
|
|
17
|
+
all = { level = "warn", priority = -1 }
|
|
18
|
+
pedantic = { level = "warn", priority = -1 }
|
|
19
|
+
nursery = { level = "warn", priority = -1 }
|
|
20
|
+
expect_used = "deny"
|
|
21
|
+
unwrap_used = "deny"
|
|
22
|
+
uninlined_format_args = "deny"
|
|
23
|
+
needless_borrow = "deny"
|
|
24
|
+
redundant_clone = "deny"
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Abdelkader Boudih
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
+
THE SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
# MergeMachines 🔀
|
|
2
|
+
|
|
3
|
+
> **Two ships, one log, no argument.** The tender that lets separated crews write
|
|
4
|
+
> their own records and still agree when the fleet regroups.
|
|
5
|
+
|
|
6
|
+
Conflict-free replicated data types for Ruby, and the clocks that stamp them.
|
|
7
|
+
|
|
8
|
+
Two processes that both edited the same thing have to agree on the result
|
|
9
|
+
without asking each other. These states merge commutatively, associatively and
|
|
10
|
+
idempotently, so a replica converges on the same value whatever order the
|
|
11
|
+
updates arrived in and however many times one of them arrived. **AMS Lamport**
|
|
12
|
+
runs under comms blackout by design: it never calls home, it reconciles on
|
|
13
|
+
contact.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 🚀 Launch Sequence
|
|
18
|
+
|
|
19
|
+
```ruby
|
|
20
|
+
require 'merge_machines'
|
|
21
|
+
|
|
22
|
+
edge = MergeMachines::GCounter.new(replicas: 8)
|
|
23
|
+
origin = MergeMachines::GCounter.new(replicas: 8)
|
|
24
|
+
|
|
25
|
+
edge.increment(replica: 1, by: 3)
|
|
26
|
+
origin.increment(replica: 2, by: 7)
|
|
27
|
+
|
|
28
|
+
edge.merge(origin).value # => 10
|
|
29
|
+
edge.merge(origin).value # => 10, the same state again is absorbed
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Nothing here talks to a network. The caller owns the transport, the replica ids
|
|
33
|
+
and every clock reading.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 🔩 The Native Extension Is Required
|
|
38
|
+
|
|
39
|
+
There is no pure-Ruby fallback and no `DISABLE_*` switch. The gem is a binding
|
|
40
|
+
to the `merge-machines` crate in `ext/merge_machines_native/core`, and it needs
|
|
41
|
+
Ruby 4.0 and a Rust toolchain (or a platform gem). A second implementation
|
|
42
|
+
would mean two sets of convergence tests and two byte formats to keep in step.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 📐 Sizes Are a Fixed Menu
|
|
47
|
+
|
|
48
|
+
The crate sizes every state by a const generic, so each size is a separately
|
|
49
|
+
compiled type. The extension carries these and raises `ArgumentError` for
|
|
50
|
+
anything else:
|
|
51
|
+
|
|
52
|
+
| Class | Keyword | Values |
|
|
53
|
+
| ------------- | ----------- | ---------------- |
|
|
54
|
+
| `GCounter` | `replicas:` | 4, 8, 16, 32 |
|
|
55
|
+
| `PNCounter` | `replicas:` | 4, 8, 16, 32 |
|
|
56
|
+
| `GSet` | `capacity:` | 64, 256, 1024 |
|
|
57
|
+
| `OrSet` | `capacity:` | 64, 256, 1024 |
|
|
58
|
+
| `LwwRegister` | `stamp:` | `:logical`, `:hybrid` |
|
|
59
|
+
|
|
60
|
+
```ruby
|
|
61
|
+
MergeMachines::GSet.new(capacity: 100)
|
|
62
|
+
# ArgumentError: capacity 100 is not supported, expected one of [64, 256, 1024]
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
A state with no free slot left raises `MergeMachines::Full` rather than
|
|
66
|
+
growing. That is the deal a fixed size buys: a replica's memory is known at
|
|
67
|
+
construction time.
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 🔢 Counters
|
|
72
|
+
|
|
73
|
+
```ruby
|
|
74
|
+
counter = MergeMachines::GCounter.new(replicas: 8)
|
|
75
|
+
counter.increment(replica: 1, by: 3)
|
|
76
|
+
counter.increment(replica: 1) # by: defaults to 1
|
|
77
|
+
counter.count(replica: 1) # => 4
|
|
78
|
+
counter.value # => 4, every replica's count
|
|
79
|
+
counter.merge(other) # exact union, idempotent
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
One shared number cannot be merged: two replicas that both saw 5 and both added
|
|
83
|
+
1 have no way to tell 6 from 7. One count per replica can, because no replica
|
|
84
|
+
ever writes another's count, which is why `increment` needs a `replica:`.
|
|
85
|
+
|
|
86
|
+
`PNCounter` is two of those, one for what went up and one for what came down,
|
|
87
|
+
so its value may be negative.
|
|
88
|
+
|
|
89
|
+
```ruby
|
|
90
|
+
counter = MergeMachines::PNCounter.new(replicas: 8)
|
|
91
|
+
counter.increment(replica: 1, by: 10)
|
|
92
|
+
counter.decrement(replica: 2, by: 4)
|
|
93
|
+
counter.value # => 6
|
|
94
|
+
counter.added # => 10
|
|
95
|
+
counter.removed # => 4
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## 🗂️ Sets
|
|
101
|
+
|
|
102
|
+
Keys are strings and must be UTF-8. The crate's elements are `Copy + Eq`, so a
|
|
103
|
+
key crosses as a 64-bit hash of its bytes and the extension keeps the string
|
|
104
|
+
each hash came from; `dump` carries that table along, so `load` hands the real
|
|
105
|
+
strings back.
|
|
106
|
+
|
|
107
|
+
```ruby
|
|
108
|
+
set = MergeMachines::GSet.new(capacity: 64)
|
|
109
|
+
set.add('user-1')
|
|
110
|
+
set.include?('user-1') # => true
|
|
111
|
+
set.members # => ['user-1']
|
|
112
|
+
set.merge(other) # union
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`GSet` only grows, so merging is the union and there is nothing to resolve.
|
|
116
|
+
`OrSet` tags every add and tombstones the tags a remove has seen, so a remove
|
|
117
|
+
races a concurrent add and loses, and re-adding afterwards works.
|
|
118
|
+
|
|
119
|
+
```ruby
|
|
120
|
+
set = MergeMachines::OrSet.new(capacity: 64)
|
|
121
|
+
set.add('user-1', replica: 1)
|
|
122
|
+
set.remove('user-1')
|
|
123
|
+
set.include?('user-1') # => false
|
|
124
|
+
|
|
125
|
+
set.add('user-1', replica: 1)
|
|
126
|
+
set.include?('user-1') # => true
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`capacity:` bounds the adds and the tombstones separately. A removed key keeps
|
|
130
|
+
its add slot, so a set that churns runs out.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 🏁 One Value, Last Writer Wins
|
|
135
|
+
|
|
136
|
+
Stamps order the writes and the replica id breaks the ties. Both sides of a
|
|
137
|
+
concurrent write pick the same winner, which is the whole point, and the
|
|
138
|
+
loser's value is gone, which is the price.
|
|
139
|
+
|
|
140
|
+
```ruby
|
|
141
|
+
register = MergeMachines::LwwRegister.new
|
|
142
|
+
register.set('http://origin', replica: 1, stamp: 7)
|
|
143
|
+
register.value # => 'http://origin'
|
|
144
|
+
register.stamp # => 7
|
|
145
|
+
register.replica # => 1
|
|
146
|
+
register.merge(other)
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
A register nobody has written holds `nil`. `stamp:` is whichever clock you
|
|
150
|
+
picked at construction: an Integer for `:logical`, a `Timestamp` for
|
|
151
|
+
`:hybrid`.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## 🕰️ Which Chronometer
|
|
156
|
+
|
|
157
|
+
`LogicalClock` is Lamport's counter. It advances on every local event and jumps
|
|
158
|
+
past any stamp it is shown, so a receive is always stamped after the send it
|
|
159
|
+
answers. No clock is read.
|
|
160
|
+
|
|
161
|
+
```ruby
|
|
162
|
+
clock = MergeMachines::LogicalClock.new(replica: 1)
|
|
163
|
+
sent_at = clock.tick # => 1
|
|
164
|
+
clock.observe(42) # => 43, past both the local history and the send
|
|
165
|
+
clock.now # => 43
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
A counter with nothing left raises `MergeMachines::Exhausted` rather than
|
|
169
|
+
handing out a stamp it already gave away, and the clock stays where it was.
|
|
170
|
+
|
|
171
|
+
`HybridClock` pairs a wall-clock reading with a counter: close to physical
|
|
172
|
+
time, still totally ordered, and still monotonic when the host's clock is
|
|
173
|
+
corrected backwards.
|
|
174
|
+
|
|
175
|
+
```ruby
|
|
176
|
+
clock = MergeMachines::HybridClock.new(replica: 1)
|
|
177
|
+
clock.tick # Timestamp, reading from the realtime clock
|
|
178
|
+
clock.tick(wall_ns: 1_700_000_000_500_000_000) # or a reading you supply
|
|
179
|
+
clock.observe(wall_ns: 1_500_000_000, counter: 3) # a timestamp that arrived
|
|
180
|
+
clock.now # the last one issued
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
It raises `MergeMachines::Exhausted` too, when the reading has not advanced and
|
|
184
|
+
the counter that separates two events at one reading has nothing left. A
|
|
185
|
+
reading that really did advance resets that counter.
|
|
186
|
+
|
|
187
|
+
### ⚠️ The Reading It Wants Is Not a Monotonic One
|
|
188
|
+
|
|
189
|
+
`wall_ns:` is physical time two machines can compare, in nanoseconds, and
|
|
190
|
+
defaults to
|
|
191
|
+
`Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)`. That clock
|
|
192
|
+
**steps backwards** when the host's is corrected, which is exactly why the
|
|
193
|
+
counter exists.
|
|
194
|
+
|
|
195
|
+
**No deadline, timeout or budget may be derived from it.** Measuring how long
|
|
196
|
+
something took belongs to the monotonic clock, which this gem neither reads nor
|
|
197
|
+
models. `deadline_machines` owns that, and **AMS Layland** is the ship you hail
|
|
198
|
+
for it.
|
|
199
|
+
|
|
200
|
+
A reading crosses this boundary as seconds in a Float, so a realtime reading
|
|
201
|
+
round-trips to about 256 nanoseconds. Two timestamps that land inside the same
|
|
202
|
+
window are separated by the counter, which is what it is for.
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## 📦 Putting State on a Wire
|
|
207
|
+
|
|
208
|
+
`dump` returns a binary string and `load` reads one back.
|
|
209
|
+
|
|
210
|
+
```ruby
|
|
211
|
+
blob = set.dump # String, Encoding::BINARY
|
|
212
|
+
MergeMachines::GSet.load(blob)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
A blob is the crate's own fixed-length frame, led by a tag byte naming the
|
|
216
|
+
structure and a field naming the shape, followed by whatever the Ruby surface
|
|
217
|
+
needs that the frame does not hold: the key table for the sets and the
|
|
218
|
+
register, the replica id for the clocks. `load` raises `ArgumentError` on a
|
|
219
|
+
truncated blob, on one written by another structure, and on one written at a
|
|
220
|
+
shape this build does not carry.
|
|
221
|
+
|
|
222
|
+
```ruby
|
|
223
|
+
MergeMachines::GSet.load(MergeMachines::OrSet.new(capacity: 64).dump)
|
|
224
|
+
# ArgumentError: codec: wrong structure tag
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 🚫 Rules of Engagement
|
|
230
|
+
|
|
231
|
+
- It is not a transport. There is no gossip, no anti-entropy loop, no peer
|
|
232
|
+
list. You ship the blobs.
|
|
233
|
+
- It is not a timer. The hybrid clock reads a wall clock, never a monotonic
|
|
234
|
+
one, and nothing here measures elapsed time.
|
|
235
|
+
- It is not a state machine, and it does not retry, back off, break a circuit
|
|
236
|
+
or shed load. Other machines in this family do those.
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## 📡 Credits
|
|
241
|
+
|
|
242
|
+
**AMS Lamport**, NCC-1178, *Lamport*-class tender.
|
|
243
|
+
|
|
244
|
+
Named for Leslie Lamport's *Time, Clocks, and the Ordering of Events in a
|
|
245
|
+
Distributed System* (1978), which showed that order between separated machines
|
|
246
|
+
is something you stamp, not something you read off a clock.
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## License
|
|
251
|
+
|
|
252
|
+
MIT.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
[package]
|
|
2
|
+
name = "merge-machines"
|
|
3
|
+
version = "0.2.0"
|
|
4
|
+
edition.workspace = true
|
|
5
|
+
rust-version.workspace = true
|
|
6
|
+
authors = ["Abdelkader Boudih <oss@seuros.com>"]
|
|
7
|
+
license = "MIT"
|
|
8
|
+
description = "Conflict-free replicated data types and the clocks they need - counters, registers, sets, Lamport and hybrid logical clocks, no_std with zero dependencies"
|
|
9
|
+
repository = "https://github.com/seuros/merge_machines"
|
|
10
|
+
keywords = ["crdt", "lamport", "replication", "eventual-consistency", "no-std"]
|
|
11
|
+
categories = ["no-std", "data-structures"]
|
|
12
|
+
readme = "README.md"
|
|
13
|
+
|
|
14
|
+
[lib]
|
|
15
|
+
name = "merge_machines"
|
|
16
|
+
crate-type = ["lib"]
|
|
17
|
+
|
|
18
|
+
[features]
|
|
19
|
+
default = ["std"]
|
|
20
|
+
std = ["alloc"]
|
|
21
|
+
alloc = []
|
|
22
|
+
|
|
23
|
+
[lints]
|
|
24
|
+
workspace = true
|