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,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: []