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.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +158 -4
  3. data/LICENSE +21 -0
  4. data/README.md +25 -13
  5. data/lib/typed_bus/channel.rb +170 -91
  6. data/lib/typed_bus/configuration.rb +51 -8
  7. data/lib/typed_bus/dead_letter_queue.rb +32 -8
  8. data/lib/typed_bus/delivery.rb +1 -1
  9. data/lib/typed_bus/delivery_tracker.rb +28 -19
  10. data/lib/typed_bus/message_bus.rb +55 -14
  11. data/lib/typed_bus/version.rb +1 -1
  12. data/lib/typed_bus.rb +3 -0
  13. metadata +23 -62
  14. data/.envrc +0 -1
  15. data/.github/workflows/deploy-github-pages.yml +0 -52
  16. data/.github/workflows/deploy-yard-docs.yml +0 -52
  17. data/.irbrc +0 -10
  18. data/COMMITS.md +0 -196
  19. data/Rakefile +0 -12
  20. data/docs/api/channel.md +0 -94
  21. data/docs/api/configuration.md +0 -90
  22. data/docs/api/dead-letter-queue.md +0 -52
  23. data/docs/api/delivery-tracker.md +0 -66
  24. data/docs/api/delivery.md +0 -73
  25. data/docs/api/index.md +0 -45
  26. data/docs/api/message-bus.md +0 -101
  27. data/docs/api/stats.md +0 -50
  28. data/docs/architecture/concurrency-model.md +0 -38
  29. data/docs/architecture/configuration-cascade.md +0 -76
  30. data/docs/architecture/index.md +0 -7
  31. data/docs/architecture/publish-flow.md +0 -67
  32. data/docs/assets/css/custom.css +0 -11
  33. data/docs/assets/images/typed_bus.gif +0 -0
  34. data/docs/assets/images/typed_bus.jpg +0 -0
  35. data/docs/assets/images/typed_bus.mp4 +0 -0
  36. data/docs/concepts.md +0 -47
  37. data/docs/examples/index.md +0 -37
  38. data/docs/getting-started/configuration.md +0 -87
  39. data/docs/getting-started/index.md +0 -7
  40. data/docs/getting-started/installation.md +0 -33
  41. data/docs/getting-started/quick-start.md +0 -51
  42. data/docs/guides/adaptive-throttling.md +0 -76
  43. data/docs/guides/backpressure.md +0 -58
  44. data/docs/guides/dead-letter-queues.md +0 -78
  45. data/docs/guides/delivery-and-ack.md +0 -89
  46. data/docs/guides/error-handling.md +0 -91
  47. data/docs/guides/graceful-shutdown.md +0 -75
  48. data/docs/guides/index.md +0 -13
  49. data/docs/guides/logging.md +0 -93
  50. data/docs/guides/stats-and-monitoring.md +0 -75
  51. data/docs/guides/typed-channels.md +0 -63
  52. data/docs/index.md +0 -56
  53. data/examples/00_config.rb +0 -156
  54. data/examples/01_basic_usage.rb +0 -26
  55. data/examples/02_typed_channels.rb +0 -41
  56. data/examples/03_multiple_subscribers.rb +0 -44
  57. data/examples/04_nack_and_dead_letters.rb +0 -47
  58. data/examples/05_delivery_timeout.rb +0 -44
  59. data/examples/06_backpressure.rb +0 -32
  60. data/examples/07_message_bus.rb +0 -55
  61. data/examples/08_error_handling.rb +0 -82
  62. data/examples/09_stats_and_monitoring.rb +0 -71
  63. data/examples/10_concurrent_pipeline.rb +0 -116
  64. data/examples/11_logging_basic.rb +0 -60
  65. data/examples/12_logging_failures.rb +0 -65
  66. data/examples/13_logging_backpressure.rb +0 -56
  67. data/examples/14_adaptive_throttling.rb +0 -101
  68. data/examples/README.md +0 -27
  69. data/examples/temp.md +0 -95
  70. data/mkdocs.yml +0 -183
