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
|
@@ -1,91 +0,0 @@
|
|
|
1
|
-
# Error Handling
|
|
2
|
-
|
|
3
|
-
TypedBus handles errors predictably at every level.
|
|
4
|
-
|
|
5
|
-
## Subscriber Exceptions
|
|
6
|
-
|
|
7
|
-
If a subscriber block raises, the delivery is auto-NACKed and routed to the DLQ:
|
|
8
|
-
|
|
9
|
-
```ruby
|
|
10
|
-
bus.subscribe(:orders) do |delivery|
|
|
11
|
-
raise "something broke"
|
|
12
|
-
# delivery is auto-nacked, exception is logged
|
|
13
|
-
end
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
The exception is rescued within the subscriber's Async task. Other subscribers and the channel continue operating normally.
|
|
17
|
-
|
|
18
|
-
## Type Mismatches
|
|
19
|
-
|
|
20
|
-
Publishing a message that doesn't match the channel's type raises `ArgumentError` at the publish site:
|
|
21
|
-
|
|
22
|
-
```ruby
|
|
23
|
-
bus.add_channel(:orders, type: Order)
|
|
24
|
-
|
|
25
|
-
Async do
|
|
26
|
-
bus.publish(:orders, "not an order")
|
|
27
|
-
# => ArgumentError: Expected Order, got String on channel :orders
|
|
28
|
-
end
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
## Unknown Channels
|
|
32
|
-
|
|
33
|
-
All MessageBus methods that take a channel name raise `ArgumentError` for unknown channels:
|
|
34
|
-
|
|
35
|
-
```ruby
|
|
36
|
-
bus.publish(:nonexistent, "msg")
|
|
37
|
-
# => ArgumentError: Unknown channel: nonexistent
|
|
38
|
-
|
|
39
|
-
bus.subscribe(:nonexistent) { |d| d.ack! }
|
|
40
|
-
# => ArgumentError: Unknown channel: nonexistent
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
`remove_channel` is the exception — it's a no-op for unknown channels.
|
|
44
|
-
|
|
45
|
-
## Publishing to a Closed Channel
|
|
46
|
-
|
|
47
|
-
```ruby
|
|
48
|
-
bus.close(:orders)
|
|
49
|
-
bus.publish(:orders, "msg")
|
|
50
|
-
# => RuntimeError: Channel :orders is closed
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
## Subscribing to a Closed Channel
|
|
54
|
-
|
|
55
|
-
```ruby
|
|
56
|
-
bus.close(:orders)
|
|
57
|
-
bus.subscribe(:orders) { |d| d.ack! }
|
|
58
|
-
# => RuntimeError: Channel :orders is closed
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## Double Resolution
|
|
62
|
-
|
|
63
|
-
Calling `ack!` or `nack!` on an already-resolved delivery raises `RuntimeError`:
|
|
64
|
-
|
|
65
|
-
```ruby
|
|
66
|
-
bus.subscribe(:orders) do |delivery|
|
|
67
|
-
delivery.ack!
|
|
68
|
-
delivery.ack! # => RuntimeError: Delivery already resolved as acked
|
|
69
|
-
end
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
## No Subscribers
|
|
73
|
-
|
|
74
|
-
Messages published with no subscribers go directly to the DLQ:
|
|
75
|
-
|
|
76
|
-
```ruby
|
|
77
|
-
bus.add_channel(:empty)
|
|
78
|
-
Async { bus.publish(:empty, "orphan") }
|
|
79
|
-
|
|
80
|
-
bus.dead_letters(:empty).size # => 1
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
## Throttle Validation
|
|
84
|
-
|
|
85
|
-
- `throttle` without `max_pending` raises `ArgumentError`
|
|
86
|
-
- `throttle` outside `(0.0, 1.0)` raises `ArgumentError`
|
|
87
|
-
|
|
88
|
-
```ruby
|
|
89
|
-
TypedBus::Channel.new(:bad, throttle: 0.5, timeout: 5)
|
|
90
|
-
# => ArgumentError: throttle requires max_pending on channel :bad
|
|
91
|
-
```
|
|
@@ -1,75 +0,0 @@
|
|
|
1
|
-
# Graceful Shutdown
|
|
2
|
-
|
|
3
|
-
TypedBus provides several levels of cleanup for stopping channels and buses.
|
|
4
|
-
|
|
5
|
-
## Close a Channel
|
|
6
|
-
|
|
7
|
-
Stops accepting new publishes and subscribes. Pending deliveries are force-NACKed and routed to the DLQ.
|
|
8
|
-
|
|
9
|
-
```ruby
|
|
10
|
-
channel.close
|
|
11
|
-
channel.closed? # => true
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
After closing:
|
|
15
|
-
|
|
16
|
-
- `publish` raises `RuntimeError`
|
|
17
|
-
- `subscribe` raises `RuntimeError`
|
|
18
|
-
- The DLQ retains its entries for inspection
|
|
19
|
-
|
|
20
|
-
## Close All Channels
|
|
21
|
-
|
|
22
|
-
```ruby
|
|
23
|
-
bus.close_all
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
Closes every channel on the bus. Each channel's pending deliveries are force-NACKed.
|
|
27
|
-
|
|
28
|
-
## Clear a Channel
|
|
29
|
-
|
|
30
|
-
Hard reset: cancels all timeout tasks, discards pending deliveries, and clears the DLQ.
|
|
31
|
-
|
|
32
|
-
```ruby
|
|
33
|
-
channel.clear!
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
Unlike `close`, `clear!` does not mark the channel as closed — you can continue using it.
|
|
37
|
-
|
|
38
|
-
## Clear a Bus
|
|
39
|
-
|
|
40
|
-
Clears all channels and resets stats:
|
|
41
|
-
|
|
42
|
-
```ruby
|
|
43
|
-
bus.clear!
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
## Remove a Channel
|
|
47
|
-
|
|
48
|
-
Close and remove a channel from the bus registry:
|
|
49
|
-
|
|
50
|
-
```ruby
|
|
51
|
-
bus.remove_channel(:orders)
|
|
52
|
-
bus.channel?(:orders) # => false
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
Removing a nonexistent channel is a no-op.
|
|
56
|
-
|
|
57
|
-
## Shutdown Order
|
|
58
|
-
|
|
59
|
-
For a clean shutdown:
|
|
60
|
-
|
|
61
|
-
1. Stop publishing new messages
|
|
62
|
-
2. Wait for pending deliveries to resolve (or let timeouts fire)
|
|
63
|
-
3. Process any DLQ entries
|
|
64
|
-
4. Call `bus.close_all`
|
|
65
|
-
|
|
66
|
-
```ruby
|
|
67
|
-
Async do
|
|
68
|
-
# ... normal operations ...
|
|
69
|
-
|
|
70
|
-
# Shutdown
|
|
71
|
-
sleep(timeout_duration) # let pending deliveries settle
|
|
72
|
-
bus.dead_letters(:orders).drain { |d| reprocess(d.message) }
|
|
73
|
-
bus.close_all
|
|
74
|
-
end
|
|
75
|
-
```
|
data/docs/guides/index.md
DELETED
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
# Guides
|
|
2
|
-
|
|
3
|
-
In-depth guides for every TypedBus feature.
|
|
4
|
-
|
|
5
|
-
- [Typed Channels](typed-channels.md) — constrain messages to a specific class
|
|
6
|
-
- [Delivery and Acknowledgment](delivery-and-ack.md) — ack/nack lifecycle and timeout behavior
|
|
7
|
-
- [Dead Letter Queues](dead-letter-queues.md) — inspect, retry, and monitor failed deliveries
|
|
8
|
-
- [Backpressure](backpressure.md) — bound channels and block publishers at capacity
|
|
9
|
-
- [Adaptive Throttling](adaptive-throttling.md) — progressive backoff as channels fill
|
|
10
|
-
- [Stats and Monitoring](stats-and-monitoring.md) — per-channel counters
|
|
11
|
-
- [Logging](logging.md) — structured log output
|
|
12
|
-
- [Error Handling](error-handling.md) — exceptions, edge cases, and recovery
|
|
13
|
-
- [Graceful Shutdown](graceful-shutdown.md) — close channels and drain state
|
data/docs/guides/logging.md
DELETED
|
@@ -1,93 +0,0 @@
|
|
|
1
|
-
# Logging
|
|
2
|
-
|
|
3
|
-
TypedBus produces structured log output from all components when a logger is configured.
|
|
4
|
-
|
|
5
|
-
## Enabling Logging
|
|
6
|
-
|
|
7
|
-
```ruby
|
|
8
|
-
TypedBus.configure do |config|
|
|
9
|
-
config.logger = Logger.new($stdout)
|
|
10
|
-
config.log_level = Logger::INFO
|
|
11
|
-
end
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
Or use the shortcut:
|
|
15
|
-
|
|
16
|
-
```ruby
|
|
17
|
-
TypedBus.logger = Logger.new($stdout)
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
Set to `nil` (the default) to disable logging.
|
|
21
|
-
|
|
22
|
-
## Log Level
|
|
23
|
-
|
|
24
|
-
Setting `log_level` automatically applies it to the logger:
|
|
25
|
-
|
|
26
|
-
```ruby
|
|
27
|
-
TypedBus.configure do |config|
|
|
28
|
-
config.logger = Logger.new($stdout)
|
|
29
|
-
config.log_level = Logger::DEBUG # applies to the logger
|
|
30
|
-
end
|
|
31
|
-
|
|
32
|
-
# Or change it later:
|
|
33
|
-
TypedBus.configuration.log_level = Logger::WARN
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
## What Gets Logged
|
|
37
|
-
|
|
38
|
-
### INFO Level
|
|
39
|
-
|
|
40
|
-
- Bus initialization
|
|
41
|
-
- Channel creation with parameters
|
|
42
|
-
- Subscriber registration and unsubscription
|
|
43
|
-
- Message publish events
|
|
44
|
-
- Delivery acks
|
|
45
|
-
- DLQ drains
|
|
46
|
-
- Channel close and clear operations
|
|
47
|
-
|
|
48
|
-
### WARN Level
|
|
49
|
-
|
|
50
|
-
- Delivery nacks
|
|
51
|
-
- Delivery timeouts
|
|
52
|
-
- DLQ entries added
|
|
53
|
-
- Publishing with no subscribers
|
|
54
|
-
|
|
55
|
-
### ERROR Level
|
|
56
|
-
|
|
57
|
-
- Subscriber exceptions
|
|
58
|
-
- Type mismatches
|
|
59
|
-
|
|
60
|
-
### DEBUG Level
|
|
61
|
-
|
|
62
|
-
- Individual subscriber notifications
|
|
63
|
-
- Throttle delay calculations
|
|
64
|
-
- Backpressure wait/resume events
|
|
65
|
-
|
|
66
|
-
## Log Format
|
|
67
|
-
|
|
68
|
-
All log messages are prefixed with the originating component:
|
|
69
|
-
|
|
70
|
-
```
|
|
71
|
-
TypedBus::MessageBus message bus initialized (default_throttle=off)
|
|
72
|
-
TypedBus::Channel[:orders] channel created (type=Order, timeout=10s, max_pending=100, throttle=off)
|
|
73
|
-
TypedBus::Channel[:orders] published message (type=Order, subscribers=2)
|
|
74
|
-
TypedBus::Delivery[:orders#1] acked
|
|
75
|
-
TypedBus::DeliveryTracker[:orders] fully delivered (all 2 subscribers acked)
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
## Custom Formatter
|
|
79
|
-
|
|
80
|
-
Use a custom formatter for colorized or structured output:
|
|
81
|
-
|
|
82
|
-
```ruby
|
|
83
|
-
logger = Logger.new($stdout)
|
|
84
|
-
logger.formatter = proc do |severity, datetime, _progname, msg|
|
|
85
|
-
timestamp = datetime.strftime("%H:%M:%S.%L")
|
|
86
|
-
"#{timestamp} [#{severity.ljust(5)}] #{msg}\n"
|
|
87
|
-
end
|
|
88
|
-
|
|
89
|
-
TypedBus.configure do |config|
|
|
90
|
-
config.logger = logger
|
|
91
|
-
config.log_level = Logger::DEBUG
|
|
92
|
-
end
|
|
93
|
-
```
|
|
@@ -1,75 +0,0 @@
|
|
|
1
|
-
# Stats and Monitoring
|
|
2
|
-
|
|
3
|
-
`MessageBus` tracks per-channel counters automatically via a shared `Stats` instance.
|
|
4
|
-
|
|
5
|
-
## Available Counters
|
|
6
|
-
|
|
7
|
-
For each channel named `:orders`, the following counters are tracked:
|
|
8
|
-
|
|
9
|
-
| Counter | Description |
|
|
10
|
-
|---------|-------------|
|
|
11
|
-
| `:orders_published` | Messages published |
|
|
12
|
-
| `:orders_delivered` | All subscribers ACKed (message fully delivered) |
|
|
13
|
-
| `:orders_nacked` | Explicit nacks by subscribers |
|
|
14
|
-
| `:orders_timed_out` | Delivery timeouts (auto-nack) |
|
|
15
|
-
| `:orders_dead_lettered` | Entries added to the DLQ |
|
|
16
|
-
| `:orders_throttled` | Publishes that were rate-limited |
|
|
17
|
-
|
|
18
|
-
## Reading Stats
|
|
19
|
-
|
|
20
|
-
```ruby
|
|
21
|
-
bus.stats[:orders_published] # => 42
|
|
22
|
-
bus.stats[:orders_delivered] # => 40
|
|
23
|
-
bus.stats[:orders_dead_lettered] # => 2
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Snapshot
|
|
27
|
-
|
|
28
|
-
Get all counters as a Hash:
|
|
29
|
-
|
|
30
|
-
```ruby
|
|
31
|
-
bus.stats.to_h
|
|
32
|
-
# => { orders_published: 42, orders_delivered: 40, ... }
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Reset
|
|
36
|
-
|
|
37
|
-
Zero all counters:
|
|
38
|
-
|
|
39
|
-
```ruby
|
|
40
|
-
bus.stats.reset!
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Or reset everything (channels + stats):
|
|
44
|
-
|
|
45
|
-
```ruby
|
|
46
|
-
bus.clear!
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
## Using Stats Directly
|
|
50
|
-
|
|
51
|
-
When using `Channel` without a `MessageBus`, pass a `Stats` instance:
|
|
52
|
-
|
|
53
|
-
```ruby
|
|
54
|
-
stats = TypedBus::Stats.new
|
|
55
|
-
channel = TypedBus::Channel.new(:work, stats: stats, timeout: 5)
|
|
56
|
-
|
|
57
|
-
# ... publish and subscribe ...
|
|
58
|
-
|
|
59
|
-
stats[:work_published] # => N
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
## Monitoring Pattern
|
|
63
|
-
|
|
64
|
-
Combine stats with DLQ callbacks for real-time alerting:
|
|
65
|
-
|
|
66
|
-
```ruby
|
|
67
|
-
bus.add_channel(:orders, timeout: 10)
|
|
68
|
-
|
|
69
|
-
bus.dead_letters(:orders).on_dead_letter do |delivery|
|
|
70
|
-
error_rate = bus.stats[:orders_dead_lettered].to_f / bus.stats[:orders_published]
|
|
71
|
-
if error_rate > 0.1
|
|
72
|
-
alert("Orders DLQ error rate above 10%: #{(error_rate * 100).round}%")
|
|
73
|
-
end
|
|
74
|
-
end
|
|
75
|
-
```
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
# Typed Channels
|
|
2
|
-
|
|
3
|
-
Channels can enforce a type constraint on published messages. When set, every message must pass an `is_a?` check against the specified class.
|
|
4
|
-
|
|
5
|
-
## Setting a Type
|
|
6
|
-
|
|
7
|
-
```ruby
|
|
8
|
-
channel = TypedBus::Channel.new(:orders, type: Order, timeout: 5)
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
Or via MessageBus:
|
|
12
|
-
|
|
13
|
-
```ruby
|
|
14
|
-
bus.add_channel(:orders, type: Order)
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Type Enforcement
|
|
18
|
-
|
|
19
|
-
```ruby
|
|
20
|
-
Async do
|
|
21
|
-
channel.publish(Order.new) # OK
|
|
22
|
-
channel.publish("not valid") # raises ArgumentError
|
|
23
|
-
end
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
The error message includes both the expected and actual types:
|
|
27
|
-
|
|
28
|
-
```
|
|
29
|
-
Expected Order, got String on channel :orders (ArgumentError)
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
## Subclasses
|
|
33
|
-
|
|
34
|
-
The check uses `is_a?`, so subclasses pass:
|
|
35
|
-
|
|
36
|
-
```ruby
|
|
37
|
-
class PriorityOrder < Order; end
|
|
38
|
-
|
|
39
|
-
channel = TypedBus::Channel.new(:orders, type: Order, timeout: 5)
|
|
40
|
-
|
|
41
|
-
Async do
|
|
42
|
-
channel.publish(PriorityOrder.new) # OK — PriorityOrder is_a? Order
|
|
43
|
-
end
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
## Untyped Channels
|
|
47
|
-
|
|
48
|
-
Omit `type:` (or pass `nil`) to accept any message:
|
|
49
|
-
|
|
50
|
-
```ruby
|
|
51
|
-
bus.add_channel(:events) # accepts anything
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
## When to Use Types
|
|
55
|
-
|
|
56
|
-
Type constraints are useful when:
|
|
57
|
-
|
|
58
|
-
- Multiple publishers share a channel and you want compile-time-like safety
|
|
59
|
-
- Messages carry structured data (Structs, Data classes) and you want to catch serialization mistakes early
|
|
60
|
-
- You want to document the channel's contract in code
|
|
61
|
-
|
|
62
|
-
!!! note
|
|
63
|
-
The `type:` parameter is per-channel only. It is not part of the configuration cascade — there is no meaningful "default type."
|
data/docs/index.md
DELETED
|
@@ -1,56 +0,0 @@
|
|
|
1
|
-
# TypedBus
|
|
2
|
-
<em>Async pub/sub with typed channels and ACK-based delivery</em>
|
|
3
|
-
|
|
4
|
-
<table>
|
|
5
|
-
<tr>
|
|
6
|
-
<td width="50%" align="center" valign="top">
|
|
7
|
-
<img src="assets/images/typed_bus.gif" alt="TypedBus" width="875"><br>
|
|
8
|
-
<a href="https://github.com/madbomber/typed_bus">GitHub Repository</a>
|
|
9
|
-
</td>
|
|
10
|
-
<td width="50%" valign="top">
|
|
11
|
-
TypedBus provides named, optionally typed pub/sub channels with explicit ACK/NACK delivery, dead letter queues, backpressure, and adaptive throttling — all within a single Async reactor.<br><br>
|
|
12
|
-
<strong>Key Features</strong><br>
|
|
13
|
-
|
|
14
|
-
- <strong>Typed Channels</strong> - Restrict messages to a specific class<br>
|
|
15
|
-
- <strong>ACK-Based Delivery</strong> - Subscribers must explicitly ack or nack<br>
|
|
16
|
-
- <strong>Dead Letter Queues</strong> - Collect nacked and timed-out deliveries<br>
|
|
17
|
-
- <strong>Backpressure</strong> - Bound pending deliveries per channel<br>
|
|
18
|
-
- <strong>Adaptive Throttling</strong> - Progressive slowdown as capacity fills<br>
|
|
19
|
-
- <strong>Configuration Cascade</strong> - Global → Bus → Channel defaults<br>
|
|
20
|
-
- <strong>Stats Tracking</strong> - Per-channel publish/deliver/nack/timeout counters<br>
|
|
21
|
-
- <strong>Structured Logging</strong> - Optional Logger integration across all components
|
|
22
|
-
</td>
|
|
23
|
-
</tr>
|
|
24
|
-
</table>
|
|
25
|
-
|
|
26
|
-
## Quick Example
|
|
27
|
-
|
|
28
|
-
```ruby
|
|
29
|
-
require "typed_bus"
|
|
30
|
-
|
|
31
|
-
TypedBus.configure do |config|
|
|
32
|
-
config.timeout = 10
|
|
33
|
-
config.log_level = Logger::INFO
|
|
34
|
-
end
|
|
35
|
-
|
|
36
|
-
bus = TypedBus::MessageBus.new
|
|
37
|
-
bus.add_channel(:events, type: String)
|
|
38
|
-
|
|
39
|
-
bus.subscribe(:events) do |delivery|
|
|
40
|
-
puts delivery.message
|
|
41
|
-
delivery.ack!
|
|
42
|
-
end
|
|
43
|
-
|
|
44
|
-
Async do
|
|
45
|
-
bus.publish(:events, "hello world")
|
|
46
|
-
end
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
## Requirements
|
|
50
|
-
|
|
51
|
-
- Ruby >= 3.2.0
|
|
52
|
-
- [async](https://github.com/socketry/async) ~> 2.0
|
|
53
|
-
|
|
54
|
-
## License
|
|
55
|
-
|
|
56
|
-
MIT
|
data/examples/00_config.rb
DELETED
|
@@ -1,156 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env ruby
|
|
2
|
-
# frozen_string_literal: true
|
|
3
|
-
|
|
4
|
-
# 00 — Three-Tier Configuration Cascade
|
|
5
|
-
#
|
|
6
|
-
# TypedBus resolves configurable parameters through three tiers:
|
|
7
|
-
#
|
|
8
|
-
# Global → Bus → Channel
|
|
9
|
-
#
|
|
10
|
-
# Each tier inherits from the one above unless explicitly overridden.
|
|
11
|
-
# Omitting a parameter (or passing :use_default) inherits from the parent.
|
|
12
|
-
# Passing an explicit value — including nil — overrides the parent.
|
|
13
|
-
#
|
|
14
|
-
# Configurable parameters and their factory defaults:
|
|
15
|
-
#
|
|
16
|
-
# timeout 30 Delivery ACK deadline in seconds
|
|
17
|
-
# max_pending nil Backpressure limit (nil = unbounded)
|
|
18
|
-
# throttle 0.0 Capacity ratio for adaptive backoff (0.0 = disabled)
|
|
19
|
-
# logger nil Ruby Logger instance (global-only)
|
|
20
|
-
# log_level Logger::INFO Log level applied to the logger (global-only)
|
|
21
|
-
|
|
22
|
-
require "logger"
|
|
23
|
-
require_relative "../lib/typed_bus"
|
|
24
|
-
|
|
25
|
-
# ─── Tier 1: Global Configuration ────────────────────────────────────
|
|
26
|
-
|
|
27
|
-
puts "=== Tier 1: Global Configuration ==="
|
|
28
|
-
puts
|
|
29
|
-
|
|
30
|
-
TypedBus.configure do |config|
|
|
31
|
-
config.timeout = 60
|
|
32
|
-
config.max_pending = 500
|
|
33
|
-
config.throttle = 0.5
|
|
34
|
-
config.logger = Logger.new($stdout)
|
|
35
|
-
config.log_level = Logger::WARN
|
|
36
|
-
end
|
|
37
|
-
|
|
38
|
-
puts "Global timeout: #{TypedBus.configuration.timeout}"
|
|
39
|
-
puts "Global max_pending: #{TypedBus.configuration.max_pending}"
|
|
40
|
-
puts "Global throttle: #{TypedBus.configuration.throttle}"
|
|
41
|
-
puts "Global logger: #{TypedBus.logger.class}"
|
|
42
|
-
puts "Global log_level: #{TypedBus.configuration.log_level} (#{%w[DEBUG INFO WARN ERROR FATAL][TypedBus.configuration.log_level]})"
|
|
43
|
-
puts
|
|
44
|
-
|
|
45
|
-
# Logger shortcuts work too:
|
|
46
|
-
# TypedBus.logger = Logger.new($stdout)
|
|
47
|
-
# TypedBus.logger # => the Logger instance
|
|
48
|
-
#
|
|
49
|
-
# Setting log_level automatically applies it to the logger:
|
|
50
|
-
# config.log_level = Logger::DEBUG # logger.level is now DEBUG
|
|
51
|
-
|
|
52
|
-
# ─── Tier 2: Bus-Level Overrides ─────────────────────────────────────
|
|
53
|
-
|
|
54
|
-
puts "=== Tier 2: Bus-Level Overrides ==="
|
|
55
|
-
puts
|
|
56
|
-
|
|
57
|
-
# Bus A: inherits everything from global
|
|
58
|
-
bus_a = TypedBus::MessageBus.new
|
|
59
|
-
puts "Bus A (all inherited):"
|
|
60
|
-
puts " timeout: #{bus_a.config.timeout}" # => 60
|
|
61
|
-
puts " max_pending: #{bus_a.config.max_pending}" # => 500
|
|
62
|
-
puts " throttle: #{bus_a.config.throttle}" # => 0.5
|
|
63
|
-
puts
|
|
64
|
-
|
|
65
|
-
# Bus B: overrides timeout, inherits the rest
|
|
66
|
-
bus_b = TypedBus::MessageBus.new(timeout: 10)
|
|
67
|
-
puts "Bus B (timeout overridden):"
|
|
68
|
-
puts " timeout: #{bus_b.config.timeout}" # => 10
|
|
69
|
-
puts " max_pending: #{bus_b.config.max_pending}" # => 500
|
|
70
|
-
puts " throttle: #{bus_b.config.throttle}" # => 0.5
|
|
71
|
-
puts
|
|
72
|
-
|
|
73
|
-
# Bus C: overrides all three
|
|
74
|
-
bus_c = TypedBus::MessageBus.new(timeout: 5, max_pending: nil, throttle: 0.0)
|
|
75
|
-
puts "Bus C (all overridden):"
|
|
76
|
-
puts " timeout: #{bus_c.config.timeout}" # => 5
|
|
77
|
-
puts " max_pending: #{bus_c.config.max_pending.inspect}" # => nil (unbounded)
|
|
78
|
-
puts " throttle: #{bus_c.config.throttle}" # => 0.0
|
|
79
|
-
puts
|
|
80
|
-
|
|
81
|
-
# Each bus gets an independent config snapshot — mutating one does not
|
|
82
|
-
# affect the global or other buses.
|
|
83
|
-
|
|
84
|
-
# ─── Tier 3: Channel-Level Overrides ─────────────────────────────────
|
|
85
|
-
|
|
86
|
-
puts "=== Tier 3: Channel-Level Overrides ==="
|
|
87
|
-
puts
|
|
88
|
-
|
|
89
|
-
bus = TypedBus::MessageBus.new(timeout: 30, max_pending: 100, throttle: 0.5)
|
|
90
|
-
puts "Bus defaults: timeout=30, max_pending=100, throttle=0.5"
|
|
91
|
-
puts
|
|
92
|
-
|
|
93
|
-
# Channel that inherits everything from its bus
|
|
94
|
-
bus.add_channel(:orders, type: String)
|
|
95
|
-
puts ":orders — inherits all bus defaults"
|
|
96
|
-
|
|
97
|
-
# Channel that overrides timeout only
|
|
98
|
-
bus.add_channel(:alerts, timeout: 2)
|
|
99
|
-
puts ":alerts — timeout=2, rest inherited"
|
|
100
|
-
|
|
101
|
-
# Channel that overrides max_pending and throttle
|
|
102
|
-
bus.add_channel(:logs, max_pending: 1000, throttle: 0.8)
|
|
103
|
-
puts ":logs — max_pending=1000, throttle=0.8, timeout inherited"
|
|
104
|
-
|
|
105
|
-
# Channel that disables throttle (explicit 0.0 overrides bus's 0.5)
|
|
106
|
-
bus.add_channel(:metrics, max_pending: nil, throttle: 0.0)
|
|
107
|
-
puts ":metrics — unbounded, no throttle"
|
|
108
|
-
puts
|
|
109
|
-
|
|
110
|
-
# ─── Live Demo: Cascade in Action ────────────────────────────────────
|
|
111
|
-
|
|
112
|
-
puts "=== Live Demo ==="
|
|
113
|
-
puts
|
|
114
|
-
|
|
115
|
-
# Quiet logger for the demo
|
|
116
|
-
TypedBus.logger = nil
|
|
117
|
-
|
|
118
|
-
demo_bus = TypedBus::MessageBus.new(timeout: 0.05)
|
|
119
|
-
demo_bus.add_channel(:fast) # inherits 0.05s timeout
|
|
120
|
-
demo_bus.add_channel(:slow, timeout: 5) # overrides to 5s
|
|
121
|
-
|
|
122
|
-
# :fast will auto-nack (subscriber never acks, 0.05s timeout)
|
|
123
|
-
demo_bus.subscribe(:fast) { |_d| }
|
|
124
|
-
|
|
125
|
-
# :slow will ack normally
|
|
126
|
-
demo_bus.subscribe(:slow) { |d| d.ack! }
|
|
127
|
-
|
|
128
|
-
Async do
|
|
129
|
-
demo_bus.publish(:fast, "this will time out")
|
|
130
|
-
demo_bus.publish(:slow, "this will be acked")
|
|
131
|
-
sleep 0.1 # let the fast timeout fire
|
|
132
|
-
end
|
|
133
|
-
|
|
134
|
-
puts ":fast stats (inherited 0.05s timeout → timed out):"
|
|
135
|
-
puts " published: #{demo_bus.stats[:fast_published]}"
|
|
136
|
-
puts " timed_out: #{demo_bus.stats[:fast_timed_out]}"
|
|
137
|
-
puts " dead_lettered: #{demo_bus.stats[:fast_dead_lettered]}"
|
|
138
|
-
puts
|
|
139
|
-
puts ":slow stats (overridden to 5s timeout → acked in time):"
|
|
140
|
-
puts " published: #{demo_bus.stats[:slow_published]}"
|
|
141
|
-
puts " delivered: #{demo_bus.stats[:slow_delivered]}"
|
|
142
|
-
puts
|
|
143
|
-
|
|
144
|
-
# ─── Reset ────────────────────────────────────────────────────────────
|
|
145
|
-
|
|
146
|
-
puts "=== Reset ==="
|
|
147
|
-
puts
|
|
148
|
-
|
|
149
|
-
# TypedBus.reset_configuration! restores factory defaults — handy in tests.
|
|
150
|
-
TypedBus.reset_configuration!
|
|
151
|
-
puts "After reset:"
|
|
152
|
-
puts " timeout: #{TypedBus.configuration.timeout}" # => 30
|
|
153
|
-
puts " max_pending: #{TypedBus.configuration.max_pending.inspect}" # => nil
|
|
154
|
-
puts " throttle: #{TypedBus.configuration.throttle}" # => 0.0
|
|
155
|
-
puts " logger: #{TypedBus.configuration.logger.inspect}" # => nil
|
|
156
|
-
puts " log_level: #{TypedBus.configuration.log_level} (INFO)" # => 1
|
data/examples/01_basic_usage.rb
DELETED
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env ruby
|
|
2
|
-
# frozen_string_literal: true
|
|
3
|
-
|
|
4
|
-
# 01 — Basic Pub/Sub with Acknowledgment
|
|
5
|
-
#
|
|
6
|
-
# The simplest use case: one channel, one subscriber, explicit ack.
|
|
7
|
-
# Every subscriber receives a Delivery envelope and must call ack! or nack!
|
|
8
|
-
# to confirm receipt.
|
|
9
|
-
|
|
10
|
-
require_relative "../lib/typed_bus"
|
|
11
|
-
|
|
12
|
-
channel = TypedBus::Channel.new(:greetings, timeout: 5)
|
|
13
|
-
|
|
14
|
-
channel.subscribe do |delivery|
|
|
15
|
-
puts "Received: #{delivery.message}"
|
|
16
|
-
delivery.ack!
|
|
17
|
-
puts " -> acknowledged"
|
|
18
|
-
end
|
|
19
|
-
|
|
20
|
-
Async do
|
|
21
|
-
channel.publish("Hello, world!")
|
|
22
|
-
channel.publish("Goodbye, world!")
|
|
23
|
-
end
|
|
24
|
-
|
|
25
|
-
puts
|
|
26
|
-
puts "All messages delivered and acknowledged."
|
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env ruby
|
|
2
|
-
# frozen_string_literal: true
|
|
3
|
-
|
|
4
|
-
# 02 — Typed Channels
|
|
5
|
-
#
|
|
6
|
-
# Channels can enforce a type constraint. Publishing the wrong type raises
|
|
7
|
-
# immediately, catching bugs at the publish site rather than in subscribers.
|
|
8
|
-
|
|
9
|
-
require_relative "../lib/typed_bus"
|
|
10
|
-
|
|
11
|
-
# Define domain events using Ruby's Data class
|
|
12
|
-
UserRegistered = Data.define(:email, :plan)
|
|
13
|
-
OrderPlaced = Data.define(:order_id, :total)
|
|
14
|
-
|
|
15
|
-
# This channel only accepts UserRegistered messages
|
|
16
|
-
channel = TypedBus::Channel.new(:users, type: UserRegistered, timeout: 5)
|
|
17
|
-
|
|
18
|
-
channel.subscribe do |delivery|
|
|
19
|
-
event = delivery.message
|
|
20
|
-
puts "New user: #{event.email} (#{event.plan} plan)"
|
|
21
|
-
delivery.ack!
|
|
22
|
-
end
|
|
23
|
-
|
|
24
|
-
Async do
|
|
25
|
-
# This works — correct type
|
|
26
|
-
channel.publish(UserRegistered.new(email: "alice@example.com", plan: :pro))
|
|
27
|
-
|
|
28
|
-
# This raises ArgumentError — wrong type
|
|
29
|
-
begin
|
|
30
|
-
channel.publish(OrderPlaced.new(order_id: 42, total: 99.99))
|
|
31
|
-
rescue ArgumentError => e
|
|
32
|
-
puts "\nType violation caught: #{e.message}"
|
|
33
|
-
end
|
|
34
|
-
|
|
35
|
-
# Plain strings are also rejected
|
|
36
|
-
begin
|
|
37
|
-
channel.publish("not a UserRegistered")
|
|
38
|
-
rescue ArgumentError => e
|
|
39
|
-
puts "Type violation caught: #{e.message}"
|
|
40
|
-
end
|
|
41
|
-
end
|