outbox_machines 0.8.1-aarch64-linux

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 ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: ed0f88f3e51a055ac8d4d50174a551412775c08df1ebaa227d3e834b14a6e69e
4
+ data.tar.gz: 4e337a235dab17f8c127fe5b7ea353bd404746c7949355f990a5bee289cf01c7
5
+ SHA512:
6
+ metadata.gz: d7e8ad3830048739aacb26bc02086b28b063b24388f395c3ca12902a0282754f8ca8c3b6f0bd71ff2ac9a770a3cdb01d37d45c10bf553117f8184e5eaba72dea
7
+ data.tar.gz: 26610e0da001b228cde92c014adaf2df428f5921e17bc0e86955da9b3ed1c44588c9a5327e842e6db1755b1b73fc750e9f4d6bba9bc49b113848ded03c8b65a8
data/CHANGELOG.md ADDED
@@ -0,0 +1,106 @@
1
+ # Changelog
2
+
3
+ ## [0.8.1](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.8.0...outbox_machines/v0.8.1) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a value runs no Ruby ([0aecf34](https://github.com/seuros/outbox_machines/commit/0aecf34e6c76d99fffdceeeb1b1d6bebdb498b68))
9
+
10
+ ## [0.8.0](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.7.0...outbox_machines/v0.8.0) (2026-11-16)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * rename Sweep::written to Sweep::expired; times take full Duration
16
+
17
+ ### Features
18
+
19
+ * rename Sweep::written to Sweep::expired; times take full Duration ([6ed9a94](https://github.com/seuros/outbox_machines/commit/6ed9a94383a1f48efcbd0074900b2d79c717d425))
20
+
21
+ ## [0.7.0](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.6.1...outbox_machines/v0.7.0) (2026-11-14)
22
+
23
+
24
+ ### ⚠ BREAKING CHANGES
25
+
26
+ * read dispositions with symbol_or_fields under one message
27
+
28
+ ### Features
29
+
30
+ * read dispositions with symbol_or_fields under one message ([e688077](https://github.com/seuros/outbox_machines/commit/e688077d680a0141eb8e637bc3043cd2b58b4486))
31
+
32
+ ## [0.6.1](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.6.0...outbox_machines/v0.6.1) (2026-11-14)
33
+
34
+
35
+ ### Bug Fixes
36
+
37
+ * **deps:** require matryona-machines >= 0.3 ([8f99e68](https://github.com/seuros/outbox_machines/commit/8f99e681d265f29452b81a86ec67adcf4b309931))
38
+
39
+ ## [0.6.0](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.5.0...outbox_machines/v0.6.0) (2026-11-14)
40
+
41
+
42
+ ### ⚠ BREAKING CHANGES
43
+
44
+ * adopt matryona-machines 0.2 and check frozen before converting arguments
45
+
46
+ ### Features
47
+
48
+ * adopt matryona-machines 0.2 and check frozen before converting arguments ([06553b9](https://github.com/seuros/outbox_machines/commit/06553b93b8b47b79289cb85c1da24b44248146a0))
49
+
50
+ ## [0.5.0](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.4.0...outbox_machines/v0.5.0) (2026-11-14)
51
+
52
+
53
+ ### ⚠ BREAKING CHANGES
54
+
55
+ * build the binding on matryona-machines; accept a genuine value whose singleton class was opened; name every argument in conversion errors
56
+
57
+ ### Features
58
+
59
+ * build the binding on matryona-machines; accept a genuine value whose singleton class was opened; name every argument in conversion errors ([79e565c](https://github.com/seuros/outbox_machines/commit/79e565c2859fd02c7ca7fc99057b0cca410aa988))
60
+
61
+ ## [0.4.0](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.3.0...outbox_machines/v0.4.0) (2026-11-14)
62
+
63
+
64
+ ### ⚠ BREAKING CHANGES
65
+
66
+ * private value fields, drop the enqueue sequence, Pass replaces the sweep flag, sealed exact-class values, clone-then-keep claim/fail/expire
67
+
68
+ ### Features
69
+
70
+ * private value fields, drop the enqueue sequence, Pass replaces the sweep flag, sealed exact-class values, clone-then-keep claim/fail/expire ([e6c66dc](https://github.com/seuros/outbox_machines/commit/e6c66dcb726d2a211785504a9fff6ad1daa19611))
71
+
72
+ ## [0.3.0](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.2.0...outbox_machines/v0.3.0) (2026-11-13)
73
+
74
+
75
+ ### ⚠ BREAKING CHANGES
76
+
77
+ * handles are issued through periscope-machines. Every instance can be built with a scope; a handle from another scope is refused before any lookup; all handle kinds of an instance share one sequence; resumed restores the sequence after a restart. An attempt from another outbox, or one this outbox never issued, answers Stale.
78
+
79
+ ### Features
80
+
81
+ * scope attempt identities through periscope-machines, refuse attempts never issued, add Outbox::resumed ([f47285b](https://github.com/seuros/outbox_machines/commit/f47285b5304cbc21d6378b7f448badca23f32196))
82
+
83
+ ## [0.2.0](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.1.2...outbox_machines/v0.2.0) (2026-11-13)
84
+
85
+
86
+ ### ⚠ BREAKING CHANGES
87
+
88
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. Claimed and Expired carry a u64 attempt instead of a per-record generation; refused or repeated calls never advance the clock; the Error alias is gone; Ruby times are Integer nanoseconds and values mirror the core.
89
+
90
+ ### Features
91
+
92
+ * never reissue attempt identities, honour repeated confirm, fail and forget, Full and Mismatch refusals ([12af815](https://github.com/seuros/outbox_machines/commit/12af815e86a5ac549ec5149642afe35c91ff7a75))
93
+
94
+ ## [0.1.2](https://github.com/seuros/outbox_machines/compare/outbox_machines/v0.1.1...outbox_machines/v0.1.2) (2026-11-13)
95
+
96
+
97
+ ### Features
98
+
99
+ * rename Error to Refusal and implement Default for Expired ([6f70b82](https://github.com/seuros/outbox_machines/commit/6f70b82ebad6b6f66ea67e520bbb54fcde79550a))
100
+
101
+ ## [0.1.1](https://github.com/seuros/outbox_machines/compare/outbox_machines-v0.1.0...outbox_machines/v0.1.1) (2026-11-12)
102
+
103
+
104
+ ### Features
105
+
106
+ * initial extraction ([1f6f6ac](https://github.com/seuros/outbox_machines/commit/1f6f6ac855f31b4f1da27c3709f71bc1f0d4522c))
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 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 all
13
+ 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 THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,331 @@
1
+ # OutboxMachines
2
+
3
+ > Sent, probably, is not a delivery status.
4
+
5
+ A delivery ledger for Ruby. Every message you owe the outside world gets a record: pending, claimed by one attempt, confirmed, or dead. Each claim carries an attempt number the outbox issues once and never again, so a worker that woke up late can't confirm or fail an attempt that has since been handed to someone else. Attempts that never report back are surfaced as what they are: unknown.
6
+
7
+ This is an initial release and the API is unstable. It is delivery policy, not a transactional outbox and not a retry engine: it does not write to your database, relay anything, sleep, or schedule.
8
+
9
+ ## Quick Start
10
+
11
+ ```bash
12
+ gem 'outbox_machines'
13
+ ```
14
+
15
+ ```ruby
16
+ SECOND = 1_000_000_000
17
+ def now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
18
+
19
+ outbox = OutboxMachines::Outbox.new(5) # five attempts, then dead
20
+
21
+ # Once your transaction has committed the row:
22
+ outbox.enqueue(event.id, now)
23
+
24
+ def relay(outbox, broker)
25
+ claimed = outbox.claim(now, 30 * SECOND)
26
+ return unless claimed.is_a?(OutboxMachines::Claimed) # nil: nothing due
27
+
28
+ broker.publish(payload_for(claimed.id))
29
+ outbox.confirm(claimed.id, claimed.attempt)
30
+ rescue BrokerRefused
31
+ outbox.fail(claimed.id, claimed.attempt, now, 5 * SECOND)
32
+ end
33
+ ```
34
+
35
+ One outbox, six verbs. Ids and times are Integers. Every time, instant or span, in or out, is nanoseconds from a monotonic clock: `now`, `lease`, `retry_after`, a claim's `lease_expires`, the instant in a `Retry`. They take the whole range a Rust `Duration` holds, so an instant the outbox answered past `2**64 - 1` (a `lease_expires` is `now + lease`) goes back in as `now`; a negative one or one past `Duration::MAX` raises `RangeError`, and a sum past it is the refusal `:invalid_duration`.
36
+
37
+ The examples below use small numbers so the arithmetic fits on a line. They are nanoseconds like any other.
38
+
39
+ ## A Message to the Resistance
40
+
41
+ So you saved the order and published `order.created` in the same request. The commit went through and the publish timed out. Or the publish went through and the commit rolled back. Either way, two systems now disagree about whether an order exists, and you find out from a customer.
42
+
43
+ You know what the docs told you to do. "Use the outbox pattern." So you add an `outbox` table and a relay loop. Then two relays pick up the same row. So you add a `locked_at` column. Then a relay dies holding the lock, so you add a timeout. Then the relay that wasn't dead, only slow, wakes up and marks the row sent, over the top of the retry that is halfway through sending it again.
44
+
45
+ The piece you keep rebuilding is a small state machine per message: waiting, out with one attempt, done, given up. With a number on each attempt, so yesterday's attempt can't speak for today's. And a deadline, after which the honest answer is "we don't know what happened". That machine is this gem.
46
+
47
+ ## Chapter 1: Stardate 2026.316, the AMS Helland
48
+
49
+ > **AMS Helland**, NCC-4221, *Helland*-class dispatch courier.
50
+ > A dispatch with no receipt was neither delivered nor lost.
51
+
52
+ The courier doesn't carry the dispatches. It keeps the board. Every dispatch on it is waiting, out with a named runner, signed for, or written off. A runner who comes back after his run was given to someone else finds his chit is no longer good. The ship is named for Pat Helland, who spent a career explaining that the far side of a network is another country.
53
+
54
+ On a bridge somewhere, a cadet volunteers:
55
+
56
+ ```ruby
57
+ def relay(row)
58
+ broker.publish(row.payload)
59
+ row.update!(sent: true)
60
+ rescue Timeout::Error
61
+ retry
62
+ end
63
+ ```
64
+
65
+ "That," says the courier's dispatcher, "is a timeout you have decided to read as a no."
66
+
67
+ ## The Flight Plan
68
+
69
+ Each record the outbox holds is in one of these states:
70
+
71
+ ```mermaid
72
+ stateDiagram-v2
73
+ [*] --> pending: enqueue
74
+ pending --> claimed: claim, returns a Claimed
75
+ claimed --> confirmed: confirm(id, attempt)
76
+ claimed --> pending: fail, attempts remain
77
+ claimed --> pending: expire_claims, attempts remain
78
+ claimed --> dead: fail or expire_claims, attempts spent
79
+ confirmed --> [*]: forget
80
+ dead --> [*]: forget
81
+ ```
82
+
83
+ And the afternoon a relay went quiet with message 42:
84
+
85
+ ```mermaid
86
+ sequenceDiagram
87
+ participant R1 as Relay 1
88
+ participant O as Outbox
89
+ participant R2 as Relay 2
90
+
91
+ R1->>O: claim
92
+ O-->>R1: Claimed 42, attempt 1
93
+ Note over R1: publishes, then stalls
94
+
95
+ R2->>O: expire_claims
96
+ O-->>R2: Expired 42, attempt 1, retry
97
+ Note over R2: outcome unknown. Reconcile first.
98
+
99
+ R2->>O: claim
100
+ O-->>R2: Claimed 42, attempt 2
101
+
102
+ R1->>O: confirm(42, 1)
103
+ O-->>R1: :stale
104
+
105
+ R2->>O: confirm(42, 2)
106
+ O-->>R2: :confirmed
107
+ ```
108
+
109
+ ## How the Outbox Works
110
+
111
+ ### Enqueue
112
+
113
+ ```ruby
114
+ outbox = OutboxMachines::Outbox.new(3) # max attempts
115
+
116
+ outbox.enqueue(42, 0) # => :enqueued
117
+ outbox.enqueue(42, 0) # => :duplicate
118
+ outbox.get(42) # => #<data OutboxMachines::Entry id=42, state=:pending, attempts=0, attempt=nil, available_at=0>
119
+ outbox.get(7) # => nil, no such record
120
+ ```
121
+
122
+ `get(id)` answers the core's `Entry`: the record's `id`, its `state` (`:pending`, `:claimed`, `:confirmed` or `:dead`), the `attempts` claimed so far (what `max_attempts` counts), the `attempt` number of the latest one (`nil` until the first claim) and `available_at`, the earliest instant a pending record may be claimed. It answers `nil` for an id the outbox does not hold, and never refuses.
123
+
124
+ A record is an id and nothing else. The payload stays in your table. An id is taken for as long as its record exists, in any state.
125
+
126
+ `:duplicate` is not a refusal. You asked for the id to be on the board and it is, so the call is honoured and changes nothing, the outbox's clock included.
127
+
128
+ ### Claim
129
+
130
+ ```ruby
131
+ claimed = outbox.claim(0, 30_000) # now 0, lease 30_000 ns
132
+ claimed # => #<data OutboxMachines::Claimed id=42, attempt=1, lease_expires=30000>
133
+ outbox.claim(0, 30_000) # => nil, nothing else is due
134
+ outbox.get(42).state # => :claimed
135
+ ```
136
+
137
+ `claim(now, lease)` hands out the due pending record that was enqueued first. `nil` means nothing is due, which is an answer and not a refusal. `attempt` is the identity of this attempt: the outbox numbers every claim it hands out from one sequence, starting at 1, and never uses a number twice. An outbox built with `Outbox.with_scope(max_attempts, scope)` stamps its scope into the top 16 bits of that number. It is not the count of claims this record has had; that is `get(id).attempts`. `lease_expires` is `now + lease`, the instant from which `expire_claims` may reap the attempt. It is a deadline, not a timer: nothing happens when it passes until you ask.
138
+
139
+ ### Fail
140
+
141
+ ```ruby
142
+ failed = outbox.fail(42, claimed.attempt, 10, 5_000)
143
+ failed # => #<data OutboxMachines::Failed disposition=#<data OutboxMachines::Retry at=5010>>
144
+ failed.disposition # => #<data OutboxMachines::Retry at=5010>
145
+
146
+ # The reply got lost, so the relay reports the same attempt again:
147
+ outbox.fail(42, claimed.attempt, 12, 5_000)
148
+ # => #<data OutboxMachines::AlreadyFailed disposition=#<data OutboxMachines::Retry at=5010>>
149
+ outbox.fail(42, claimed.attempt, 12, 9_000) # => :mismatch, that is not what was reported
150
+
151
+ outbox.claim(5_009, 30_000) # => nil, not due yet
152
+ second = outbox.claim(5_010, 30_000)
153
+ second.attempt # => 2
154
+ outbox.fail(42, claimed.attempt, 5_010, 0) # => :stale, attempt 1 was superseded
155
+ ```
156
+
157
+ `fail(id, attempt, now, retry_after)` is for an attempt you know did nothing. You pass the delay, and the answer is a `Failed` wrapping the core's `Disposition`: a `Retry(at)` carrying the instant the record is claimable again, `now + retry_after`, or the symbol `:dead`. The outbox does not compute backoff.
158
+
159
+ Report the same attempt twice and the second answer is an `AlreadyFailed`. It is not a refusal: the attempt is over, as you asked, so the call is honoured and changes nothing, the clock included. Its disposition is the one from the first call. A repeat is the same report made again: same attempt, same `retry_after`. `now` is when you called, so it may differ, but a different `retry_after` is a different report and the answer is the refusal `:mismatch`, even for a record that died. The arguments of a repeat are still checked. The outbox honours that repeat only while it can prove it: until the record is claimed again, and only when it was `fail` that ended the attempt. An attempt reaped by `expire_claims` was never failed, so a `fail` for it is `:stale`.
160
+
161
+ Once the attempts are spent the answer changes:
162
+
163
+ ```ruby
164
+ single = OutboxMachines::Outbox.new(1)
165
+ single.enqueue(1, 0)
166
+ only = single.claim(0, 10)
167
+
168
+ single.fail(1, only.attempt, 5, 1_000) # => #<data OutboxMachines::Failed disposition=:dead>
169
+ single.fail(1, only.attempt, 6, 1_000) # => #<data OutboxMachines::AlreadyFailed disposition=:dead>
170
+ single.get(1).state # => :dead
171
+ single.claim(10_000, 10) # => nil
172
+ ```
173
+
174
+ A dead record is never claimed again. It sits there, countable with `count(:dead)`, until you `forget` it.
175
+
176
+ ### Confirm
177
+
178
+ ```ruby
179
+ outbox.confirm(42, 1) # => :stale, attempt 1 was superseded
180
+ outbox.confirm(42, 2) # => :confirmed
181
+ outbox.confirm(42, 2) # => :already_confirmed, and nothing changed
182
+ outbox.confirm(42, 1) # => :stale, still not the attempt that confirmed
183
+ outbox.confirm(7, 1) # => :unknown
184
+ ```
185
+
186
+ `confirm` is your word that the effect is persisted on the other side. The outbox can't check. Call it after the broker's acknowledgement or your durable write, never before.
187
+
188
+ `:already_confirmed` is not a refusal. A confirmed record is never claimed again, so its latest attempt is the one that confirmed it, and the outbox can tell that attempt's repeat from anyone else's for as long as it holds the record. After `forget` the record and the proof are both gone, and the same call answers `:unknown`.
189
+
190
+ ### Expire claims
191
+
192
+ ```ruby
193
+ outbox = OutboxMachines::Outbox.new(2)
194
+ outbox.enqueue(1, 0)
195
+ lost = outbox.claim(0, 10)
196
+
197
+ sweep = outbox.expire_claims(9, 64)
198
+ sweep.expired # => []
199
+ sweep.scanned # => 64
200
+ sweep.pass # => :complete
201
+
202
+ sweep = outbox.expire_claims(10, 64)
203
+ sweep.expired # => [#<data OutboxMachines::Expired id=1, attempt=1, disposition=#<data OutboxMachines::Retry at=10>>]
204
+ outbox.get(1).state # => :pending
205
+
206
+ fresh = outbox.claim(10, 10)
207
+ fresh.attempt # => 2
208
+ outbox.confirm(1, lost.attempt) # => :stale
209
+ outbox.confirm(1, fresh.attempt) # => :confirmed
210
+ ```
211
+
212
+ `expire_claims(now, max_scan)` reaps claims whose lease has ended and answers a `Sweep`: `expired`, `scanned` and `pass`. Each entry of `expired` is an `Expired` with an `id`, an `attempt` and a `disposition`, which is a `Retry(at)` or `:dead`. An expired record is due again immediately, so `at` is the `now` you passed. One call looks at no more than `max_scan` slots, says how many it looked at in `scanned`, and reaps no more than 16 claims. Keep calling until `pass` is `:complete` (it is `:partial` until the cursor has looked at every slot since the last full pass). A `max_scan` the platform's `usize` cannot hold raises `RangeError`; it is never narrowed.
213
+
214
+ An expired attempt did not fail. Nobody knows what it did. Until it is reaped, a late `confirm` for it is still accepted, because if the effect happened the record must not go out again.
215
+
216
+ ### Forget
217
+
218
+ ```ruby
219
+ outbox.enqueue(1, 10) # => :duplicate, confirmed records keep their id
220
+ outbox.forget(1) # => :forgotten
221
+ outbox.forget(1) # => :not_held
222
+ outbox.enqueue(1, 10) # => :enqueued
223
+ outbox.forget(1) # => :not_terminal
224
+ ```
225
+
226
+ Only confirmed and dead records can be forgotten. Forgetting frees the slot and the id. `:not_held` is not a refusal: you asked for the record to be gone and it is, whether it was forgotten earlier or never enqueued.
227
+
228
+ Forgetting does not free the attempt numbers the record used. Enqueue the id again and it is a new record whose first claim gets a number nobody has held:
229
+
230
+ ```ruby
231
+ outbox = OutboxMachines::Outbox.new(3)
232
+ outbox.enqueue(7, 0)
233
+ old = outbox.claim(0, 10) # attempt 1
234
+ outbox.confirm(7, old.attempt) # => :confirmed
235
+ outbox.forget(7) # => :forgotten
236
+ outbox.enqueue(7, 0) # => :enqueued, a new record
237
+ fresh = outbox.claim(0, 10)
238
+ fresh.attempt # => 2
239
+ outbox.get(7).attempts # => 1
240
+ outbox.confirm(7, old.attempt) # => :stale, a report about the record that is gone
241
+ outbox.fail(7, old.attempt, 0, 0) # => :stale
242
+ ```
243
+
244
+ ### Capacity
245
+
246
+ The outbox holds 64 records at a time, in any state. Past that, `enqueue` refuses with `:full` until something is forgotten:
247
+
248
+ ```ruby
249
+ outbox = OutboxMachines::Outbox.new(3)
250
+ outbox.capacity # => 64
251
+ OutboxMachines::CAPACITY # => 64
252
+ outbox.max_attempts # => 3
253
+
254
+ 64.times { |i| outbox.enqueue(i, 0) }
255
+ outbox.enqueue(64, 0) # => :full
256
+ outbox.size # => 64
257
+ outbox.count(:pending) # => 64
258
+ ```
259
+
260
+ Nothing is ever evicted to make room, confirmed and dead records included. Forget what you have dealt with.
261
+
262
+ ### Time only moves forward
263
+
264
+ The outbox remembers the latest time it has seen. Hand it an earlier one and it refuses:
265
+
266
+ ```ruby
267
+ outbox = OutboxMachines::Outbox.new(3)
268
+ outbox.enqueue(1, 10) # => :enqueued
269
+ outbox.enqueue(2, 9) # => :time_regression
270
+ outbox.claim(9, 5) # => :time_regression
271
+ outbox.expire_claims(9, 1) # => :time_regression
272
+ outbox.claim(10, 0) # => :invalid_duration
273
+ ```
274
+
275
+ A zero lease is `:invalid_duration`. Feed it `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`, never wall-clock time.
276
+
277
+ Only a call that is honoured and takes effect moves that clock. A refusal doesn't, and neither does a repeat: a `:duplicate` enqueue or an `AlreadyFailed`. (`confirm` and `forget` take no time at all.) A `claim` that finds nothing due and an `expire_claims` that reaps nothing were both honoured, so the time they were given counts.
278
+
279
+ ### What each verb can answer
280
+
281
+ | Verb | Honoured | Records `now` | Refusals |
282
+ | --- | --- | --- | --- |
283
+ | `enqueue` | `:enqueued`, `:duplicate` | `:enqueued` only (the record is claimable from `now`) | `:time_regression`, `:full` |
284
+ | `claim` | a `Claimed`, `nil` | both (`nil` means nothing was due at `now`) | `:time_regression`, `:invalid_duration`, `:exhausted` |
285
+ | `confirm` | `:confirmed`, `:already_confirmed` | takes no time | `:stale`, `:unknown` |
286
+ | `fail` | `Failed(disposition)`, `AlreadyFailed(disposition)` | `Failed` only (it retries from `now`) | `:stale`, `:unknown`, `:time_regression`, `:invalid_duration`, `:mismatch` |
287
+ | `expire_claims` | a `Sweep` | always, also when it reaped nothing (an answer about `now`) | `:time_regression` |
288
+ | `forget` | `:forgotten`, `:not_held` | takes no time | `:not_terminal` |
289
+
290
+ An honoured answer records `now` exactly when it depends on `now`. A repeat that holds whatever the time (`:duplicate`, `AlreadyFailed`) records nothing, and no refusal records anything.
291
+
292
+ A `disposition` is a `Retry(at)` or `:dead`. The queries `get`, `count`, `size`, `empty?`, `capacity`, `max_attempts`, `scope` and `issued` never refuse.
293
+
294
+ `:duplicate`, `:already_confirmed`, `AlreadyFailed` and `:not_held` are idempotent repeats: what you asked for already holds, so the call is honoured and changes nothing.
295
+
296
+ `:unknown` comes from `confirm` and `fail` only, for an id the outbox does not hold, reported with an attempt the outbox did issue. That includes a record you have since forgotten: the outbox keeps nothing about it, so it cannot call your report a repeat. `:stale` means the id is held but the attempt is neither its live one nor the one whose outcome the call repeats; an attempt that belonged to an earlier record with the same id is exactly that. An attempt this outbox never issued is `:stale` too, and that is answered first, before the id is even looked up, so it is `:stale` for an id the outbox does not hold as well: an attempt from an outbox of another scope, a number of its own scope it has not reached yet, or a number whose low 48 bits are zero. `:mismatch` comes from `fail` only: the attempt was already failed, with a different `retry_after`.
297
+
298
+ `:exhausted` comes from `claim` only: a record is due but the outbox has handed out every attempt number of its scope (2**48 - 1 claims) in its lifetime. It cannot be reached from Ruby in practice; you will not see it. Each refusal is the snake_case of one core `Refusal` variant; there is no catch-all symbol.
299
+
300
+ ## The Rules of the Courier
301
+
302
+ - **Ids and times are Integers** in `0..2**64-1`. Floats, nil, and strings raise `TypeError`. Negative or past `2**64-1` raises `RangeError`, and so does a `max_attempts` outside `1..2**32-1`.
303
+ - **Time is Integer nanoseconds**, for instants and spans alike. No floats, no milliseconds, no `Time`. An instant the outbox answers is exact, so `now + lease` can exceed `2**64-1` when you feed it numbers that large.
304
+ - **Values are valid or do not exist.** Every value class checks itself on `new` through the core's own constructor, so one you build by hand is held to the rule a returned one is. `Claimed.new(7, 0, 10)` (no outbox issues attempt sequence zero), `Claimed.new(7, 1, 0)` (a lease ends after the epoch), `Expired.new(7, 0, :dead)`, `Sweep.new([expired], 0, :complete)` (more reaped than scanned), `Entry.new(1, :claimed, 0, nil, 3)` (only a pending record is unclaimed), `Failed.new(:nope)` and `Retry.new(-1)` raise `RangeError`; a wrong type (`Retry.new(1.0)`, `Sweep.new([1], 3, :complete)`, `count('pending')`) raises `TypeError`. `count(:nope)` is `RangeError`.
305
+ - **Values are final, and the extension is the authority.** Subclassing a value class raises `TypeError` and `allocate` is gone. That stops accidents, not reflection: a named subclass still leaves its constant behind, `Marshal.load` and a hand-bound `Data#initialize` skip the check. So every value the extension reads back (the `Retry` in a `Failed` or an `Expired`, each `Expired` in a `Sweep`) must be exactly its class, and is read natively and checked again by the core: a forged one raises `TypeError` or `RangeError`. `Sweep` takes a plain `Array`, never a subclass.
306
+ - **The outbox never loses work.** Every argument is converted before the core is called, and the value classes are resolved once, when the extension loads. `claim`, `fail` and `expire_claims` answer Ruby objects, and building one runs Ruby code (`new`, which a reopened class can redefine), so the core decides on a copy, the answer is built, and the copy is kept only if the outbox is still unfrozen and unchanged. A `new` that raises applies nothing; one that freezes the outbox raises `FrozenError`, one that calls back in and changes it raises `RuntimeError`, and in both cases the outer call is not applied.
307
+ - **A Claimed is an id, an attempt, and `lease_expires`.** `Claimed`, `Expired`, `Sweep` and `Entry` are plain frozen `Data` values with the fields of the core structs they are named after; `Retry` is the core's `Disposition::Retry(at)`, and `Failed` and `AlreadyFailed` are the two variants of its `Failure`. `Sweep#expired` holds the reaped claims themselves where the core's `Sweep::expired` counts the ones it wrote to the caller's buffer. `confirm` and `fail` take the first two numbers of a `Claimed`, and an attempt that is neither the live one nor the one being repeated is `:stale`. Attempt numbers are never reissued, so a `Claimed` from last week cannot speak for a record enqueued today.
308
+ - **Scopes.** An attempt number is only meaningful to the outbox that issued it. Numbers count from 1, so two outboxes that hold the same record id hand out the same ones, and a report sent to the wrong outbox would settle the wrong attempt. Give each outbox its own scope: `Outbox.with_scope(max_attempts, scope)`, any Integer in `0..65_535` (a non-Integer raises `TypeError`, anything outside the range raises `RangeError`). `Outbox.new(max_attempts)` is scope zero, and `outbox.scope` reads it back. The scope rides in the top 16 bits of every `attempt`, and `confirm` and `fail` answer `:stale` to an attempt from another scope. The outbox can't pick a scope for you, and two outboxes left in the same scope still mix up each other's attempts.
309
+ - **Restarts.** A new outbox counts from 1 again, so an attempt that outlived a restart could name a new claim. Either save `outbox.issued` (how many attempt numbers it has handed out) and restart with `Outbox.resumed(max_attempts, scope, issued)`, which carries on at `issued + 1`, or give each incarnation a scope no earlier one used. Save the count before you act on a claim: resuming from too low a count hands numbers out twice. `issued` is an Integer in `0..2**48-1`; anything else raises `TypeError` or `RangeError`. Records are not restored, enqueue them again.
310
+ - **Refusals don't raise.** `:full`, `:stale`, `:unknown`, `:not_terminal`, `:time_regression`, `:invalid_duration`, `:exhausted` and `:mismatch` are answers. Only malformed input raises. A refused call changes nothing: no record, and not the clock.
311
+ - **Repeats are honoured.** `:duplicate`, `:already_confirmed`, `AlreadyFailed` and `:not_held` say the effect you asked for already holds. They change nothing either.
312
+ - **Lookup is a scan.** The table is small on purpose. Shard across outboxes before you ask for a bigger one.
313
+ - **Frozen means frozen.** `freeze` the outbox and `enqueue`, `claim`, `confirm`, `fail`, `expire_claims`, and `forget` all raise `FrozenError`. Reads still work.
314
+ - **Native is required.** There is no pure-Ruby fallback.
315
+
316
+ ## What You Think You're Doing vs Reality
317
+
318
+ ### You Think: "The lease expired, so the send failed. Retry."
319
+ ### Reality: The send might be sitting in the broker right now.
320
+
321
+ A timeout tells you the worker stopped talking. It doesn't tell you what the worker did first. That's why expiry and failure are separate verbs here: `fail` is a fact you supply, `expire_claims` is a list of questions the outbox hands back. Answer them, with an idempotency key on the destination, a fence, or a lookup, before the next attempt goes out.
322
+
323
+ ## What's Yours
324
+
325
+ The outbox lives in your process and forgets everything when the process does. Writing the outbox row in the same transaction as the business change is yours. So is the durable record of who claimed what, rebuilding the table after a restart, the relay loop, the backoff schedule, and working out what an expired attempt actually did. Receiving is a different problem: deduplicating what arrives is [dedup_machines](https://github.com/seuros/dedup_machines). This gem shares no code with it, or with the lease, chrono, and saga gems. They meet in your adapter.
326
+
327
+ ## License
328
+
329
+ MIT License. See [LICENSE.txt](LICENSE.txt) for details.
330
+
331
+ **Remember: the relay will time out. The question is whether you call that a failure.**
@@ -0,0 +1,81 @@
1
+ # Changelog
2
+
3
+ ## [0.9.0](https://github.com/seuros/outbox_machines/compare/outbox-machines-v0.8.0...outbox-machines-v0.9.0) (2026-11-16)
4
+
5
+
6
+ ### ⚠ BREAKING CHANGES
7
+
8
+ * rename Sweep::written to Sweep::expired; times take full Duration
9
+
10
+ ### Features
11
+
12
+ * rename Sweep::written to Sweep::expired; times take full Duration ([6ed9a94](https://github.com/seuros/outbox_machines/commit/6ed9a94383a1f48efcbd0074900b2d79c717d425))
13
+
14
+ ## [0.8.0](https://github.com/seuros/outbox_machines/compare/outbox-machines-v0.7.0...outbox-machines-v0.8.0) (2026-11-14)
15
+
16
+
17
+ ### ⚠ BREAKING CHANGES
18
+
19
+ * adopt matryona-machines 0.2 and check frozen before converting arguments
20
+
21
+ ### Features
22
+
23
+ * adopt matryona-machines 0.2 and check frozen before converting arguments ([06553b9](https://github.com/seuros/outbox_machines/commit/06553b93b8b47b79289cb85c1da24b44248146a0))
24
+
25
+ ## [0.7.0](https://github.com/seuros/outbox_machines/compare/outbox-machines-v0.6.0...outbox-machines-v0.7.0) (2026-11-14)
26
+
27
+
28
+ ### ⚠ BREAKING CHANGES
29
+
30
+ * build the binding on matryona-machines; accept a genuine value whose singleton class was opened; name every argument in conversion errors
31
+
32
+ ### Features
33
+
34
+ * build the binding on matryona-machines; accept a genuine value whose singleton class was opened; name every argument in conversion errors ([79e565c](https://github.com/seuros/outbox_machines/commit/79e565c2859fd02c7ca7fc99057b0cca410aa988))
35
+
36
+ ## [0.6.0](https://github.com/seuros/outbox_machines/compare/outbox-machines-v0.5.0...outbox-machines-v0.6.0) (2026-11-14)
37
+
38
+
39
+ ### ⚠ BREAKING CHANGES
40
+
41
+ * private value fields, drop the enqueue sequence, Pass replaces the sweep flag, sealed exact-class values, clone-then-keep claim/fail/expire
42
+
43
+ ### Features
44
+
45
+ * private value fields, drop the enqueue sequence, Pass replaces the sweep flag, sealed exact-class values, clone-then-keep claim/fail/expire ([e6c66dc](https://github.com/seuros/outbox_machines/commit/e6c66dcb726d2a211785504a9fff6ad1daa19611))
46
+
47
+ ## [0.5.0](https://github.com/seuros/outbox_machines/compare/outbox-machines-v0.4.0...outbox-machines-v0.5.0) (2026-11-13)
48
+
49
+
50
+ ### ⚠ BREAKING CHANGES
51
+
52
+ * handles are issued through periscope-machines. Every instance can be built with a scope; a handle from another scope is refused before any lookup; all handle kinds of an instance share one sequence; resumed restores the sequence after a restart. An attempt from another outbox, or one this outbox never issued, answers Stale.
53
+
54
+ ### Features
55
+
56
+ * scope attempt identities through periscope-machines, refuse attempts never issued, add Outbox::resumed ([f47285b](https://github.com/seuros/outbox_machines/commit/f47285b5304cbc21d6378b7f448badca23f32196))
57
+
58
+ ## [0.4.0](https://github.com/seuros/outbox_machines/compare/outbox-machines-v0.3.0...outbox-machines-v0.4.0) (2026-11-13)
59
+
60
+
61
+ ### ⚠ BREAKING CHANGES
62
+
63
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. Claimed and Expired carry a u64 attempt instead of a per-record generation; refused or repeated calls never advance the clock; the Error alias is gone; Ruby times are Integer nanoseconds and values mirror the core.
64
+
65
+ ### Features
66
+
67
+ * never reissue attempt identities, honour repeated confirm, fail and forget, Full and Mismatch refusals ([12af815](https://github.com/seuros/outbox_machines/commit/12af815e86a5ac549ec5149642afe35c91ff7a75))
68
+
69
+ ## [0.3.0](https://github.com/seuros/outbox_machines/compare/outbox-machines-v0.2.0...outbox-machines-v0.3.0) (2026-11-13)
70
+
71
+
72
+ ### Features
73
+
74
+ * rename Error to Refusal and implement Default for Expired ([6f70b82](https://github.com/seuros/outbox_machines/commit/6f70b82ebad6b6f66ea67e520bbb54fcde79550a))
75
+
76
+ ## [0.2.0](https://github.com/seuros/outbox_machines/compare/outbox-machines-v0.1.0...outbox-machines-v0.2.0) (2026-11-12)
77
+
78
+
79
+ ### Features
80
+
81
+ * initial extraction ([1f6f6ac](https://github.com/seuros/outbox_machines/commit/1f6f6ac855f31b4f1da27c3709f71bc1f0d4522c))
@@ -0,0 +1,226 @@
1
+ # outbox-machines
2
+
3
+ > **AMS Helland**, NCC-4221, *Helland*-class dispatch courier.
4
+
5
+ Engine-room flight manual: track owed dispatches through identity-checked attempts.
6
+
7
+ Pre-1.0. Bounded delivery-policy metadata for an outbox: records move
8
+ through `pending`, `claimed`, `confirmed` and `dead`, and every attempt carries
9
+ an identity the outbox issues once and never again, so a stale worker cannot
10
+ touch a newer attempt, nor a newer record that reuses the id.
11
+
12
+ This is **delivery policy only**. It is not a transactional outbox or inbox, not
13
+ a relay, and not a retry engine: it never sleeps, schedules, or performs I/O.
14
+ Atomic insertion with business writes, durable claims, crash recovery and
15
+ payload storage are adapter responsibilities. It composes with saga, dedup,
16
+ lease and chrono through explicit caller-side contracts only; this crate has no
17
+ dependency on any sibling.
18
+
19
+ Allocation-free `no_std`. Capacity `N` is a const generic; a full table refuses
20
+ with `Refusal::Full` and never evicts. Time is explicit and must not go
21
+ backwards: every instant (`now`, `Claimed::lease_expires`, `Disposition::Retry`,
22
+ `Entry::available_at`) and every span (`lease`, `retry_after`) is a
23
+ `core::time::Duration` since an epoch the caller picks. The Ruby gem passes
24
+ and answers the same values as Integer nanoseconds, and mirrors `Claimed`,
25
+ `Expired`, `Sweep` and `Entry` as `Data` values of the same names, and
26
+ `Failure`'s two variants as `Failed` and `AlreadyFailed` (its `Sweep#expired`
27
+ carries the expired entries where this one's `Sweep::expired` counts them). Lookup is a linear scan, so keep `N`
28
+ small. Ids are `u64`; payloads live outside.
29
+
30
+ - `enqueue(id, now) -> Result<Enqueue, Refusal>`: `Enqueued`, or `Duplicate`
31
+ for an id that is already present (an idempotent repeat: honoured, nothing
32
+ changes). An id stays taken, even when confirmed or dead, until
33
+ `forget(id)`. Refuses with `TimeRegression` or `Full`.
34
+ - `claim(now, lease) -> Result<Option<Claimed>, Refusal>`: the due pending
35
+ record enqueued first (a forgotten record's slot goes to a newcomer, its
36
+ place in line does not), or `None` when nothing is due. `Claimed::attempt` is
37
+ the identity of the attempt, drawn from one sequence for the whole outbox,
38
+ starting at 1 and carried under the outbox's scope. Refuses with `TimeRegression`, `InvalidDuration`, or
39
+ `Exhausted` when a record is due but that sequence is spent.
40
+ - `confirm(id, attempt) -> Result<Confirmation, Refusal>`: the caller
41
+ asserts the external effect was persisted. The outbox cannot verify it.
42
+ Accepted even after the lease deadline, as long as no newer attempt exists.
43
+ `Confirmed`, or `AlreadyConfirmed` when this same attempt already
44
+ confirmed the record. Refuses with `Stale` for an attempt this outbox never
45
+ issued (another scope, or a sequence it has not reached; before any
46
+ lookup), then `Unknown` or `Stale`.
47
+ - `fail(id, attempt, now, retry_after) -> Result<Failure, Refusal>`: a
48
+ *known* failure. `Failed(Disposition)`: back to pending at
49
+ `now + retry_after`, or `Dead` once `max_attempts` claims are spent.
50
+ `AlreadyFailed(Disposition)` when `fail` already ended this same attempt
51
+ with this same `retry_after` and no claim followed; it carries the standing
52
+ disposition. Refuses, in this order, with `Stale` for an attempt this outbox
53
+ never issued, `Unknown`, `Stale`,
54
+ `TimeRegression`, `InvalidDuration`, or `Mismatch` for a repeat whose
55
+ `retry_after` is not the one recorded.
56
+ - `expire_claims(now, max_scan, out)`: reaps claims whose lease ended, into a
57
+ caller buffer, with a persistent cursor. Bounded by `max_scan` and
58
+ `out.len()`; call again until `Sweep::pass()` is `Pass::Complete`. Writes the first
59
+ `Sweep::expired` entries of `out` and leaves the rest untouched. Build the
60
+ buffer as `[Expired::default(); K]`: the default is a placeholder with
61
+ attempt 0, which the outbox never emits. Refuses with `TimeRegression`.
62
+ - `forget(id) -> Result<Forgetting, Refusal>`: drops a confirmed or dead
63
+ record. `Forgotten`, or `NotHeld` when no record carries the id. Refuses
64
+ with `NotTerminal`.
65
+ - `get(id) -> Option<Entry>`: the record's state, `attempts` (the claims it
66
+ has had, which is what `max_attempts` counts) and `attempt` (the identity
67
+ of the latest one, `None` before the first claim).
68
+
69
+ ## Attempt identities
70
+
71
+ An attempt identity is issued once for the lifetime of the outbox. It is not
72
+ the record's attempt count, which restarts when an id is forgotten and
73
+ enqueued again; the identity does not. A worker that claimed id 7, went quiet,
74
+ and reports back after 7 was confirmed, forgotten, enqueued and claimed anew
75
+ presents an identity the new record never had: `Stale`, nothing changed.
76
+
77
+ ## Scopes
78
+
79
+ An attempt identity means something only to the outbox that issued it. It is
80
+ a `u64` in the [`periscope-machines`](https://crates.io/crates/periscope-machines)
81
+ layout: the outbox's scope in the top 16 bits, a sequence counted from 1 in
82
+ the low 48. `Outbox::new(max_attempts)` is scope zero and issues 1, 2, 3;
83
+ `Outbox::with_scope(max_attempts, scope)` issues the same sequence under
84
+ `scope`, and `Outbox::scope()`, `Claimed::scope()` and `Expired::scope()` read
85
+ it back.
86
+
87
+ Two outboxes that hold the same record id issue the same sequence numbers, so
88
+ without scopes a report sent to the wrong outbox settles the wrong attempt.
89
+ Give each outbox its own scope: `confirm` and `fail` then answer `Stale` to an
90
+ attempt of another scope before they look at any record, and nothing changes.
91
+ The outbox reads no clock and no random source, so it cannot pick a scope;
92
+ two outboxes left in the same scope still alias.
93
+
94
+ The check is `periscope_machines::Issuer::owns`, so it refuses more than
95
+ another scope: an attempt of this scope whose sequence the outbox has not
96
+ reached, or sequence zero, was never issued here and is `Stale` too, whatever
97
+ the id.
98
+
99
+ A fresh outbox starts its sequence again, so an attempt that outlived a
100
+ restart could name a new claim. Either save `Outbox::issued()` and restart
101
+ with `Outbox::resumed(max_attempts, scope, issued)`, which continues at
102
+ `issued + 1` (`None` when `issued` is past 2^48 - 1), or give each incarnation
103
+ a scope no earlier one used. Save the count before acting on a claim:
104
+ resuming from too low a count reissues identities.
105
+
106
+ A scope holds 2^48 - 1 identities. When they are spent `claim` refuses with
107
+ `Exhausted` rather than wrap, and only when a record is due.
108
+
109
+ ## Repeats and refusals
110
+
111
+ `Duplicate`, `AlreadyConfirmed`, `AlreadyFailed` and `NotHeld` are idempotent
112
+ repeats: the effect asked for already holds, so the call is honoured and
113
+ changes nothing, the observed clock included. The outbox honours only what it
114
+ can prove from the record it still holds:
115
+
116
+ - A confirmed record is never claimed again, so its latest attempt *is* the
117
+ confirming one. `confirm` with that attempt repeats; any other attempt is
118
+ `Stale`, an attempt of an earlier record with the same id included. The
119
+ attempt a record holds was issued by this outbox, and an attempt of another
120
+ scope is refused before the record is read, so a repeat is only ever
121
+ honoured for an identity of this scope.
122
+ - A record remembers whether its latest attempt was ended by `fail`, and with
123
+ which `retry_after`. `fail` with that attempt and that `retry_after` repeats
124
+ until the record is claimed again. `now` is the instant of the call, not
125
+ part of the report, so it may differ; a different `retry_after` is a
126
+ different report and is refused with `Mismatch`, also when the record died
127
+ and the delay shaped nothing. An attempt reaped by `expire_claims` has an
128
+ unknown outcome, not a failed one: `fail` for it is `Stale`, as is `fail`
129
+ for a confirmed attempt and `confirm` for a failed one.
130
+ - `claim` and `expire_claims` carry no identity a repeat could be matched on.
131
+ A second identical call is a new call: it claims the next due record, or
132
+ reaps nothing.
133
+
134
+ `Refusal::Unknown` is answered by `confirm` and `fail` only, when no record
135
+ carries the id and the attempt is one this outbox issued. That includes a record that was confirmed or dead and then
136
+ forgotten: nothing about it is kept, so a late repeat cannot be proven and is
137
+ `Unknown`. `enqueue`, `claim`, `expire_claims` and `forget` never answer it.
138
+
139
+ `Refusal::Stale` means the id is held but `attempt` is neither its live
140
+ attempt nor the attempt whose outcome the call repeats, or that this outbox
141
+ never issued `attempt` (another scope, or a sequence it has not reached),
142
+ whatever the id. The variants are
143
+ `Unknown`, `Stale`, `NotTerminal`, `TimeRegression`, `InvalidDuration`,
144
+ `Exhausted`, `Full` and `Mismatch`. `Refusal` is the only refusal type, no public enum is `#[non_exhaustive]`
145
+ (a new variant is a breaking change every caller matches on), and a refused call
146
+ changes nothing: no record, no sweep cursor, and not the observed clock.
147
+ `Outbox` is `PartialEq`, so `outbox == clone_taken_before` proves it.
148
+
149
+ An honoured answer records `now` exactly when it depends on `now`:
150
+
151
+ | Method | Records `now` | Leaves the clock alone |
152
+ | --- | --- | --- |
153
+ | `enqueue` | `Enqueued` (claimable from `now`) | `Duplicate` |
154
+ | `claim` | `Some(Claimed)`, `None` (nothing due at `now`) | |
155
+ | `confirm` | takes no time | `Confirmed`, `AlreadyConfirmed` |
156
+ | `fail` | `Failed` (retries from `now`) | `AlreadyFailed` |
157
+ | `expire_claims` | every `Sweep`, one that wrote nothing included | |
158
+ | `forget` | takes no time | `Forgotten`, `NotHeld` |
159
+
160
+ Every refusal leaves it alone.
161
+
162
+ ## Values
163
+
164
+ `Claimed::new`, `Expired::new`, `Sweep::new` and `Entry::new` build a value
165
+ only if some outbox could answer it, `None` otherwise: an attempt whose
166
+ sequence is zero (no scope issues it), a `Claimed` whose lease ends at the
167
+ epoch, a `Sweep` that wrote more than it scanned, an `Entry` whose attempt and
168
+ claim count disagree or that is claimed, confirmed or dead without an attempt.
169
+ Their fields are private and read through accessors of the same names
170
+ (`Sweep::pass()` answers `Pass::Partial` or `Pass::Complete`), so no value
171
+ skips that check; the Ruby gem validates every value it is handed through
172
+ these constructors. `Expired::default()` is the output-buffer
173
+ placeholder only.
174
+
175
+ ## Ambiguous effects
176
+
177
+ An expired lease is an unknown outcome, not a failure: the worker may still run
178
+ or may have already produced the effect. Expired claims are reported separately
179
+ so the adapter can reconcile (fence, query the destination, or use an
180
+ idempotency key) before trusting a retry. Use `fail` only for failures you know
181
+ did not take effect.
182
+
183
+ ```rust
184
+ use core::num::NonZeroU32;
185
+ use core::time::Duration;
186
+ use outbox_machines::{Confirmation, Disposition, Enqueue, Failure, Forgetting, Outbox, Refusal};
187
+
188
+ # fn main() -> Result<(), Refusal> {
189
+ let mut outbox = Outbox::<8>::new(NonZeroU32::MIN.saturating_add(2));
190
+ assert_eq!(outbox.enqueue(42, Duration::ZERO), Ok(Enqueue::Enqueued));
191
+ let Some(claimed) = outbox.claim(Duration::ZERO, Duration::from_secs(30))? else {
192
+ return Ok(());
193
+ };
194
+ assert_eq!((claimed.id(), claimed.attempt()), (42, 1));
195
+ let retry_at_5 = Disposition::Retry(Duration::from_secs(5));
196
+ assert_eq!(
197
+ outbox.fail(42, 1, Duration::ZERO, Duration::from_secs(5)),
198
+ Ok(Failure::Failed(retry_at_5))
199
+ );
200
+ assert_eq!(
201
+ outbox.fail(42, 1, Duration::ZERO, Duration::from_secs(5)),
202
+ Ok(Failure::AlreadyFailed(retry_at_5))
203
+ );
204
+ assert_eq!(
205
+ outbox.fail(42, 1, Duration::ZERO, Duration::from_secs(9)),
206
+ Err(Refusal::Mismatch)
207
+ );
208
+ let retry = outbox.claim(Duration::from_secs(5), Duration::from_secs(30))?;
209
+ assert_eq!(retry.map(|c| c.attempt()), Some(2));
210
+ assert_eq!(outbox.confirm(42, 1), Err(Refusal::Stale));
211
+ assert_eq!(outbox.confirm(42, 2), Ok(Confirmation::Confirmed));
212
+ assert_eq!(outbox.confirm(42, 2), Ok(Confirmation::AlreadyConfirmed));
213
+ assert_eq!(outbox.forget(42), Ok(Forgetting::Forgotten));
214
+ assert_eq!(outbox.forget(42), Ok(Forgetting::NotHeld));
215
+ assert_eq!(outbox.confirm(42, 2), Err(Refusal::Unknown));
216
+
217
+ // The id is free again, but the identities its attempts used are not.
218
+ assert_eq!(outbox.enqueue(42, Duration::from_secs(5)), Ok(Enqueue::Enqueued));
219
+ let anew = outbox.claim(Duration::from_secs(5), Duration::from_secs(30))?;
220
+ assert_eq!(anew.map(|c| c.attempt()), Some(3));
221
+ assert_eq!(outbox.get(42).map(|e| e.attempts()), Some(1));
222
+ assert_eq!(outbox.confirm(42, 1), Err(Refusal::Stale));
223
+ assert_eq!(outbox.confirm(42, 2), Err(Refusal::Stale));
224
+ # Ok(())
225
+ # }
226
+ ```
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OutboxMachines
4
+ VERSION = '0.8.1'
5
+ end
@@ -0,0 +1,131 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'outbox_machines/version'
4
+
5
+ module OutboxMachines
6
+ # A successful claim: the record id, the attempt identity that must
7
+ # accompany `confirm` and `fail`, and the instant (Integer nanoseconds) from
8
+ # which `expire_claims` may reap the lease. The outbox issues an attempt
9
+ # identity once and never again, also after the record is forgotten and its
10
+ # id enqueued anew; it is not the record's attempt count (`Entry#attempts`).
11
+ # The identity carries the scope of the outbox that issued it
12
+ # (`Outbox.with_scope`); an outbox of another scope answers :stale to it.
13
+ #
14
+ # Built by hand it is held to the core's `Claimed::new`: Integers in
15
+ # 0..2**64-1, an attempt whose sequence (low 48 bits) is at least 1, and a
16
+ # positive `lease_expires`. TypeError for the wrong type, RangeError for a
17
+ # value outside that.
18
+ Claimed = Data.define(:id, :attempt, :lease_expires) do
19
+ def initialize(id:, attempt:, lease_expires:)
20
+ OutboxMachines.__send__(:__claimed, id, attempt, lease_expires)
21
+ super
22
+ end
23
+
24
+ # The scope of the outbox that issued this attempt.
25
+ def scope = Outbox.__send__(:__scope_of, self)
26
+ end
27
+
28
+ # The core's `Disposition::Retry(at)`: the record is pending again and
29
+ # claimable at or after the instant `at` (Integer nanoseconds). The other
30
+ # disposition, `Disposition::Dead`, is the symbol :dead.
31
+ # `at` is an Integer: TypeError otherwise, RangeError when negative or past
32
+ # what a `Duration` holds.
33
+ Retry = Data.define(:at) do
34
+ def initialize(at:)
35
+ OutboxMachines.__send__(:__retry, at)
36
+ super
37
+ end
38
+ end
39
+
40
+ # The core's `Failure::Failed(disposition)`: `fail` ended the live attempt and
41
+ # the record went where the disposition (a Retry or :dead) says.
42
+ # A disposition is a Retry or :dead: TypeError for anything else that is not
43
+ # a Symbol, RangeError for another Symbol.
44
+ Failed = Data.define(:disposition) do
45
+ def initialize(disposition:)
46
+ OutboxMachines.__send__(:__failure, disposition)
47
+ super
48
+ end
49
+ end
50
+
51
+ # The core's `Failure::AlreadyFailed(disposition)`: an idempotent repeat.
52
+ # `fail` had already ended this same attempt with this same `retry_after`,
53
+ # nothing changed, and the disposition is the standing one from the first
54
+ # call.
55
+ # The disposition is checked as Failed's is.
56
+ AlreadyFailed = Data.define(:disposition) do
57
+ def initialize(disposition:)
58
+ OutboxMachines.__send__(:__failure, disposition)
59
+ super
60
+ end
61
+ end
62
+
63
+ # One claim reaped by `expire_claims`: the record id, the identity of the
64
+ # attempt whose lease ran out, and what became of the record (a Retry or
65
+ # :dead). Its outcome is unknown, not failed.
66
+ # Built by hand it is held to the core's `Expired::new`: an attempt whose
67
+ # sequence is at least 1, a disposition as Failed takes.
68
+ Expired = Data.define(:id, :attempt, :disposition) do
69
+ def initialize(id:, attempt:, disposition:)
70
+ OutboxMachines.__send__(:__expired, id, attempt, disposition)
71
+ super
72
+ end
73
+
74
+ # The scope of the outbox that issued the reaped attempt.
75
+ def scope = Outbox.__send__(:__scope_of, self)
76
+ end
77
+
78
+ # Progress of one bounded `expire_claims` call: the Expired values it reaped,
79
+ # the slots it examined, and where the cursor stands: the core's `Pass`,
80
+ # :complete once it has finished a full pass over every slot (cumulatively
81
+ # across calls), :partial until then.
82
+ # Built by hand it is held to the core's `Sweep::new`: a plain Array (no subclass) of Expired
83
+ # (kept as a frozen copy) no longer than `scanned`, and a `pass` of :partial
84
+ # or :complete (TypeError for a non-Symbol, RangeError for another Symbol).
85
+ Sweep = Data.define(:expired, :scanned, :pass) do
86
+ def initialize(expired:, scanned:, pass:)
87
+ OutboxMachines.__send__(:__sweep, expired, scanned, pass)
88
+ super(expired: expired.frozen? ? expired : expired.dup.freeze, scanned:, pass:)
89
+ end
90
+ end
91
+
92
+ # A read-only view of one record, from `Outbox#get`: its id, its state
93
+ # (:pending, :claimed, :confirmed or :dead), the claims issued to it so far,
94
+ # the identity of the latest one (nil until it is first claimed), and the
95
+ # earliest instant (Integer nanoseconds) a pending record may be claimed.
96
+ #
97
+ # Built by hand it is held to the core's `Entry::new`: `attempt` is nil
98
+ # exactly when `attempts` is 0, a present one has a sequence of at least 1,
99
+ # and only a :pending record is unclaimed. TypeError for the wrong type,
100
+ # RangeError for a value outside that.
101
+ Entry = Data.define(:id, :state, :attempts, :attempt, :available_at) do
102
+ def initialize(id:, state:, attempts:, attempt:, available_at:)
103
+ OutboxMachines.__send__(:__entry, id, state, attempts, attempt, available_at)
104
+ super
105
+ end
106
+ end
107
+ end
108
+
109
+ # Native is required: no algorithm fallback. It builds and validates the Data
110
+ # values above, so they must exist first.
111
+ require 'outbox_machines_native/outbox_machines_native'
112
+
113
+ module OutboxMachines
114
+ private_class_method :__retry, :__failure, :__claimed, :__expired, :__sweep, :__entry
115
+
116
+ # The values are final. `initialize` is where each validates, and a subclass
117
+ # could override it, or `allocate` build an instance that never ran it:
118
+ # subclassing raises TypeError and `allocate` is gone. That stops accidents,
119
+ # not reflection (Ruby binds a named subclass's constant before `inherited`
120
+ # raises; `Marshal.load` and a hand-bound `Data#initialize` skip the check),
121
+ # so the extension is the authority: every value it reads back must be
122
+ # exactly its class and is checked again, TypeError or RangeError otherwise.
123
+ [Claimed, Retry, Failed, AlreadyFailed, Expired, Sweep, Entry].each do |value|
124
+ value.singleton_class.undef_method(:allocate)
125
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
126
+ end
127
+
128
+ class Outbox
129
+ private_class_method :__scope_of
130
+ end
131
+ end
@@ -0,0 +1,192 @@
1
+ module OutboxMachines
2
+ VERSION: String
3
+
4
+ # Private validating hooks behind the Data values: nil when the core has a
5
+ # value for the fields, TypeError/RangeError otherwise.
6
+ private def self.__retry: (Integer at) -> nil
7
+ private def self.__failure: (disposition disposition) -> nil
8
+ private def self.__claimed: (Integer id, Integer attempt, Integer lease_expires) -> nil
9
+ private def self.__expired: (Integer id, Integer attempt, disposition disposition) -> nil
10
+ private def self.__sweep: (Array[Expired] expired, Integer scanned, pass pass) -> nil
11
+ private def self.__entry: (Integer id, state state, Integer attempts, Integer? attempt, Integer available_at) -> nil
12
+ CAPACITY: Integer
13
+
14
+ type state = :pending | :claimed | :confirmed | :dead
15
+
16
+ # The core's `Disposition`: Retry(at), or :dead.
17
+ type disposition = Retry | :dead
18
+
19
+ # The core's `Disposition::Retry(at)`: pending again, claimable at or after
20
+ # the instant `at`, in nanoseconds. TypeError for a non-Integer, RangeError
21
+ # past what a Duration holds or negative.
22
+ class Retry < Data
23
+ attr_reader at: Integer
24
+ def self.new: (Integer at) -> Retry
25
+ | (at: Integer) -> Retry
26
+ end
27
+
28
+ # The core's `Failure::Failed(disposition)`: the live attempt is over.
29
+ # RangeError for a Symbol other than :dead, TypeError for anything else
30
+ # that is not a Retry (also for AlreadyFailed).
31
+ class Failed < Data
32
+ attr_reader disposition: disposition
33
+ def self.new: (disposition disposition) -> Failed
34
+ | (disposition: disposition) -> Failed
35
+ end
36
+
37
+ # The core's `Failure::AlreadyFailed(disposition)`: an idempotent repeat,
38
+ # same attempt and same retry_after, carrying the standing disposition;
39
+ # nothing changed.
40
+ class AlreadyFailed < Data
41
+ attr_reader disposition: disposition
42
+ def self.new: (disposition disposition) -> AlreadyFailed
43
+ | (disposition: disposition) -> AlreadyFailed
44
+ end
45
+
46
+ # Mirrors the core's `Entry`; `new` is held to `Entry::new` (RangeError
47
+ # when attempt is not nil exactly when attempts is 0, has sequence zero, or
48
+ # a non-pending record has no attempt; TypeError for a wrong type).
49
+ class Entry < Data
50
+ attr_reader id: Integer
51
+ attr_reader state: state
52
+ # Claims issued to this record so far; it dies at max_attempts.
53
+ attr_reader attempts: Integer
54
+ # Identity of the latest attempt, nil until the record is first claimed.
55
+ attr_reader attempt: Integer?
56
+ # Earliest instant, in nanoseconds, a pending record may be claimed.
57
+ attr_reader available_at: Integer
58
+ def self.new: (Integer id, state state, Integer attempts, Integer? attempt, Integer available_at) -> Entry
59
+ | (id: Integer, state: state, attempts: Integer, attempt: Integer?, available_at: Integer) -> Entry
60
+ end
61
+
62
+ # Mirrors the core's `Claimed`; `new` is held to `Claimed::new` (RangeError
63
+ # for attempt sequence zero or lease_expires 0; TypeError for a wrong type).
64
+ class Claimed < Data
65
+ attr_reader id: Integer
66
+ # Identity of the attempt: issued once per outbox and never reissued. It
67
+ # carries the outbox's scope in its top 16 bits above a sequence starting
68
+ # at 1, so scope zero issues 1, 2, 3. Not the record's attempt count.
69
+ attr_reader attempt: Integer
70
+ # Instant, in nanoseconds, from which expire_claims may reap the lease.
71
+ attr_reader lease_expires: Integer
72
+ def self.new: (Integer id, Integer attempt, Integer lease_expires) -> Claimed
73
+ | (id: Integer, attempt: Integer, lease_expires: Integer) -> Claimed
74
+ # The scope of the outbox that issued this attempt.
75
+ def scope: () -> Integer
76
+ end
77
+
78
+ # Mirrors the core's `Expired`; `new` is held to `Expired::new` (RangeError
79
+ # for attempt sequence zero; the disposition is checked as Failed's).
80
+ class Expired < Data
81
+ attr_reader id: Integer
82
+ attr_reader attempt: Integer
83
+ attr_reader disposition: disposition
84
+ def self.new: (Integer id, Integer attempt, disposition disposition) -> Expired
85
+ | (id: Integer, attempt: Integer, disposition: disposition) -> Expired
86
+ # The scope of the outbox that issued the reaped attempt.
87
+ def scope: () -> Integer
88
+ end
89
+
90
+ # The core's `Pass`: :complete once the cursor finished a full pass over
91
+ # every slot, cumulatively across calls; :partial until then.
92
+ type pass = :partial | :complete
93
+
94
+ # Mirrors the core's `Sweep`. `expired` holds the reaped claims themselves,
95
+ # where the core reports how many it wrote to the caller's buffer. `new`
96
+ # keeps a frozen copy of the Array; RangeError when it holds more than
97
+ # `scanned` or `pass` is another Symbol, TypeError for a non-Expired element
98
+ # or a non-Symbol pass.
99
+ class Sweep < Data
100
+ attr_reader expired: Array[Expired]
101
+ attr_reader scanned: Integer
102
+ attr_reader pass: pass
103
+ def self.new: (Array[Expired] expired, Integer scanned, pass pass) -> Sweep
104
+ | (expired: Array[Expired], scanned: Integer, pass: pass) -> Sweep
105
+ end
106
+
107
+ class Outbox
108
+ # Every refusal symbol, one per core `Refusal` variant, no catch-all. A
109
+ # refused call changed nothing. Each method below lists exactly the ones
110
+ # it can answer.
111
+ type refusal = :unknown | :stale | :not_terminal | :time_regression | :invalid_duration | :exhausted | :full
112
+ | :mismatch
113
+
114
+ # Every instant (`now`, `lease_expires`, a retry `at`) and every span
115
+ # (`lease`, `retry_after`) is Integer nanoseconds of the caller's monotonic
116
+ # clock, over the whole `Duration` range, so every instant the outbox
117
+ # answers (a `lease_expires` past 2**64-1 included) reads back as `now`. A
118
+ # non-Integer raises TypeError; negative or past `Duration::MAX`
119
+ # nanoseconds raises RangeError. A sum past that is :invalid_duration.
120
+
121
+ # An empty outbox in scope zero.
122
+ def self.new: (Integer max_attempts) -> Outbox
123
+ # An empty outbox whose attempt identities carry `scope`, an Integer in
124
+ # 0..65_535 (TypeError for a non-Integer, RangeError outside the range).
125
+ # An attempt from an outbox of another scope is always :stale.
126
+ def self.with_scope: (Integer max_attempts, Integer scope) -> Outbox
127
+ # An empty outbox of `scope` that continues the attempt sequence after
128
+ # `issued` identities, the count a previous incarnation read from #issued:
129
+ # the next claim carries sequence issued + 1. `issued` is an Integer in
130
+ # 0..2**48-1 (TypeError for a non-Integer, RangeError outside the range;
131
+ # the core answers None there). resumed(max_attempts, scope, 0) is
132
+ # with_scope(max_attempts, scope).
133
+ def self.resumed: (Integer max_attempts, Integer scope, Integer issued) -> Outbox
134
+ def scope: () -> Integer
135
+ # How many attempt identities this outbox has issued; also the sequence
136
+ # number of the latest one. Save it to restart with Outbox.resumed.
137
+ def issued: () -> Integer
138
+ # Private: what Claimed#scope and Expired#scope read, from exactly a
139
+ # Claimed or an Expired (TypeError otherwise). RangeError for an attempt
140
+ # of sequence zero.
141
+ private def self.__scope_of: (Claimed | Expired held) -> Integer
142
+ def capacity: () -> Integer
143
+ def max_attempts: () -> Integer
144
+ def size: () -> Integer
145
+ def empty?: () -> bool
146
+ # TypeError for a non-Symbol, RangeError for a Symbol naming no state.
147
+ def count: (state state) -> Integer
148
+ # The record with this id, or nil. Never refuses.
149
+ def get: (Integer id) -> Entry?
150
+
151
+ # Honoured: :enqueued (records now), or :duplicate for an id that is
152
+ # already present (records nothing).
153
+ def enqueue: (Integer id, Integer now) -> (:enqueued | :duplicate | :time_regression | :full)
154
+
155
+ # Honoured: a Claimed, or nil when nothing is due; both record now.
156
+ # :exhausted means a
157
+ # record is due but the outbox has issued every attempt identity of its
158
+ # scope, 2**48-1 of them; it cannot be reached in practice.
159
+ def claim: (Integer now, Integer lease) -> (Claimed | nil | :time_regression | :invalid_duration | :exhausted)
160
+
161
+ # Honoured: :confirmed, or :already_confirmed when this same attempt
162
+ # already confirmed the record (a repeat that changes nothing). :stale
163
+ # for an attempt this outbox never issued (another scope, or a sequence
164
+ # it has not reached) comes first, whatever the id. :unknown is an id
165
+ # the outbox does not hold, forgotten records included; :stale is
166
+ # an attempt that is neither the live one nor the confirming one, which
167
+ # includes an attempt of an earlier record that carried the same id.
168
+ def confirm: (Integer id, Integer attempt) -> (:confirmed | :already_confirmed | :unknown | :stale)
169
+
170
+ # Honoured: a Failed (records now), or an AlreadyFailed (records nothing) when `fail` already ended this
171
+ # same attempt with this same retry_after and no claim followed (a repeat
172
+ # that changes nothing and answers the standing disposition; `now` may
173
+ # differ). The disposition is a Retry carrying the instant the record is
174
+ # claimable again, or :dead once max_attempts claims are spent. :stale
175
+ # covers a superseded, confirmed or reaped attempt, one of an earlier
176
+ # record that carried the same id, and one this outbox never issued
177
+ # (another scope, or a sequence it has not reached; answered first,
178
+ # whatever the id); :mismatch is a repeat whose retry_after
179
+ # is not the one recorded.
180
+ def fail: (Integer id, Integer attempt, Integer now, Integer retry_after)
181
+ -> (Failed | AlreadyFailed | :unknown | :stale | :time_regression | :invalid_duration | :mismatch)
182
+
183
+ # Honoured: a Sweep of at most 16 Expired values, also when it reaped
184
+ # none; it always records now. A max_scan past what the platform's usize
185
+ # holds raises RangeError rather than being narrowed.
186
+ def expire_claims: (Integer now, Integer max_scan) -> (Sweep | :time_regression)
187
+
188
+ # Honoured: :forgotten, or :not_held for an id the outbox does not hold (a
189
+ # repeat that changes nothing). Never answers :unknown.
190
+ def forget: (Integer id) -> (:forgotten | :not_held | :not_terminal)
191
+ end
192
+ end
metadata ADDED
@@ -0,0 +1,66 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: outbox_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.8.1
5
+ platform: aarch64-linux
6
+ authors:
7
+ - Abdelkader Boudih
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
+ dependencies: []
13
+ description: 'Tracks every message owed to the outside world as pending, claimed by
14
+ one attempt, confirmed or dead. Each claim carries an attempt identity issued once
15
+ and never again, so a late worker cannot settle an attempt handed to someone else,
16
+ and a lease that runs out is reported as an unknown outcome, not a failure. Bound
17
+ to Ruby from the no_std outbox-machines crate: the delivery policy only, not a transactional
18
+ outbox, a queue or a retry engine.'
19
+ email:
20
+ - oss@seuros.com
21
+ executables: []
22
+ extensions: []
23
+ extra_rdoc_files: []
24
+ files:
25
+ - CHANGELOG.md
26
+ - LICENSE.txt
27
+ - README.md
28
+ - ext/outbox_machines_native/core/CHANGELOG.md
29
+ - ext/outbox_machines_native/core/README.md
30
+ - ext/outbox_machines_native/extconf.rb
31
+ - lib/outbox_machines.rb
32
+ - lib/outbox_machines/version.rb
33
+ - lib/outbox_machines_native/outbox_machines_native.so
34
+ - sig/outbox_machines.rbs
35
+ homepage: https://github.com/seuros/outbox_machines
36
+ licenses:
37
+ - MIT
38
+ metadata:
39
+ source_code_uri: https://github.com/seuros/outbox_machines
40
+ rubygems_mfa_required: 'true'
41
+ cargo_crate_name: outbox_machines_native
42
+ cargo_manifest_path: ext/outbox_machines_native/ffi/Cargo.toml
43
+ post_install_message:
44
+ rdoc_options: []
45
+ require_paths:
46
+ - lib
47
+ required_ruby_version: !ruby/object:Gem::Requirement
48
+ requirements:
49
+ - - ">="
50
+ - !ruby/object:Gem::Version
51
+ version: '4.0'
52
+ - - "<"
53
+ - !ruby/object:Gem::Version
54
+ version: 4.1.dev
55
+ required_rubygems_version: !ruby/object:Gem::Requirement
56
+ requirements:
57
+ - - ">="
58
+ - !ruby/object:Gem::Version
59
+ version: '0'
60
+ requirements: []
61
+ rubygems_version: 3.5.23
62
+ signing_key:
63
+ specification_version: 4
64
+ summary: 'Delivery ledger for an outbox: claims, leases and attempt identities for
65
+ Ruby'
66
+ test_files: []