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 +7 -0
- data/CHANGELOG.md +106 -0
- data/LICENSE.txt +21 -0
- data/README.md +331 -0
- data/ext/outbox_machines_native/core/CHANGELOG.md +81 -0
- data/ext/outbox_machines_native/core/README.md +226 -0
- data/ext/outbox_machines_native/extconf.rb +2 -0
- data/lib/outbox_machines/version.rb +5 -0
- data/lib/outbox_machines.rb +131 -0
- data/lib/outbox_machines_native/outbox_machines_native.so +0 -0
- data/sig/outbox_machines.rbs +192 -0
- metadata +66 -0
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,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
|
|
Binary file
|
|
@@ -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: []
|