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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +106 -0
- data/Cargo.lock +314 -0
- data/Cargo.toml +28 -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/Cargo.toml +23 -0
- data/ext/outbox_machines_native/core/README.md +226 -0
- data/ext/outbox_machines_native/core/src/lib.rs +558 -0
- data/ext/outbox_machines_native/core/src/refusal.rs +48 -0
- data/ext/outbox_machines_native/core/src/values.rs +298 -0
- data/ext/outbox_machines_native/extconf.rb +2 -0
- data/ext/outbox_machines_native/ffi/Cargo.toml +21 -0
- data/ext/outbox_machines_native/ffi/extconf.rb +14 -0
- data/ext/outbox_machines_native/ffi/src/classes.rs +37 -0
- data/ext/outbox_machines_native/ffi/src/init.rs +35 -0
- data/ext/outbox_machines_native/ffi/src/lib.rs +300 -0
- data/ext/outbox_machines_native/ffi/src/values.rs +149 -0
- data/lib/outbox_machines/version.rb +5 -0
- data/lib/outbox_machines.rb +131 -0
- data/sig/outbox_machines.rbs +192 -0
- metadata +92 -0
|
@@ -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,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
|