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
@@ -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
@@ -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
@@ -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
@@ -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