outbox_machines 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,300 @@
1
+ //! Thin binding to the bounded outbox delivery policy.
2
+ mod classes;
3
+ mod init;
4
+ mod values;
5
+
6
+ use std::{cell::RefCell, num::NonZeroU32};
7
+
8
+ use magnus::{Error, RClass, Ruby, Symbol, Value, prelude::*, typed_data::Obj};
9
+ use matryona_machines::ruby::{
10
+ SymbolNames, Symbols, instant, integer, keep, nanoseconds, positive, symbol, which_fields,
11
+ };
12
+
13
+ use crate::classes::classes;
14
+ use outbox_machines::{
15
+ Confirmation, Disposition, Enqueue, Expired, Failure, Forgetting, Refusal, State,
16
+ };
17
+
18
+ /// Records one Ruby outbox holds.
19
+ const CAPACITY: usize = 64;
20
+ /// Most `Expired` values one `expire_claims` call answers.
21
+ const SWEEP_BUFFER: usize = 16;
22
+
23
+ fn range(ruby: &Ruby, message: &'static str) -> Error {
24
+ Error::new(ruby.exception_range_error(), message)
25
+ }
26
+
27
+ /// The scope an attempt identity carries: `Claimed#scope`, `Expired#scope`.
28
+ /// The value is read natively, exactly a `Claimed` or an `Expired` with its
29
+ /// attempt from the struct, never through a reader, and checked again:
30
+ /// `RangeError` for a sequence of zero, which `Marshal.load` can forge.
31
+ fn scope_of(ruby: &Ruby, value: Value) -> Result<u16, Error> {
32
+ let classes = classes(ruby)?;
33
+ let held = [classes.claimed.get(ruby), classes.expired.get(ruby)];
34
+ let message = "expected an OutboxMachines::Claimed or an OutboxMachines::Expired";
35
+ let (_, [_, attempt, _]) = which_fields::<3>(ruby, value, &held, message)?;
36
+ Expired::new(0, integer(attempt, "attempt")?, Disposition::Dead)
37
+ .map(|expired| expired.scope())
38
+ .ok_or_else(|| range(ruby, "attempt must have a sequence of at least 1"))
39
+ }
40
+
41
+ #[magnus::wrap(class = "OutboxMachines::Outbox", free_immediately, size)]
42
+ struct Outbox {
43
+ core: RefCell<outbox_machines::Outbox<CAPACITY>>,
44
+ }
45
+
46
+ /// An honoured answer that is a bare symbol, or the refusal's symbol.
47
+ fn answer(ruby: &Ruby, outcome: Result<&str, Refusal>) -> Value {
48
+ match outcome {
49
+ Ok(name) => symbol(ruby, name).as_value(),
50
+ Err(e) => refusal(ruby, e),
51
+ }
52
+ }
53
+
54
+ matryona_machines::symbols! {
55
+ /// The core's refusals as Symbols: the snake case of each variant.
56
+ Refusals for Refusal as "a refusal" {
57
+ Unknown => "unknown",
58
+ Stale => "stale",
59
+ NotTerminal => "not_terminal",
60
+ TimeRegression => "time_regression",
61
+ InvalidDuration => "invalid_duration",
62
+ Full => "full",
63
+ Exhausted => "exhausted",
64
+ Mismatch => "mismatch",
65
+ }
66
+ }
67
+
68
+ fn refusal(ruby: &Ruby, refusal: Refusal) -> Value {
69
+ Refusals::symbol(ruby, refusal).as_value()
70
+ }
71
+
72
+ fn state_symbol(ruby: &Ruby, state: State) -> Symbol {
73
+ values::States::symbol(ruby, state)
74
+ }
75
+
76
+ /// `retry` is the `Retry` class, resolved at init.
77
+ fn disposition(ruby: &Ruby, retry: RClass, value: Disposition) -> Result<Value, Error> {
78
+ Ok(match value {
79
+ Disposition::Retry(at) => retry.funcall("new", (nanoseconds(ruby, at),))?,
80
+ Disposition::Dead => values::Dispositions::symbol(ruby, &value).as_value(),
81
+ })
82
+ }
83
+
84
+ // Refusals are answers (symbols), not exceptions. Only malformed input raises.
85
+ impl Outbox {
86
+ fn new(ruby: &Ruby, max_attempts: Value) -> Result<Self, Error> {
87
+ Self::build(ruby, Self::max(max_attempts)?, 0, 0)
88
+ }
89
+
90
+ fn with_scope(ruby: &Ruby, max_attempts: Value, scope: Value) -> Result<Self, Error> {
91
+ let max = Self::max(max_attempts)?;
92
+ Self::build(ruby, max, integer(scope, "scope")?, 0)
93
+ }
94
+
95
+ fn resumed(
96
+ ruby: &Ruby,
97
+ max_attempts: Value,
98
+ scope: Value,
99
+ issued: Value,
100
+ ) -> Result<Self, Error> {
101
+ let max = Self::max(max_attempts)?;
102
+ let scope = integer(scope, "scope")?;
103
+ Self::build(ruby, max, scope, integer(issued, "issued")?)
104
+ }
105
+
106
+ fn max(max_attempts: Value) -> Result<NonZeroU32, Error> {
107
+ positive(max_attempts, "max_attempts")
108
+ }
109
+
110
+ /// The core answers `None` for a count past the sequence; that is
111
+ /// malformed input, so it raises like every other argument out of range.
112
+ fn build(ruby: &Ruby, max: NonZeroU32, scope: u16, issued: u64) -> Result<Self, Error> {
113
+ let core = outbox_machines::Outbox::resumed(max, scope, issued)
114
+ .ok_or_else(|| range(ruby, "issued must be in 0..2**48-1"))?;
115
+ Ok(Self {
116
+ core: RefCell::new(core),
117
+ })
118
+ }
119
+ fn issued(&self) -> u64 {
120
+ self.core.borrow().issued()
121
+ }
122
+
123
+ fn scope(&self) -> u16 {
124
+ self.core.borrow().scope()
125
+ }
126
+
127
+ fn capacity(&self) -> usize {
128
+ self.core.borrow().capacity()
129
+ }
130
+
131
+ fn max_attempts(&self) -> u32 {
132
+ self.core.borrow().max_attempts()
133
+ }
134
+
135
+ fn size(&self) -> usize {
136
+ self.core.borrow().len()
137
+ }
138
+
139
+ fn is_empty(&self) -> bool {
140
+ self.core.borrow().is_empty()
141
+ }
142
+
143
+ fn enqueue(ruby: &Ruby, this: Obj<Self>, id: Value, now: Value) -> Result<Value, Error> {
144
+ this.check_frozen()?;
145
+ let (id, now) = (integer(id, "id")?, instant(now, "now")?);
146
+ let outcome = this.core.borrow_mut().enqueue(id, now);
147
+ Ok(answer(
148
+ ruby,
149
+ outcome.map(|done| match done {
150
+ Enqueue::Enqueued => "enqueued",
151
+ Enqueue::Duplicate => "duplicate",
152
+ }),
153
+ ))
154
+ }
155
+
156
+ /// A `Claimed`, `nil` when nothing is due, or a refusal symbol.
157
+ fn claim(ruby: &Ruby, this: Obj<Self>, now: Value, lease: Value) -> Result<Value, Error> {
158
+ this.check_frozen()?;
159
+ let (now, lease) = (instant(now, "now")?, instant(lease, "lease")?);
160
+ let class = classes(ruby)?.claimed.get(ruby);
161
+ keep(
162
+ ruby,
163
+ this,
164
+ &this.core,
165
+ |core| core.claim(now, lease),
166
+ |claimed| match claimed {
167
+ Ok(Some(claimed)) => {
168
+ let expires = nanoseconds(ruby, claimed.lease_expires());
169
+ class.funcall("new", (claimed.id(), claimed.attempt(), expires))
170
+ }
171
+ Ok(None) => Ok(ruby.qnil().as_value()),
172
+ Err(e) => Ok(refusal(ruby, e)),
173
+ },
174
+ )
175
+ }
176
+
177
+ fn confirm(ruby: &Ruby, this: Obj<Self>, id: Value, attempt: Value) -> Result<Value, Error> {
178
+ this.check_frozen()?;
179
+ let (id, attempt) = (integer(id, "id")?, integer(attempt, "attempt")?);
180
+ let outcome = this.core.borrow_mut().confirm(id, attempt);
181
+ Ok(answer(
182
+ ruby,
183
+ outcome.map(|done| match done {
184
+ Confirmation::Confirmed => "confirmed",
185
+ Confirmation::AlreadyConfirmed => "already_confirmed",
186
+ }),
187
+ ))
188
+ }
189
+
190
+ fn fail(
191
+ ruby: &Ruby,
192
+ this: Obj<Self>,
193
+ id: Value,
194
+ attempt: Value,
195
+ now: Value,
196
+ retry_after: Value,
197
+ ) -> Result<Value, Error> {
198
+ this.check_frozen()?;
199
+ let (id, attempt) = (integer(id, "id")?, integer(attempt, "attempt")?);
200
+ let (now, after) = (instant(now, "now")?, instant(retry_after, "retry_after")?);
201
+ let classes = classes(ruby)?;
202
+ keep(
203
+ ruby,
204
+ this,
205
+ &this.core,
206
+ |core| core.fail(id, attempt, now, after),
207
+ |failure| {
208
+ let (class, value) = match failure {
209
+ Ok(Failure::Failed(value)) => (classes.failed, value),
210
+ Ok(Failure::AlreadyFailed(value)) => (classes.already_failed, value),
211
+ Err(e) => return Ok(refusal(ruby, e)),
212
+ };
213
+ let retry = classes.retry.get(ruby);
214
+ class
215
+ .get(ruby)
216
+ .funcall("new", (disposition(ruby, retry, value)?,))
217
+ },
218
+ )
219
+ }
220
+
221
+ /// A `Sweep` holding up to 16 `Expired` values, or a refusal symbol.
222
+ /// `RangeError` for a `max_scan` past `usize`, before the core runs.
223
+ fn expire_claims(
224
+ ruby: &Ruby,
225
+ this: Obj<Self>,
226
+ now: Value,
227
+ max_scan: Value,
228
+ ) -> Result<Value, Error> {
229
+ this.check_frozen()?;
230
+ let (now, scan) = (instant(now, "now")?, integer(max_scan, "max_scan")?);
231
+ let classes = classes(ruby)?;
232
+ let (retry, expired_class) = (classes.retry.get(ruby), classes.expired.get(ruby));
233
+ keep(
234
+ ruby,
235
+ this,
236
+ &this.core,
237
+ |core| {
238
+ // The core writes into a Rust buffer; values are built after.
239
+ let mut out = [Expired::default(); SWEEP_BUFFER];
240
+ core.expire_claims(now, scan, &mut out)
241
+ .map(|sweep| (sweep, out))
242
+ },
243
+ |swept| {
244
+ let (sweep, out) = match swept {
245
+ Ok(swept) => swept,
246
+ Err(e) => return Ok(refusal(ruby, e)),
247
+ };
248
+ let expired = ruby.ary_new_capa(sweep.expired());
249
+ for entry in out.iter().take(sweep.expired()) {
250
+ let fate = disposition(ruby, retry, entry.disposition())?;
251
+ let fields = (entry.id(), entry.attempt(), fate);
252
+ expired.push(expired_class.funcall::<_, _, Value>("new", fields)?)?;
253
+ }
254
+ expired.freeze();
255
+ let pass = values::Passes::symbol(ruby, sweep.pass());
256
+ classes
257
+ .sweep
258
+ .get(ruby)
259
+ .funcall("new", (expired, sweep.scanned(), pass))
260
+ },
261
+ )
262
+ }
263
+
264
+ fn forget(ruby: &Ruby, this: Obj<Self>, id: Value) -> Result<Value, Error> {
265
+ this.check_frozen()?;
266
+ let id = integer(id, "id")?;
267
+ let outcome = this.core.borrow_mut().forget(id);
268
+ Ok(answer(
269
+ ruby,
270
+ outcome.map(|done| match done {
271
+ Forgetting::Forgotten => "forgotten",
272
+ Forgetting::NotHeld => "not_held",
273
+ }),
274
+ ))
275
+ }
276
+
277
+ /// An `Entry`, or `nil` when no record carries the id.
278
+ fn get(ruby: &Ruby, this: Obj<Self>, id: Value) -> Result<Value, Error> {
279
+ let id = integer(id, "id")?;
280
+ let class = classes(ruby)?.entry.get(ruby);
281
+ let Some(entry) = this.core.borrow().get(id) else {
282
+ return Ok(ruby.qnil().as_value());
283
+ };
284
+ let state = state_symbol(ruby, entry.state());
285
+ let available_at = nanoseconds(ruby, entry.available_at());
286
+ let fields = (
287
+ entry.id(),
288
+ state,
289
+ entry.attempts(),
290
+ entry.attempt(),
291
+ available_at,
292
+ );
293
+ class.funcall("new", fields)
294
+ }
295
+
296
+ fn count(ruby: &Ruby, this: Obj<Self>, state: Value) -> Result<usize, Error> {
297
+ let state = values::States::parse(ruby, state)?;
298
+ Ok(this.core.borrow().count(state))
299
+ }
300
+ }
@@ -0,0 +1,149 @@
1
+ //! Private hooks behind the `Data` values: each one is valid or does not
2
+ //! exist. A wrong type raises `TypeError`; a value the core's constructor
3
+ //! answers `None` for raises `RangeError`.
4
+ use magnus::{Error, Ruby, Value, prelude::*};
5
+ use matryona_machines::ruby::{
6
+ Choice, Refused, Symbols, exact_array, exact_fields, instant, integer, optional,
7
+ symbol_or_fields_why,
8
+ };
9
+ use outbox_machines::{Claimed, Disposition, Entry, Expired, Pass, State, Sweep};
10
+
11
+ use crate::{classes::classes, range};
12
+
13
+ matryona_machines::symbols! {
14
+ /// The core's record states as Symbols: `TypeError` for a non-Symbol,
15
+ /// `RangeError` for a Symbol that names no state.
16
+ pub States for State as "state" {
17
+ Pending => "pending",
18
+ Claimed => "claimed",
19
+ Confirmed => "confirmed",
20
+ Dead => "dead",
21
+ }
22
+ }
23
+
24
+ matryona_machines::symbols! {
25
+ /// The core's sweep passes as Symbols.
26
+ pub Passes for Pass as "pass" {
27
+ Partial => "partial",
28
+ Complete => "complete",
29
+ }
30
+ }
31
+
32
+ matryona_machines::symbols! {
33
+ /// The core's dispositions as Symbols: `:dead` reads back; a retry is
34
+ /// its `Retry`.
35
+ pub Dispositions for Disposition as "a disposition" => names_only {
36
+ Retry(..) => "retry",
37
+ Dead => "dead",
38
+ }
39
+ }
40
+
41
+ /// A `Retry` or `:dead`, read back into the core's `Disposition`. A `Retry`
42
+ /// must be exactly a `Retry`, and its instant is read and checked again.
43
+ fn disposition(ruby: &Ruby, value: Value) -> Result<Disposition, Error> {
44
+ let retry = [classes(ruby)?.retry.get(ruby)];
45
+ let message = |why: Refused<'_>| match why {
46
+ Refused::UnknownSymbol(symbol) => format!("unknown disposition {}", symbol.inspect()),
47
+ _ => "disposition must be a Retry or :dead".into(),
48
+ };
49
+ Ok(
50
+ match symbol_or_fields_why(ruby, value, Dispositions, &retry, message)? {
51
+ Choice::Symbol(disposition) => disposition,
52
+ Choice::Struct(_, [at]) => Disposition::Retry(instant(at, "at")?),
53
+ },
54
+ )
55
+ }
56
+
57
+ /// Any instant is a valid `Disposition::Retry`; the conversion is the check.
58
+ fn retry(at: Value) -> Result<(), Error> {
59
+ instant(at, "at").map(drop)
60
+ }
61
+
62
+ /// Any disposition is a valid `Failure`; reading it back is the check.
63
+ fn failure(ruby: &Ruby, value: Value) -> Result<(), Error> {
64
+ disposition(ruby, value).map(drop)
65
+ }
66
+
67
+ fn claimed(ruby: &Ruby, id: Value, attempt: Value, lease_expires: Value) -> Result<(), Error> {
68
+ let (id, attempt) = (integer(id, "id")?, integer(attempt, "attempt")?);
69
+ Claimed::new(id, attempt, instant(lease_expires, "lease_expires")?)
70
+ .map(drop)
71
+ .ok_or_else(|| {
72
+ let message =
73
+ "attempt must have a sequence of at least 1 and lease_expires be positive";
74
+ range(ruby, message)
75
+ })
76
+ }
77
+
78
+ fn expired(ruby: &Ruby, id: Value, attempt: Value, fate: Value) -> Result<(), Error> {
79
+ let (id, attempt) = (integer(id, "id")?, integer(attempt, "attempt")?);
80
+ Expired::new(id, attempt, disposition(ruby, fate)?)
81
+ .map(drop)
82
+ .ok_or_else(|| range(ruby, "attempt must have a sequence of at least 1"))
83
+ }
84
+
85
+ /// One element of a `Sweep`: exactly an `Expired`, its fields read natively
86
+ /// and checked again by `Expired::new`, so a forged one is refused.
87
+ fn reaped(ruby: &Ruby, row: Value) -> Result<(), Error> {
88
+ let message = "expired must be an Array of Expired";
89
+ let [id, attempt, fate] =
90
+ exact_fields::<3>(ruby, row, classes(ruby)?.expired.get(ruby), message)?;
91
+ expired(ruby, id, attempt, fate)
92
+ }
93
+
94
+ fn sweep(ruby: &Ruby, rows: Value, scanned: Value, done: Value) -> Result<(), Error> {
95
+ let scanned = integer(scanned, "scanned")?;
96
+ // Iterated natively: an Array subclass could answer `all?` for itself.
97
+ let rows = exact_array(ruby, rows, "expired must be an Array of Expired")?;
98
+ for index in 0..rows.len() {
99
+ let index = isize::try_from(index).map_err(|_| range(ruby, "too many rows"))?;
100
+ reaped(ruby, rows.entry(index)?)?;
101
+ }
102
+ let done = Passes::parse(ruby, done)?;
103
+ Sweep::new(rows.len(), scanned, done)
104
+ .map(drop)
105
+ .ok_or_else(|| {
106
+ range(
107
+ ruby,
108
+ "a sweep reaps no more claims than the slots it scanned",
109
+ )
110
+ })
111
+ }
112
+
113
+ fn entry(
114
+ ruby: &Ruby,
115
+ id: Value,
116
+ held: Value,
117
+ attempts: Value,
118
+ attempt: Value,
119
+ available_at: Value,
120
+ ) -> Result<(), Error> {
121
+ let id = integer(id, "id")?;
122
+ let attempts = integer(attempts, "attempts")?;
123
+ let attempt = optional(attempt, "attempt")?;
124
+ let available_at = instant(available_at, "available_at")?;
125
+ Entry::new(
126
+ id,
127
+ States::parse(ruby, held)?,
128
+ attempts,
129
+ attempt,
130
+ available_at,
131
+ )
132
+ .map(drop)
133
+ .ok_or_else(|| {
134
+ let message = "attempt is nil exactly when attempts is 0, has a sequence of at least \
135
+ 1, and only a :pending record is unclaimed";
136
+ range(ruby, message)
137
+ })
138
+ }
139
+
140
+ pub fn define(module: magnus::RModule) -> Result<(), Error> {
141
+ use magnus::function;
142
+ module.define_singleton_method("__retry", function!(retry, 1))?;
143
+ module.define_singleton_method("__failure", function!(failure, 1))?;
144
+ module.define_singleton_method("__claimed", function!(claimed, 3))?;
145
+ module.define_singleton_method("__expired", function!(expired, 3))?;
146
+ module.define_singleton_method("__sweep", function!(sweep, 3))?;
147
+ module.define_singleton_method("__entry", function!(entry, 5))?;
148
+ Ok(())
149
+ }
@@ -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