Error Handling¶
TypedBus handles errors predictably at every level.
Subscriber Exceptions¶
If a subscriber block raises, the delivery is auto-NACKed and routed to the DLQ:
bus.subscribe(:orders) do |delivery|
raise "something broke"
# delivery is auto-nacked, exception is logged
end
The exception is rescued within the subscriber's Async task. Other subscribers and the channel continue operating normally.
Type Mismatches¶
Publishing a message that doesn't match the channel's type raises ArgumentError at the publish site:
bus.add_channel(:orders, type: Order)
Async do
bus.publish(:orders, "not an order")
# => ArgumentError: Expected Order, got String on channel :orders
end
Unknown Channels¶
All MessageBus methods that take a channel name raise ArgumentError for unknown channels:
bus.publish(:nonexistent, "msg")
# => ArgumentError: Unknown channel: :nonexistent (registered: :orders)
bus.subscribe("orders") { |d| d.ack! }
# => ArgumentError: Unknown channel: "orders" (registered: :orders)
The message shows the name you passed with inspect and lists the registered
channel names, so a String/Symbol mix-up ("orders" vs :orders) is easy to
spot. A bus with no channels says (no channels registered).
remove_channel is the exception — it's a no-op for unknown channels.
Publishing to a Closed Channel¶
Subscribing to a Closed Channel¶
bus.close(:orders)
bus.subscribe(:orders) { |d| d.ack! }
# => RuntimeError: Channel :orders is closed
Double Resolution¶
Calling ack! or nack! on an already-resolved delivery raises RuntimeError:
bus.subscribe(:orders) do |delivery|
delivery.ack!
delivery.ack! # => RuntimeError: Delivery already resolved as acked
end
No Subscribers¶
Messages published with no subscribers go directly to the DLQ:
bus.add_channel(:empty)
Async { bus.publish(:empty, "orphan") }
bus.dead_letters(:empty).size # => 1
Throttle Validation¶
throttlewithoutmax_pendingraisesArgumentErrorwhen the channel is createdthrottlethat is notnil,0, or a number strictly between0and1raisesArgumentErroras soon as it is set: inConfiguration#throttle=,MessageBus.new,add_channel, orChannel.new
TypedBus::Channel.new(:bad, throttle: 0.5, timeout: 5)
# => ArgumentError: throttle requires max_pending on channel :bad
TypedBus::MessageBus.new(throttle: 1.5, max_pending: 10)
# => ArgumentError: throttle must be 0 (off) or between 0.0 and 1.0 (exclusive), got 1.5
max_pending Validation¶
max_pending must be nil (unbounded) or a positive Integer. Configuration#max_pending=, MessageBus.new, add_channel, and Channel.new raise ArgumentError for anything else:
TypedBus::Channel.new(:bad, max_pending: 0)
# => ArgumentError: max_pending must be nil or a positive Integer, got 0
Type Validation¶
A channel's type: must be a Class or Module (or nil for untyped). Anything else raises ArgumentError when the channel is created:
TypedBus::Channel.new(:bad, type: "Order")
# => ArgumentError: type must be a Class or Module, got "Order" on channel :bad
Subscribing Without a Block¶
subscribe needs a block to deliver to. Calling it without one raises ArgumentError:
Raising Dead Letter Callbacks¶
An on_dead_letter callback runs inside the nack that dead-lettered the delivery. If it raises, the entry is already in the DLQ and the nacked/timed_out and dead_lettered stats are already counted, but the error propagates to whoever triggered the nack: the subscriber (where it is logged as a subscriber error), the timeout task, the publisher when there are no subscribers, or the caller of close / close_all when the nack comes from closing a channel. close still nacks every pending delivery and close_all still closes every channel before the first error is re-raised. Rescue inside the callback if it can fail.