@@ -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 (nil = unbounded)
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 [Float] capacity ratio (0.0..1.0) at which asymptotic backoff begins (0.0 = disabled)
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, "channel created (type=#{type || 'any'}, timeout=#{timeout}s, max_pending=#{max_pending || 'unbounded'}, throttle=#{@throttle > 0 ? "#{(@throttle * 100).round}%" : 'off'})")
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
- # @return [DeliveryTracker] the tracker for this message
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
- raise "Channel :#{@name} is closed" if @closed
59
+ admit!(message)
51
60
 
52
- validate_type!(message)
53
- apply_throttle! if throttled?
54
- wait_for_capacity if bounded?
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
- subscriber_ids = @subscribers.keys
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} is closed" if @closed
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
- case id_or_block
130
- when Integer
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
- before = @subscribers.size
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, "clearing all state (active=#{@active_deliveries.size}, pending=#{@pending_deliveries.size}, dlq=#{@dead_letter_queue.size})")
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 validate_throttle_config!
184
- return if @throttle == 0.0
149
+ def ensure_open!
150
+ raise "Channel :#{@name} is closed" if @closed
151
+ end
185
152
 
186
- unless bounded?
187
- raise ArgumentError, "throttle requires max_pending on channel :#{@name}"
188
- end
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
- unless @throttle > 0.0 && @throttle < 1.0
191
- raise ArgumentError, "throttle must be between 0.0 and 1.0 (exclusive), got #{@throttle} on channel :#{@name}"
192
- end
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
- log(:error, "type mismatch: expected #{@type}, got #{message.class}")
215
- raise ArgumentError, "Expected #{@type}, got #{message.class} on channel :#{@name}"
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
- log(:debug, "backpressure: waiting for capacity (pending=#{@pending_deliveries.size}, max=#{@max_pending})")
224
- while @pending_deliveries.size >= @max_pending && !@closed
225
- @backpressure.wait
226
- end
227
- log(:debug, "backpressure: capacity available (pending=#{@pending_deliveries.size})")
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.object_id)
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
- attr_accessor :timeout, :max_pending, :throttle
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 [Float, Symbol] capacity ratio for adaptive backoff
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, "entry added (channel=:#{delivery.channel_name}, subscriber=##{delivery.subscriber_id}, reason=#{reason}, total=#{@entries.size})")
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(&block)
33
- @entries.each(&block)
34
+ def each(&)
35
+ @entries.each(&)
34
36
  end
35
37
 
36
38
  include Enumerable
37
39
 
38
- # Yield each dead letter and remove it from the queue.
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.dup
42
- @entries.clear
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 > 0
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.
@@ -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.each_with_object({}) { |id, h| h[id] = :pending }
19
- @on_complete = nil
20
- @on_resolved = nil
21
- @on_dead_letter = nil
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? { |s| s == :acked }
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? { |s| s == :pending }
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 { |_, s| s == :pending }
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 = block
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 = block
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 = block
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
- if @states[subscriber_id] != :pending
77
- raise "Subscriber #{subscriber_id} already resolved as #{@states[subscriber_id]}"
78
- end
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 #{@states.size} subscribers acked)")
90
- @on_complete&.call
98
+ log(:info, "fully delivered (all #{total} subscribers acked)")
99
+ @on_complete.each(&:call)
91
100
  else
92
- nacked = @states.count { |_, s| s == :nacked }
93
- log(:warn, "resolved with #{nacked} nack(s) out of #{@states.size} subscribers")
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&.call
105
+ @on_resolved.each(&:call)
97
106
  end
98
107
 
99
108
  def fire_dead_letter(subscriber_id)
100
- @on_dead_letter&.call(subscriber_id)
109
+ @on_dead_letter.each { |callback| callback.call(subscriber_id) }
101
110
  end
102
111
 
103
112
  def log(level, message)