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,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,92 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: outbox_machines
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.8.1
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Abdelkader Boudih
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: rb_sys
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - "~>"
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: '0.9'
|
|
19
|
+
- - ">="
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: 0.9.130
|
|
22
|
+
type: :runtime
|
|
23
|
+
prerelease: false
|
|
24
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
25
|
+
requirements:
|
|
26
|
+
- - "~>"
|
|
27
|
+
- !ruby/object:Gem::Version
|
|
28
|
+
version: '0.9'
|
|
29
|
+
- - ">="
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: 0.9.130
|
|
32
|
+
description: 'Tracks every message owed to the outside world as pending, claimed by
|
|
33
|
+
one attempt, confirmed or dead. Each claim carries an attempt identity issued once
|
|
34
|
+
and never again, so a late worker cannot settle an attempt handed to someone else,
|
|
35
|
+
and a lease that runs out is reported as an unknown outcome, not a failure. Bound
|
|
36
|
+
to Ruby from the no_std outbox-machines crate: the delivery policy only, not a transactional
|
|
37
|
+
outbox, a queue or a retry engine.'
|
|
38
|
+
email:
|
|
39
|
+
- oss@seuros.com
|
|
40
|
+
executables: []
|
|
41
|
+
extensions:
|
|
42
|
+
- ext/outbox_machines_native/extconf.rb
|
|
43
|
+
extra_rdoc_files: []
|
|
44
|
+
files:
|
|
45
|
+
- CHANGELOG.md
|
|
46
|
+
- Cargo.lock
|
|
47
|
+
- Cargo.toml
|
|
48
|
+
- LICENSE.txt
|
|
49
|
+
- README.md
|
|
50
|
+
- ext/outbox_machines_native/core/CHANGELOG.md
|
|
51
|
+
- ext/outbox_machines_native/core/Cargo.toml
|
|
52
|
+
- ext/outbox_machines_native/core/README.md
|
|
53
|
+
- ext/outbox_machines_native/core/src/lib.rs
|
|
54
|
+
- ext/outbox_machines_native/core/src/refusal.rs
|
|
55
|
+
- ext/outbox_machines_native/core/src/values.rs
|
|
56
|
+
- ext/outbox_machines_native/extconf.rb
|
|
57
|
+
- ext/outbox_machines_native/ffi/Cargo.toml
|
|
58
|
+
- ext/outbox_machines_native/ffi/extconf.rb
|
|
59
|
+
- ext/outbox_machines_native/ffi/src/classes.rs
|
|
60
|
+
- ext/outbox_machines_native/ffi/src/init.rs
|
|
61
|
+
- ext/outbox_machines_native/ffi/src/lib.rs
|
|
62
|
+
- ext/outbox_machines_native/ffi/src/values.rs
|
|
63
|
+
- lib/outbox_machines.rb
|
|
64
|
+
- lib/outbox_machines/version.rb
|
|
65
|
+
- sig/outbox_machines.rbs
|
|
66
|
+
homepage: https://github.com/seuros/outbox_machines
|
|
67
|
+
licenses:
|
|
68
|
+
- MIT
|
|
69
|
+
metadata:
|
|
70
|
+
source_code_uri: https://github.com/seuros/outbox_machines
|
|
71
|
+
rubygems_mfa_required: 'true'
|
|
72
|
+
cargo_crate_name: outbox_machines_native
|
|
73
|
+
cargo_manifest_path: ext/outbox_machines_native/ffi/Cargo.toml
|
|
74
|
+
rdoc_options: []
|
|
75
|
+
require_paths:
|
|
76
|
+
- lib
|
|
77
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
78
|
+
requirements:
|
|
79
|
+
- - ">="
|
|
80
|
+
- !ruby/object:Gem::Version
|
|
81
|
+
version: 4.0.0
|
|
82
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
83
|
+
requirements:
|
|
84
|
+
- - ">="
|
|
85
|
+
- !ruby/object:Gem::Version
|
|
86
|
+
version: '0'
|
|
87
|
+
requirements: []
|
|
88
|
+
rubygems_version: 4.0.20
|
|
89
|
+
specification_version: 4
|
|
90
|
+
summary: 'Delivery ledger for an outbox: claims, leases and attempt identities for
|
|
91
|
+
Ruby'
|
|
92
|
+
test_files: []
|