typed_bus 0.0.1 → 0.1.0
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 +4 -4
- data/CHANGELOG.md +158 -4
- data/LICENSE +21 -0
- data/README.md +25 -13
- data/lib/typed_bus/channel.rb +170 -91
- data/lib/typed_bus/configuration.rb +51 -8
- data/lib/typed_bus/dead_letter_queue.rb +32 -8
- data/lib/typed_bus/delivery.rb +1 -1
- data/lib/typed_bus/delivery_tracker.rb +28 -19
- data/lib/typed_bus/message_bus.rb +55 -14
- data/lib/typed_bus/version.rb +1 -1
- data/lib/typed_bus.rb +3 -0
- metadata +23 -62
- data/.envrc +0 -1
- data/.github/workflows/deploy-github-pages.yml +0 -52
- data/.github/workflows/deploy-yard-docs.yml +0 -52
- data/.irbrc +0 -10
- data/COMMITS.md +0 -196
- data/Rakefile +0 -12
- data/docs/api/channel.md +0 -94
- data/docs/api/configuration.md +0 -90
- data/docs/api/dead-letter-queue.md +0 -52
- data/docs/api/delivery-tracker.md +0 -66
- data/docs/api/delivery.md +0 -73
- data/docs/api/index.md +0 -45
- data/docs/api/message-bus.md +0 -101
- data/docs/api/stats.md +0 -50
- data/docs/architecture/concurrency-model.md +0 -38
- data/docs/architecture/configuration-cascade.md +0 -76
- data/docs/architecture/index.md +0 -7
- data/docs/architecture/publish-flow.md +0 -67
- data/docs/assets/css/custom.css +0 -11
- data/docs/assets/images/typed_bus.gif +0 -0
- data/docs/assets/images/typed_bus.jpg +0 -0
- data/docs/assets/images/typed_bus.mp4 +0 -0
- data/docs/concepts.md +0 -47
- data/docs/examples/index.md +0 -37
- data/docs/getting-started/configuration.md +0 -87
- data/docs/getting-started/index.md +0 -7
- data/docs/getting-started/installation.md +0 -33
- data/docs/getting-started/quick-start.md +0 -51
- data/docs/guides/adaptive-throttling.md +0 -76
- data/docs/guides/backpressure.md +0 -58
- data/docs/guides/dead-letter-queues.md +0 -78
- data/docs/guides/delivery-and-ack.md +0 -89
- data/docs/guides/error-handling.md +0 -91
- data/docs/guides/graceful-shutdown.md +0 -75
- data/docs/guides/index.md +0 -13
- data/docs/guides/logging.md +0 -93
- data/docs/guides/stats-and-monitoring.md +0 -75
- data/docs/guides/typed-channels.md +0 -63
- data/docs/index.md +0 -56
- data/examples/00_config.rb +0 -156
- data/examples/01_basic_usage.rb +0 -26
- data/examples/02_typed_channels.rb +0 -41
- data/examples/03_multiple_subscribers.rb +0 -44
- data/examples/04_nack_and_dead_letters.rb +0 -47
- data/examples/05_delivery_timeout.rb +0 -44
- data/examples/06_backpressure.rb +0 -32
- data/examples/07_message_bus.rb +0 -55
- data/examples/08_error_handling.rb +0 -82
- data/examples/09_stats_and_monitoring.rb +0 -71
- data/examples/10_concurrent_pipeline.rb +0 -116
- data/examples/11_logging_basic.rb +0 -60
- data/examples/12_logging_failures.rb +0 -65
- data/examples/13_logging_backpressure.rb +0 -56
- data/examples/14_adaptive_throttling.rb +0 -101
- data/examples/README.md +0 -27
- data/examples/temp.md +0 -95
- data/mkdocs.yml +0 -183
data/lib/typed_bus/channel.rb
CHANGED
|
@@ -13,29 +13,36 @@ module TypedBus
|
|
|
13
13
|
attr_reader :name, :type, :dead_letter_queue
|
|
14
14
|
|
|
15
15
|
# @param name [Symbol] channel name
|
|
16
|
-
# @param type [Class, nil] optional type constraint for messages
|
|
17
|
-
# @param timeout [Numeric] seconds before delivery auto-nacks (default: 30)
|
|
18
|
-
# @param max_pending [Integer, nil] backpressure limit
|
|
16
|
+
# @param type [Class, Module, nil] optional type constraint for messages
|
|
17
|
+
# @param timeout [Numeric, nil] seconds before delivery auto-nacks (default: 30); nil = never auto-nack
|
|
18
|
+
# @param max_pending [Integer, nil] backpressure limit; a positive Integer or nil (unbounded)
|
|
19
19
|
# @param stats [Stats, nil] optional stats tracker for counters
|
|
20
|
-
# @param throttle [
|
|
20
|
+
# @param throttle [Numeric, nil] remaining-capacity ratio at which asymptotic backoff begins;
|
|
21
|
+
# 0 or nil = off, else strictly between 0 and 1
|
|
22
|
+
# @raise [ArgumentError] if type, max_pending, or throttle is invalid
|
|
21
23
|
def initialize(name, type: nil, timeout: 30, max_pending: nil, stats: nil, throttle: 0.0)
|
|
22
24
|
@name = name
|
|
23
25
|
@type = type
|
|
24
26
|
@timeout = timeout
|
|
25
27
|
@max_pending = max_pending
|
|
26
28
|
@stats = stats
|
|
27
|
-
@throttle = throttle.to_f
|
|
29
|
+
@throttle = Configuration.validate_throttle!(throttle, " on channel :#{name}").to_f
|
|
28
30
|
@subscribers = {}
|
|
29
31
|
@next_subscriber_id = 0
|
|
30
|
-
@pending_deliveries = {}
|
|
32
|
+
@pending_deliveries = {}.compare_by_identity
|
|
31
33
|
@active_deliveries = []
|
|
32
34
|
@closed = false
|
|
33
35
|
@dead_letter_queue = DeadLetterQueue.new
|
|
34
36
|
@backpressure = Async::Condition.new
|
|
35
37
|
|
|
38
|
+
validate_type_config!
|
|
39
|
+
Configuration.validate_max_pending!(@max_pending)
|
|
36
40
|
validate_throttle_config!
|
|
37
41
|
|
|
38
|
-
log(:info,
|
|
42
|
+
log(:info,
|
|
43
|
+
"channel created (type=#{type || 'any'}, timeout=#{timeout ? "#{timeout}s" : 'none'}, " \
|
|
44
|
+
"max_pending=#{max_pending || 'unbounded'}, " \
|
|
45
|
+
"throttle=#{@throttle.positive? ? "#{(@throttle * 100).round}%" : 'off'})")
|
|
39
46
|
end
|
|
40
47
|
|
|
41
48
|
# Publish a message to all current subscribers.
|
|
@@ -44,77 +51,34 @@ module TypedBus
|
|
|
44
51
|
#
|
|
45
52
|
# @param message [Object]
|
|
46
53
|
# @raise [ArgumentError] if message doesn't match type constraint
|
|
47
|
-
# @raise [RuntimeError] if channel is closed
|
|
48
|
-
#
|
|
54
|
+
# @raise [RuntimeError] if channel is closed, including while the
|
|
55
|
+
# publisher was waiting on throttle or backpressure
|
|
56
|
+
# @return [DeliveryTracker, nil] the tracker, or nil when there are no
|
|
57
|
+
# subscribers and the message was dead-lettered
|
|
49
58
|
def publish(message)
|
|
50
|
-
|
|
59
|
+
admit!(message)
|
|
51
60
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
61
|
+
# Snapshot ids and handlers together so every id the tracker waits on
|
|
62
|
+
# gets a Delivery, even if a handler unsubscribes someone mid-publish.
|
|
63
|
+
subscribers = @subscribers.to_a
|
|
64
|
+
return dead_letter_no_subscribers(message) if subscribers.empty?
|
|
55
65
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
if subscriber_ids.empty?
|
|
59
|
-
log(:warn, "published with no subscribers, routing to DLQ (message=#{message.class})")
|
|
60
|
-
dead_letter_no_subscribers(message)
|
|
61
|
-
return nil
|
|
62
|
-
end
|
|
63
|
-
|
|
64
|
-
log(:info, "published message (type=#{message.class}, subscribers=#{subscriber_ids.size})")
|
|
65
|
-
|
|
66
|
-
tracker = DeliveryTracker.new(message, channel_name: @name, subscriber_ids: subscriber_ids)
|
|
67
|
-
@pending_deliveries[tracker.object_id] = tracker
|
|
68
|
-
|
|
69
|
-
tracker.on_complete { record_stat(:delivered) }
|
|
70
|
-
tracker.on_resolved { tracker_resolved(tracker) }
|
|
71
|
-
|
|
72
|
-
subscriber_ids.each do |sub_id|
|
|
73
|
-
handler = @subscribers[sub_id]
|
|
74
|
-
next unless handler
|
|
75
|
-
|
|
76
|
-
delivery = Delivery.new(
|
|
77
|
-
message,
|
|
78
|
-
channel_name: @name,
|
|
79
|
-
subscriber_id: sub_id,
|
|
80
|
-
timeout: @timeout,
|
|
81
|
-
on_ack: ->(_id) {
|
|
82
|
-
@active_deliveries.delete(delivery)
|
|
83
|
-
tracker.ack(sub_id)
|
|
84
|
-
},
|
|
85
|
-
on_nack: ->(_id) {
|
|
86
|
-
@active_deliveries.delete(delivery)
|
|
87
|
-
tracker.nack(sub_id)
|
|
88
|
-
@dead_letter_queue.push(delivery)
|
|
89
|
-
record_stat(:dead_lettered)
|
|
90
|
-
if delivery.timed_out?
|
|
91
|
-
record_stat(:timed_out)
|
|
92
|
-
else
|
|
93
|
-
record_stat(:nacked)
|
|
94
|
-
end
|
|
95
|
-
}
|
|
96
|
-
)
|
|
97
|
-
|
|
98
|
-
@active_deliveries << delivery
|
|
99
|
-
log(:debug, "notifying subscriber ##{sub_id} (message=#{message.class})")
|
|
100
|
-
|
|
101
|
-
Async do
|
|
102
|
-
handler.call(delivery)
|
|
103
|
-
rescue StandardError => e
|
|
104
|
-
log(:error, "subscriber ##{sub_id} raised #{e.class}: #{e.message}")
|
|
105
|
-
delivery.nack! if delivery.pending?
|
|
106
|
-
end
|
|
107
|
-
end
|
|
66
|
+
log(:info, "published message (type=#{message.class}, subscribers=#{subscribers.size})")
|
|
108
67
|
|
|
68
|
+
tracker = track(message, subscribers.map(&:first))
|
|
69
|
+
subscribers.each { |sub_id, handler| deliver(tracker, sub_id, handler) }
|
|
109
70
|
tracker
|
|
110
71
|
end
|
|
111
72
|
|
|
112
73
|
# Subscribe to messages on this channel.
|
|
113
74
|
# The block receives a +Delivery+ object.
|
|
114
75
|
#
|
|
76
|
+
# @raise [ArgumentError] if no block is given
|
|
77
|
+
# @raise [RuntimeError] if channel is closed
|
|
115
78
|
# @return [Integer] subscriber id (use for unsubscribe)
|
|
116
79
|
def subscribe(&block)
|
|
117
|
-
raise "Channel :#{@name}
|
|
80
|
+
raise ArgumentError, "Channel :#{@name} subscribe requires a block" unless block
|
|
81
|
+
ensure_open!
|
|
118
82
|
|
|
119
83
|
id = next_subscriber_id
|
|
120
84
|
@subscribers[id] = block
|
|
@@ -126,14 +90,10 @@ module TypedBus
|
|
|
126
90
|
#
|
|
127
91
|
# @param id_or_block [Integer, Proc]
|
|
128
92
|
def unsubscribe(id_or_block)
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
@subscribers.delete(id_or_block)
|
|
132
|
-
log(:info, "subscriber ##{id_or_block} unsubscribed (remaining=#{@subscribers.size})")
|
|
93
|
+
if id_or_block.is_a?(Integer)
|
|
94
|
+
unsubscribe_id(id_or_block)
|
|
133
95
|
else
|
|
134
|
-
|
|
135
|
-
@subscribers.delete_if { |_, v| v == id_or_block }
|
|
136
|
-
log(:info, "subscriber unsubscribed by reference (removed=#{before - @subscribers.size}, remaining=#{@subscribers.size})")
|
|
96
|
+
unsubscribe_handler(id_or_block)
|
|
137
97
|
end
|
|
138
98
|
end
|
|
139
99
|
|
|
@@ -154,6 +114,10 @@ module TypedBus
|
|
|
154
114
|
|
|
155
115
|
# Close the channel. Stops accepting new publishes/subscribes.
|
|
156
116
|
# Pending deliveries are force-nacked (routed to DLQ with stats).
|
|
117
|
+
# Publishers waiting for capacity are always woken and raise the
|
|
118
|
+
# closed error, even if an on_dead_letter callback raises here.
|
|
119
|
+
# Every pending delivery is nacked even if an on_dead_letter callback
|
|
120
|
+
# raises; the first such error is re-raised once all are handled.
|
|
157
121
|
def close
|
|
158
122
|
return if @closed
|
|
159
123
|
|
|
@@ -161,6 +125,7 @@ module TypedBus
|
|
|
161
125
|
pending = @active_deliveries.count(&:pending?)
|
|
162
126
|
log(:info, "closing (force-nacking #{pending} pending deliveries)")
|
|
163
127
|
force_nack_pending
|
|
128
|
+
ensure
|
|
164
129
|
@backpressure.signal
|
|
165
130
|
end
|
|
166
131
|
|
|
@@ -170,7 +135,8 @@ module TypedBus
|
|
|
170
135
|
|
|
171
136
|
# Hard reset: cancel all timeout tasks, discard all pending state and DLQ.
|
|
172
137
|
def clear!
|
|
173
|
-
log(:info,
|
|
138
|
+
log(:info,
|
|
139
|
+
"clearing all state (active=#{@active_deliveries.size}, pending=#{@pending_deliveries.size}, dlq=#{@dead_letter_queue.size})")
|
|
174
140
|
@active_deliveries.each(&:cancel_timeout)
|
|
175
141
|
@active_deliveries.clear
|
|
176
142
|
@pending_deliveries.clear
|
|
@@ -180,16 +146,41 @@ module TypedBus
|
|
|
180
146
|
|
|
181
147
|
private
|
|
182
148
|
|
|
183
|
-
def
|
|
184
|
-
|
|
149
|
+
def ensure_open!
|
|
150
|
+
raise "Channel :#{@name} is closed" if @closed
|
|
151
|
+
end
|
|
185
152
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
153
|
+
# Everything that can reject or delay a publish before fan-out.
|
|
154
|
+
def admit!(message)
|
|
155
|
+
ensure_open!
|
|
156
|
+
validate_type!(message)
|
|
157
|
+
apply_throttle! if throttled?
|
|
158
|
+
wait_for_capacity if bounded?
|
|
159
|
+
ensure_open! # the channel may have closed while we waited
|
|
160
|
+
end
|
|
189
161
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
162
|
+
def unsubscribe_id(id)
|
|
163
|
+
@subscribers.delete(id)
|
|
164
|
+
log(:info, "subscriber ##{id} unsubscribed (remaining=#{@subscribers.size})")
|
|
165
|
+
end
|
|
166
|
+
|
|
167
|
+
def unsubscribe_handler(handler)
|
|
168
|
+
ids = @subscribers.select { |_, registered| registered == handler }.keys
|
|
169
|
+
ids.each { |id| @subscribers.delete(id) }
|
|
170
|
+
log(:info, "subscriber unsubscribed by reference (removed=#{ids.size}, remaining=#{@subscribers.size})")
|
|
171
|
+
end
|
|
172
|
+
|
|
173
|
+
def validate_type_config!
|
|
174
|
+
return if @type.nil? || @type.is_a?(Module)
|
|
175
|
+
|
|
176
|
+
raise ArgumentError, "type must be a Class or Module, got #{@type.inspect} on channel :#{@name}"
|
|
177
|
+
end
|
|
178
|
+
|
|
179
|
+
# The range is checked by Configuration.validate_throttle! in #initialize.
|
|
180
|
+
def validate_throttle_config!
|
|
181
|
+
return if @throttle == 0.0 || bounded?
|
|
182
|
+
|
|
183
|
+
raise ArgumentError, "throttle requires max_pending on channel :#{@name}"
|
|
193
184
|
end
|
|
194
185
|
|
|
195
186
|
def throttled?
|
|
@@ -199,6 +190,9 @@ module TypedBus
|
|
|
199
190
|
def apply_throttle!
|
|
200
191
|
remaining_ratio = (@max_pending - @pending_deliveries.size).to_f / @max_pending
|
|
201
192
|
return if remaining_ratio > @throttle
|
|
193
|
+
# At or over capacity the delay would be infinite; let backpressure
|
|
194
|
+
# (wait_for_capacity) do the blocking instead of sleeping forever.
|
|
195
|
+
return if remaining_ratio <= 0.0
|
|
202
196
|
|
|
203
197
|
effective_rate = @max_pending * remaining_ratio
|
|
204
198
|
delay = 1.0 / effective_rate
|
|
@@ -211,8 +205,9 @@ module TypedBus
|
|
|
211
205
|
return unless @type
|
|
212
206
|
return if message.is_a?(@type)
|
|
213
207
|
|
|
214
|
-
|
|
215
|
-
|
|
208
|
+
actual = message.class
|
|
209
|
+
log(:error, "type mismatch: expected #{@type}, got #{actual}")
|
|
210
|
+
raise ArgumentError, "Expected #{@type}, got #{actual} on channel :#{@name}"
|
|
216
211
|
end
|
|
217
212
|
|
|
218
213
|
def bounded?
|
|
@@ -220,30 +215,114 @@ module TypedBus
|
|
|
220
215
|
end
|
|
221
216
|
|
|
222
217
|
def wait_for_capacity
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
log(:debug, "backpressure: capacity available (pending=#{
|
|
218
|
+
pending = pending_count
|
|
219
|
+
return if pending < @max_pending
|
|
220
|
+
|
|
221
|
+
log(:debug, "backpressure: waiting for capacity (pending=#{pending}, max=#{@max_pending})")
|
|
222
|
+
log(:debug, "backpressure: capacity available (pending=#{wait_while_full})")
|
|
223
|
+
end
|
|
224
|
+
|
|
225
|
+
# Block until a tracker resolves below the limit or the channel closes.
|
|
226
|
+
# @return [Integer] the pending count once the wait is over
|
|
227
|
+
def wait_while_full
|
|
228
|
+
@backpressure.wait while full? && !closed?
|
|
229
|
+
pending_count
|
|
230
|
+
end
|
|
231
|
+
|
|
232
|
+
def full?
|
|
233
|
+
pending_count >= @max_pending
|
|
228
234
|
end
|
|
229
235
|
|
|
230
236
|
def tracker_resolved(tracker)
|
|
231
|
-
@pending_deliveries.delete(tracker
|
|
237
|
+
@pending_deliveries.delete(tracker)
|
|
232
238
|
@backpressure.signal if bounded?
|
|
233
239
|
end
|
|
234
240
|
|
|
241
|
+
# Nack every pending delivery. An error from one (such as a raising
|
|
242
|
+
# on_dead_letter callback) must not leave the rest pending, so the
|
|
243
|
+
# first error is kept and re-raised after the loop.
|
|
235
244
|
def force_nack_pending
|
|
245
|
+
first_error = nil
|
|
236
246
|
@active_deliveries.dup.each do |delivery|
|
|
237
247
|
delivery.nack! if delivery.pending?
|
|
248
|
+
rescue StandardError => error
|
|
249
|
+
first_error ||= error
|
|
238
250
|
end
|
|
251
|
+
raise first_error if first_error
|
|
239
252
|
end
|
|
240
253
|
|
|
254
|
+
# Start tracking one publish across its subscribers.
|
|
255
|
+
# @return [DeliveryTracker]
|
|
256
|
+
def track(message, subscriber_ids)
|
|
257
|
+
tracker = DeliveryTracker.new(message, channel_name: @name, subscriber_ids: subscriber_ids)
|
|
258
|
+
@pending_deliveries[tracker] = tracker
|
|
259
|
+
|
|
260
|
+
tracker.on_complete { record_stat(:delivered) }
|
|
261
|
+
tracker.on_resolved { tracker_resolved(tracker) }
|
|
262
|
+
tracker
|
|
263
|
+
end
|
|
264
|
+
|
|
265
|
+
# Hand one subscriber its Delivery for the tracked message.
|
|
266
|
+
def deliver(tracker, sub_id, handler)
|
|
267
|
+
delivery = build_delivery(tracker, sub_id)
|
|
268
|
+
@active_deliveries << delivery
|
|
269
|
+
|
|
270
|
+
# An earlier handler may have closed the channel mid-fan-out. close
|
|
271
|
+
# only force-nacks deliveries that already exist, so dead-letter
|
|
272
|
+
# this one the same way instead of dispatching it.
|
|
273
|
+
return delivery.nack! if closed?
|
|
274
|
+
|
|
275
|
+
log(:debug, "notifying subscriber ##{sub_id} (message=#{tracker.message.class})")
|
|
276
|
+
dispatch(handler, delivery)
|
|
277
|
+
end
|
|
278
|
+
|
|
279
|
+
# Build the Delivery envelope for one subscriber, wired to the tracker.
|
|
280
|
+
# @return [Delivery]
|
|
281
|
+
def build_delivery(tracker, sub_id)
|
|
282
|
+
delivery = Delivery.new(
|
|
283
|
+
tracker.message,
|
|
284
|
+
channel_name: @name,
|
|
285
|
+
subscriber_id: sub_id,
|
|
286
|
+
timeout: @timeout,
|
|
287
|
+
on_ack: ->(_id) { delivery_acked(delivery, tracker) },
|
|
288
|
+
on_nack: ->(_id) { delivery_nacked(delivery, tracker) }
|
|
289
|
+
)
|
|
290
|
+
end
|
|
291
|
+
|
|
292
|
+
# Run the subscriber's handler in its own task; a raising handler nacks.
|
|
293
|
+
def dispatch(handler, delivery)
|
|
294
|
+
Async do
|
|
295
|
+
handler.call(delivery)
|
|
296
|
+
rescue StandardError => error
|
|
297
|
+
log(:error, "subscriber ##{delivery.subscriber_id} raised #{error.class}: #{error.message}")
|
|
298
|
+
delivery.nack! if delivery.pending?
|
|
299
|
+
end
|
|
300
|
+
end
|
|
301
|
+
|
|
302
|
+
def delivery_acked(delivery, tracker)
|
|
303
|
+
@active_deliveries.delete(delivery)
|
|
304
|
+
tracker.ack(delivery.subscriber_id)
|
|
305
|
+
end
|
|
306
|
+
|
|
307
|
+
def delivery_nacked(delivery, tracker)
|
|
308
|
+
@active_deliveries.delete(delivery)
|
|
309
|
+
tracker.nack(delivery.subscriber_id)
|
|
310
|
+
# Count before pushing: the DLQ runs a user callback that may raise.
|
|
311
|
+
record_stat(:dead_lettered)
|
|
312
|
+
record_stat(delivery.timed_out? ? :timed_out : :nacked)
|
|
313
|
+
@dead_letter_queue.push(delivery)
|
|
314
|
+
end
|
|
315
|
+
|
|
316
|
+
# A publish with nobody listening goes straight to the DLQ.
|
|
317
|
+
# @return [nil]
|
|
241
318
|
def dead_letter_no_subscribers(message)
|
|
319
|
+
log(:warn, "published with no subscribers, routing to DLQ (message=#{message.class})")
|
|
242
320
|
delivery = Delivery.new(message, channel_name: @name, subscriber_id: -1)
|
|
243
321
|
delivery.nack!
|
|
244
|
-
@dead_letter_queue.push(delivery)
|
|
245
322
|
record_stat(:nacked)
|
|
246
323
|
record_stat(:dead_lettered)
|
|
324
|
+
@dead_letter_queue.push(delivery)
|
|
325
|
+
nil
|
|
247
326
|
end
|
|
248
327
|
|
|
249
328
|
def record_stat(suffix)
|
|
@@ -24,9 +24,41 @@ module TypedBus
|
|
|
24
24
|
log_level: Logger::INFO
|
|
25
25
|
}.freeze
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
# @return [Numeric, nil] delivery ACK deadline in seconds; nil = never auto-nack
|
|
28
|
+
attr_accessor :timeout
|
|
29
|
+
# @return [Integer, nil] backpressure limit; nil = unbounded
|
|
30
|
+
attr_reader :max_pending
|
|
31
|
+
# @return [Numeric, nil] remaining-capacity ratio where backoff begins; 0 or nil = off
|
|
32
|
+
attr_reader :throttle
|
|
28
33
|
attr_reader :logger, :log_level
|
|
29
34
|
|
|
35
|
+
# Ensure a backpressure limit is usable: +nil+ (unbounded) or a
|
|
36
|
+
# positive Integer. Zero and negative limits can never accept a publish.
|
|
37
|
+
#
|
|
38
|
+
# @param value [Object] candidate max_pending
|
|
39
|
+
# @raise [ArgumentError] if value is neither nil nor a positive Integer
|
|
40
|
+
# @return [Integer, nil] the validated value
|
|
41
|
+
def self.validate_max_pending!(value)
|
|
42
|
+
return value if value.nil? || (value.is_a?(Integer) && value.positive?)
|
|
43
|
+
|
|
44
|
+
raise ArgumentError, "max_pending must be nil or a positive Integer, got #{value.inspect}"
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
# Ensure a throttle threshold is usable: +nil+ or +0+ (off), or a real
|
|
48
|
+
# number strictly between 0 and 1. Whether the channel is bounded is
|
|
49
|
+
# checked when the channel is created.
|
|
50
|
+
#
|
|
51
|
+
# @param value [Object] candidate throttle
|
|
52
|
+
# @param context [String, nil] text appended to the error message
|
|
53
|
+
# @raise [ArgumentError] if value is not nil, 0, or a number in (0, 1)
|
|
54
|
+
# @return [Numeric, nil] the validated value
|
|
55
|
+
def self.validate_throttle!(value, context = nil)
|
|
56
|
+
return value if value.nil?
|
|
57
|
+
return value if value.is_a?(Numeric) && value.real? && (value.zero? || (value.positive? && value < 1))
|
|
58
|
+
|
|
59
|
+
raise ArgumentError, "throttle must be 0 (off) or between 0.0 and 1.0 (exclusive), got #{value.inspect}#{context}"
|
|
60
|
+
end
|
|
61
|
+
|
|
30
62
|
def initialize
|
|
31
63
|
@timeout = DEFAULTS[:timeout]
|
|
32
64
|
@max_pending = DEFAULTS[:max_pending]
|
|
@@ -35,6 +67,20 @@ module TypedBus
|
|
|
35
67
|
@log_level = DEFAULTS[:log_level]
|
|
36
68
|
end
|
|
37
69
|
|
|
70
|
+
# Set the backpressure limit.
|
|
71
|
+
# @param value [Integer, nil] a positive Integer, or nil for unbounded
|
|
72
|
+
# @raise [ArgumentError] if value is neither nil nor a positive Integer
|
|
73
|
+
def max_pending=(value)
|
|
74
|
+
@max_pending = self.class.validate_max_pending!(value)
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# Set the throttle threshold.
|
|
78
|
+
# @param value [Numeric, nil] 0 or nil for off, or a number strictly between 0 and 1
|
|
79
|
+
# @raise [ArgumentError] if value is not nil, 0, or a number in (0, 1)
|
|
80
|
+
def throttle=(value)
|
|
81
|
+
@throttle = self.class.validate_throttle!(value)
|
|
82
|
+
end
|
|
83
|
+
|
|
38
84
|
# Set the logger and apply the current log_level to it.
|
|
39
85
|
# @param log [Logger, nil]
|
|
40
86
|
def logger=(log)
|
|
@@ -44,7 +90,9 @@ module TypedBus
|
|
|
44
90
|
|
|
45
91
|
# Set the log level and apply it to the current logger.
|
|
46
92
|
# @param level [Integer] a Logger constant (Logger::DEBUG, Logger::INFO, etc.)
|
|
93
|
+
# @raise [ArgumentError] if level is not a valid Logger level
|
|
47
94
|
def log_level=(level)
|
|
95
|
+
Logger.new(nil, level: level)
|
|
48
96
|
@log_level = level
|
|
49
97
|
@logger&.level = level
|
|
50
98
|
end
|
|
@@ -52,9 +100,9 @@ module TypedBus
|
|
|
52
100
|
# Merge overrides on top of this configuration's values.
|
|
53
101
|
# Parameters set to +:use_default+ inherit from this config.
|
|
54
102
|
#
|
|
55
|
-
# @param timeout [Numeric, Symbol] delivery ACK deadline
|
|
103
|
+
# @param timeout [Numeric, nil, Symbol] delivery ACK deadline
|
|
56
104
|
# @param max_pending [Integer, nil, Symbol] backpressure limit
|
|
57
|
-
# @param throttle [
|
|
105
|
+
# @param throttle [Numeric, nil, Symbol] capacity ratio for adaptive backoff
|
|
58
106
|
# @return [Hash] resolved values
|
|
59
107
|
def resolve(timeout: :use_default, max_pending: :use_default, throttle: :use_default)
|
|
60
108
|
{
|
|
@@ -63,10 +111,5 @@ module TypedBus
|
|
|
63
111
|
throttle: throttle == :use_default ? @throttle : throttle
|
|
64
112
|
}
|
|
65
113
|
end
|
|
66
|
-
|
|
67
|
-
def initialize_copy(_source)
|
|
68
|
-
# All fields are scalars or intentionally shared (Logger).
|
|
69
|
-
# No deep-copy needed.
|
|
70
|
-
end
|
|
71
114
|
end
|
|
72
115
|
end
|
|
@@ -16,7 +16,9 @@ module TypedBus
|
|
|
16
16
|
def push(delivery)
|
|
17
17
|
@entries << delivery
|
|
18
18
|
reason = delivery.timed_out? ? "timeout" : "nack"
|
|
19
|
-
log(:warn,
|
|
19
|
+
log(:warn,
|
|
20
|
+
"entry added (channel=:#{delivery.channel_name}, subscriber=##{delivery.subscriber_id}, " \
|
|
21
|
+
"reason=#{reason}, total=#{@entries.size})")
|
|
20
22
|
@on_dead_letter&.call(delivery)
|
|
21
23
|
end
|
|
22
24
|
|
|
@@ -29,26 +31,48 @@ module TypedBus
|
|
|
29
31
|
end
|
|
30
32
|
|
|
31
33
|
# Iterate over dead letters without removing them.
|
|
32
|
-
def each(&
|
|
33
|
-
@entries.each(&
|
|
34
|
+
def each(&)
|
|
35
|
+
@entries.each(&)
|
|
34
36
|
end
|
|
35
37
|
|
|
36
38
|
include Enumerable
|
|
37
39
|
|
|
38
|
-
#
|
|
40
|
+
# Remove the current entries from the queue and yield each one once.
|
|
41
|
+
#
|
|
42
|
+
# The queue is emptied before the first yield, so while the block
|
|
43
|
+
# runs, #size and #each see only entries added during the drain.
|
|
44
|
+
# Those (such as a retry that fails again) stay queued for the next
|
|
45
|
+
# drain. If the block raises, the entry it was handling and the ones
|
|
46
|
+
# not yet yielded go back to the front of the queue in their
|
|
47
|
+
# original order. If the block exits early with +break+, +return+,
|
|
48
|
+
# or +throw+, the entry it was handling counts as done and only the
|
|
49
|
+
# ones not yet yielded go back.
|
|
39
50
|
# @return [Array<Delivery>] the drained entries
|
|
40
51
|
def drain
|
|
41
|
-
drained = @entries
|
|
42
|
-
@entries
|
|
52
|
+
drained = @entries
|
|
53
|
+
@entries = []
|
|
54
|
+
if block_given?
|
|
55
|
+
handled = 0
|
|
56
|
+
begin
|
|
57
|
+
drained.each do |entry|
|
|
58
|
+
handled += 1
|
|
59
|
+
yield entry
|
|
60
|
+
end
|
|
61
|
+
rescue Exception # rubocop:disable Lint/RescueException -- any raise puts the entry back
|
|
62
|
+
handled -= 1
|
|
63
|
+
raise
|
|
64
|
+
ensure
|
|
65
|
+
@entries.unshift(*drained.drop(handled))
|
|
66
|
+
end
|
|
67
|
+
end
|
|
43
68
|
log(:info, "drained #{drained.size} entries")
|
|
44
|
-
drained.each { |d| yield d } if block_given?
|
|
45
69
|
drained
|
|
46
70
|
end
|
|
47
71
|
|
|
48
72
|
def clear!
|
|
49
73
|
count = @entries.size
|
|
50
74
|
@entries.clear
|
|
51
|
-
log(:info, "cleared #{count} entries") if count
|
|
75
|
+
log(:info, "cleared #{count} entries") if count.positive?
|
|
52
76
|
end
|
|
53
77
|
|
|
54
78
|
# Register or replace the callback fired when entries arrive.
|
data/lib/typed_bus/delivery.rb
CHANGED
|
@@ -12,7 +12,7 @@ module TypedBus
|
|
|
12
12
|
# @param message [Object] the published payload
|
|
13
13
|
# @param channel_name [Symbol] originating channel
|
|
14
14
|
# @param subscriber_id [Integer] identity of the target subscriber
|
|
15
|
-
# @param timeout [Numeric] seconds before auto-nack (nil = no timeout)
|
|
15
|
+
# @param timeout [Numeric, nil] seconds before auto-nack (nil = no timeout)
|
|
16
16
|
# @param on_ack [Proc, nil] called with subscriber_id on ack
|
|
17
17
|
# @param on_nack [Proc, nil] called with subscriber_id on nack
|
|
18
18
|
def initialize(message, channel_name:, subscriber_id:, timeout: nil, on_ack: nil, on_nack: nil)
|
|
@@ -15,10 +15,10 @@ module TypedBus
|
|
|
15
15
|
def initialize(message, channel_name:, subscriber_ids:)
|
|
16
16
|
@message = message
|
|
17
17
|
@channel_name = channel_name
|
|
18
|
-
@states = subscriber_ids.
|
|
19
|
-
@on_complete =
|
|
20
|
-
@on_resolved =
|
|
21
|
-
@on_dead_letter =
|
|
18
|
+
@states = subscriber_ids.to_h { |id| [id, :pending] }
|
|
19
|
+
@on_complete = []
|
|
20
|
+
@on_resolved = []
|
|
21
|
+
@on_dead_letter = []
|
|
22
22
|
@resolved = false
|
|
23
23
|
end
|
|
24
24
|
|
|
@@ -37,45 +37,53 @@ module TypedBus
|
|
|
37
37
|
|
|
38
38
|
# True when every subscriber has ACKed.
|
|
39
39
|
def fully_delivered?
|
|
40
|
-
@states.values.all? { |
|
|
40
|
+
@states.values.all? { |state| state == :acked }
|
|
41
41
|
end
|
|
42
42
|
|
|
43
43
|
# True when all subscribers have resolved (acked or nacked).
|
|
44
44
|
def fully_resolved?
|
|
45
|
-
@states.values.none? { |
|
|
45
|
+
@states.values.none? { |state| state == :pending }
|
|
46
46
|
end
|
|
47
47
|
|
|
48
48
|
# Number of subscribers still pending.
|
|
49
49
|
def pending_count
|
|
50
|
-
@states.count { |_,
|
|
50
|
+
@states.count { |_, state| state == :pending }
|
|
51
51
|
end
|
|
52
52
|
|
|
53
53
|
# Register a callback fired when all subscribers have resolved
|
|
54
54
|
# and every one ACKed (successful delivery).
|
|
55
|
+
# Callbacks accumulate and run in registration order.
|
|
55
56
|
def on_complete(&block)
|
|
56
|
-
@on_complete
|
|
57
|
+
register(@on_complete, block)
|
|
57
58
|
end
|
|
58
59
|
|
|
59
60
|
# Register a callback fired when all subscribers have resolved,
|
|
60
61
|
# regardless of outcome (acked or nacked). Use for cleanup.
|
|
62
|
+
# Callbacks accumulate and run in registration order.
|
|
61
63
|
def on_resolved(&block)
|
|
62
|
-
@on_resolved
|
|
64
|
+
register(@on_resolved, block)
|
|
63
65
|
end
|
|
64
66
|
|
|
65
67
|
# Register a callback fired for each NACK, receiving the subscriber_id.
|
|
68
|
+
# Callbacks accumulate and run in registration order.
|
|
66
69
|
def on_dead_letter(&block)
|
|
67
|
-
@on_dead_letter
|
|
70
|
+
register(@on_dead_letter, block)
|
|
68
71
|
end
|
|
69
72
|
|
|
70
73
|
private
|
|
71
74
|
|
|
75
|
+
# Append a callback; a call without a block registers nothing.
|
|
76
|
+
def register(callbacks, block)
|
|
77
|
+
callbacks << block if block
|
|
78
|
+
end
|
|
79
|
+
|
|
72
80
|
def set_state(subscriber_id, state)
|
|
73
81
|
unless @states.key?(subscriber_id)
|
|
74
82
|
raise ArgumentError, "Unknown subscriber_id: #{subscriber_id}"
|
|
75
83
|
end
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
84
|
+
|
|
85
|
+
current = @states[subscriber_id]
|
|
86
|
+
raise "Subscriber #{subscriber_id} already resolved as #{current}" if current != :pending
|
|
79
87
|
|
|
80
88
|
@states[subscriber_id] = state
|
|
81
89
|
end
|
|
@@ -84,20 +92,21 @@ module TypedBus
|
|
|
84
92
|
return unless fully_resolved? && !@resolved
|
|
85
93
|
|
|
86
94
|
@resolved = true
|
|
95
|
+
total = @states.size
|
|
87
96
|
|
|
88
97
|
if fully_delivered?
|
|
89
|
-
log(:info, "fully delivered (all #{
|
|
90
|
-
@on_complete
|
|
98
|
+
log(:info, "fully delivered (all #{total} subscribers acked)")
|
|
99
|
+
@on_complete.each(&:call)
|
|
91
100
|
else
|
|
92
|
-
nacked = @states.count { |_,
|
|
93
|
-
log(:warn, "resolved with #{nacked} nack(s) out of #{
|
|
101
|
+
nacked = @states.count { |_, state| state == :nacked }
|
|
102
|
+
log(:warn, "resolved with #{nacked} nack(s) out of #{total} subscribers")
|
|
94
103
|
end
|
|
95
104
|
|
|
96
|
-
@on_resolved
|
|
105
|
+
@on_resolved.each(&:call)
|
|
97
106
|
end
|
|
98
107
|
|
|
99
108
|
def fire_dead_letter(subscriber_id)
|
|
100
|
-
@on_dead_letter
|
|
109
|
+
@on_dead_letter.each { |callback| callback.call(subscriber_id) }
|
|
101
110
|
end
|
|
102
111
|
|
|
103
112
|
def log(level, message)
|