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/docs/api/channel.md
DELETED
|
@@ -1,94 +0,0 @@
|
|
|
1
|
-
# Channel
|
|
2
|
-
|
|
3
|
-
`TypedBus::Channel`
|
|
4
|
-
|
|
5
|
-
A named, typed pub/sub channel with explicit acknowledgment tracking.
|
|
6
|
-
|
|
7
|
-
## Constructor
|
|
8
|
-
|
|
9
|
-
### `Channel.new(name, type:, timeout:, max_pending:, stats:, throttle:)`
|
|
10
|
-
|
|
11
|
-
| Parameter | Default | Description |
|
|
12
|
-
|-----------|---------|-------------|
|
|
13
|
-
| `name` | required | `Symbol` channel name |
|
|
14
|
-
| `type` | `nil` | Optional class constraint for messages |
|
|
15
|
-
| `timeout` | `30` | Seconds before delivery auto-nacks |
|
|
16
|
-
| `max_pending` | `nil` | Backpressure limit; `nil` = unbounded |
|
|
17
|
-
| `stats` | `nil` | Optional `Stats` instance for counters |
|
|
18
|
-
| `throttle` | `0.0` | Capacity ratio where backoff begins |
|
|
19
|
-
|
|
20
|
-
```ruby
|
|
21
|
-
channel = TypedBus::Channel.new(:orders,
|
|
22
|
-
type: Order,
|
|
23
|
-
timeout: 10,
|
|
24
|
-
max_pending: 100,
|
|
25
|
-
throttle: 0.5
|
|
26
|
-
)
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
!!! note
|
|
30
|
-
When using channels via `MessageBus`, these values are resolved through the configuration cascade. You don't normally construct channels directly with all parameters.
|
|
31
|
-
|
|
32
|
-
## Attributes
|
|
33
|
-
|
|
34
|
-
### `name` → `Symbol`
|
|
35
|
-
|
|
36
|
-
Channel name.
|
|
37
|
-
|
|
38
|
-
### `type` → `Class`, `nil`
|
|
39
|
-
|
|
40
|
-
Type constraint, or `nil` for untyped channels.
|
|
41
|
-
|
|
42
|
-
### `dead_letter_queue` → `DeadLetterQueue`
|
|
43
|
-
|
|
44
|
-
The channel's dead letter queue.
|
|
45
|
-
|
|
46
|
-
## Pub/Sub
|
|
47
|
-
|
|
48
|
-
### `publish(message)` → `DeliveryTracker`, `nil`
|
|
49
|
-
|
|
50
|
-
Publish a message to all current subscribers.
|
|
51
|
-
|
|
52
|
-
- Blocks the calling fiber if bounded and at capacity
|
|
53
|
-
- Applies throttle delay if configured
|
|
54
|
-
- Returns `nil` if no subscribers (message goes to DLQ)
|
|
55
|
-
|
|
56
|
-
**Raises:** `ArgumentError` for type mismatches. `RuntimeError` if closed.
|
|
57
|
-
|
|
58
|
-
### `subscribe(&block)` → `Integer`
|
|
59
|
-
|
|
60
|
-
Subscribe to messages. Returns the subscriber ID.
|
|
61
|
-
|
|
62
|
-
**Raises:** `RuntimeError` if closed.
|
|
63
|
-
|
|
64
|
-
### `unsubscribe(id_or_block)`
|
|
65
|
-
|
|
66
|
-
Remove a subscriber by integer ID or block reference.
|
|
67
|
-
|
|
68
|
-
## Query
|
|
69
|
-
|
|
70
|
-
### `subscriber_count` → `Integer`
|
|
71
|
-
|
|
72
|
-
Number of active subscribers.
|
|
73
|
-
|
|
74
|
-
### `pending_count` → `Integer`
|
|
75
|
-
|
|
76
|
-
Number of unresolved delivery trackers.
|
|
77
|
-
|
|
78
|
-
### `pending?` → `Boolean`
|
|
79
|
-
|
|
80
|
-
True when there are unresolved deliveries.
|
|
81
|
-
|
|
82
|
-
### `closed?` → `Boolean`
|
|
83
|
-
|
|
84
|
-
True if the channel has been closed.
|
|
85
|
-
|
|
86
|
-
## Lifecycle
|
|
87
|
-
|
|
88
|
-
### `close`
|
|
89
|
-
|
|
90
|
-
Stop accepting new publishes and subscribes. Pending deliveries are force-NACKed and routed to the DLQ.
|
|
91
|
-
|
|
92
|
-
### `clear!`
|
|
93
|
-
|
|
94
|
-
Hard reset: cancel all timeout tasks, discard pending state, clear DLQ. Does not mark the channel as closed.
|
data/docs/api/configuration.md
DELETED
|
@@ -1,90 +0,0 @@
|
|
|
1
|
-
# Configuration
|
|
2
|
-
|
|
3
|
-
`TypedBus::Configuration`
|
|
4
|
-
|
|
5
|
-
Holds configurable defaults for the message bus system. Supports three-tier cascade: Global → Bus → Channel.
|
|
6
|
-
|
|
7
|
-
## Attributes
|
|
8
|
-
|
|
9
|
-
| Attribute | Type | Default | Description |
|
|
10
|
-
|-----------|------|---------|-------------|
|
|
11
|
-
| `timeout` | `Numeric` | `30` | Delivery ACK deadline in seconds |
|
|
12
|
-
| `max_pending` | `Integer`, `nil` | `nil` | Backpressure limit; `nil` = unbounded |
|
|
13
|
-
| `throttle` | `Float` | `0.0` | Remaining-capacity ratio where backoff begins |
|
|
14
|
-
| `logger` | `Logger`, `nil` | `nil` | Ruby Logger instance |
|
|
15
|
-
| `log_level` | `Integer` | `Logger::INFO` | Log level applied to the logger |
|
|
16
|
-
|
|
17
|
-
## Constructor
|
|
18
|
-
|
|
19
|
-
### `Configuration.new`
|
|
20
|
-
|
|
21
|
-
Creates a new Configuration with factory defaults.
|
|
22
|
-
|
|
23
|
-
## Methods
|
|
24
|
-
|
|
25
|
-
### `timeout=`, `max_pending=`, `throttle=`
|
|
26
|
-
|
|
27
|
-
Standard setters for cascade parameters.
|
|
28
|
-
|
|
29
|
-
### `logger=(log)`
|
|
30
|
-
|
|
31
|
-
Sets the logger and applies the current `log_level` to it.
|
|
32
|
-
|
|
33
|
-
```ruby
|
|
34
|
-
config.logger = Logger.new($stdout)
|
|
35
|
-
# config.logger.level is now config.log_level
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
### `log_level=(level)`
|
|
39
|
-
|
|
40
|
-
Sets the log level and applies it to the current logger (if present).
|
|
41
|
-
|
|
42
|
-
```ruby
|
|
43
|
-
config.log_level = Logger::DEBUG
|
|
44
|
-
# config.logger.level is now Logger::DEBUG (if logger is set)
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
### `resolve(timeout:, max_pending:, throttle:)`
|
|
48
|
-
|
|
49
|
-
Merges overrides on top of this configuration's values. Parameters set to `:use_default` inherit from this config.
|
|
50
|
-
|
|
51
|
-
**Parameters:**
|
|
52
|
-
|
|
53
|
-
| Parameter | Default | Description |
|
|
54
|
-
|-----------|---------|-------------|
|
|
55
|
-
| `timeout` | `:use_default` | Delivery ACK deadline |
|
|
56
|
-
| `max_pending` | `:use_default` | Backpressure limit |
|
|
57
|
-
| `throttle` | `:use_default` | Capacity ratio for adaptive backoff |
|
|
58
|
-
|
|
59
|
-
**Returns:** `Hash` with resolved `:timeout`, `:max_pending`, and `:throttle` values.
|
|
60
|
-
|
|
61
|
-
```ruby
|
|
62
|
-
config = TypedBus::Configuration.new
|
|
63
|
-
config.timeout = 60
|
|
64
|
-
|
|
65
|
-
config.resolve(timeout: 10)
|
|
66
|
-
# => { timeout: 10, max_pending: nil, throttle: 0.0 }
|
|
67
|
-
|
|
68
|
-
config.resolve
|
|
69
|
-
# => { timeout: 60, max_pending: nil, throttle: 0.0 }
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
### `dup`
|
|
73
|
-
|
|
74
|
-
Returns an independent shallow copy. The logger is intentionally shared (same Logger instance); all other fields are independent.
|
|
75
|
-
|
|
76
|
-
## Constants
|
|
77
|
-
|
|
78
|
-
### `DEFAULTS`
|
|
79
|
-
|
|
80
|
-
Frozen hash of factory defaults:
|
|
81
|
-
|
|
82
|
-
```ruby
|
|
83
|
-
{
|
|
84
|
-
timeout: 30,
|
|
85
|
-
max_pending: nil,
|
|
86
|
-
throttle: 0.0,
|
|
87
|
-
logger: nil,
|
|
88
|
-
log_level: Logger::INFO
|
|
89
|
-
}
|
|
90
|
-
```
|
|
@@ -1,52 +0,0 @@
|
|
|
1
|
-
# DeadLetterQueue
|
|
2
|
-
|
|
3
|
-
`TypedBus::DeadLetterQueue`
|
|
4
|
-
|
|
5
|
-
Stores deliveries that failed — either explicitly NACKed or timed out. Each Channel owns a DLQ. Includes `Enumerable`.
|
|
6
|
-
|
|
7
|
-
## Constructor
|
|
8
|
-
|
|
9
|
-
### `DeadLetterQueue.new(&on_dead_letter)`
|
|
10
|
-
|
|
11
|
-
Optionally accepts a block that fires on each `push`.
|
|
12
|
-
|
|
13
|
-
## Methods
|
|
14
|
-
|
|
15
|
-
### `push(delivery)`
|
|
16
|
-
|
|
17
|
-
Add a failed delivery.
|
|
18
|
-
|
|
19
|
-
### `size` → `Integer`
|
|
20
|
-
|
|
21
|
-
Number of entries.
|
|
22
|
-
|
|
23
|
-
### `empty?` → `Boolean`
|
|
24
|
-
|
|
25
|
-
True if no entries.
|
|
26
|
-
|
|
27
|
-
### `each(&block)`
|
|
28
|
-
|
|
29
|
-
Iterate over dead letters without removing them.
|
|
30
|
-
|
|
31
|
-
### `drain { |delivery| ... }` → `Array<Delivery>`
|
|
32
|
-
|
|
33
|
-
Yield each dead letter and remove it from the queue. Returns the drained entries. Without a block, just removes and returns them.
|
|
34
|
-
|
|
35
|
-
### `clear!`
|
|
36
|
-
|
|
37
|
-
Discard all entries.
|
|
38
|
-
|
|
39
|
-
### `on_dead_letter { |delivery| ... }`
|
|
40
|
-
|
|
41
|
-
Register or replace the callback fired when entries arrive.
|
|
42
|
-
|
|
43
|
-
## Enumerable
|
|
44
|
-
|
|
45
|
-
`DeadLetterQueue` includes `Enumerable`, so you can use `map`, `select`, `count`, `any?`, etc.:
|
|
46
|
-
|
|
47
|
-
```ruby
|
|
48
|
-
dlq = channel.dead_letter_queue
|
|
49
|
-
|
|
50
|
-
timed_out = dlq.count(&:timed_out?)
|
|
51
|
-
messages = dlq.map(&:message)
|
|
52
|
-
```
|
|
@@ -1,66 +0,0 @@
|
|
|
1
|
-
# DeliveryTracker
|
|
2
|
-
|
|
3
|
-
`TypedBus::DeliveryTracker`
|
|
4
|
-
|
|
5
|
-
Tracks the delivery state of a single published message across N subscribers. Created per `publish` call.
|
|
6
|
-
|
|
7
|
-
## Constructor
|
|
8
|
-
|
|
9
|
-
### `DeliveryTracker.new(message, channel_name:, subscriber_ids:)`
|
|
10
|
-
|
|
11
|
-
| Parameter | Default | Description |
|
|
12
|
-
|-----------|---------|-------------|
|
|
13
|
-
| `message` | required | The published payload |
|
|
14
|
-
| `channel_name` | required | Originating channel name |
|
|
15
|
-
| `subscriber_ids` | required | `Array<Integer>` of subscriber IDs |
|
|
16
|
-
|
|
17
|
-
!!! note
|
|
18
|
-
Trackers are created internally by `Channel#publish`. You don't normally construct them directly.
|
|
19
|
-
|
|
20
|
-
## Attributes
|
|
21
|
-
|
|
22
|
-
### `message` → `Object`
|
|
23
|
-
|
|
24
|
-
The published payload.
|
|
25
|
-
|
|
26
|
-
### `channel_name` → `Symbol`
|
|
27
|
-
|
|
28
|
-
The originating channel.
|
|
29
|
-
|
|
30
|
-
## Recording Responses
|
|
31
|
-
|
|
32
|
-
### `ack(subscriber_id)`
|
|
33
|
-
|
|
34
|
-
Record an ACK from a subscriber. Checks for resolution after recording.
|
|
35
|
-
|
|
36
|
-
### `nack(subscriber_id)`
|
|
37
|
-
|
|
38
|
-
Record a NACK from a subscriber. Fires the `on_dead_letter` callback. Checks for resolution after recording.
|
|
39
|
-
|
|
40
|
-
## State
|
|
41
|
-
|
|
42
|
-
### `fully_delivered?` → `Boolean`
|
|
43
|
-
|
|
44
|
-
True when every subscriber has ACKed.
|
|
45
|
-
|
|
46
|
-
### `fully_resolved?` → `Boolean`
|
|
47
|
-
|
|
48
|
-
True when all subscribers have responded (acked or nacked).
|
|
49
|
-
|
|
50
|
-
### `pending_count` → `Integer`
|
|
51
|
-
|
|
52
|
-
Number of subscribers still pending.
|
|
53
|
-
|
|
54
|
-
## Callbacks
|
|
55
|
-
|
|
56
|
-
### `on_complete { ... }`
|
|
57
|
-
|
|
58
|
-
Called when all subscribers have resolved and every one ACKed (successful delivery).
|
|
59
|
-
|
|
60
|
-
### `on_resolved { ... }`
|
|
61
|
-
|
|
62
|
-
Called when all subscribers have resolved, regardless of outcome. Used for cleanup (e.g., removing from pending map, signaling backpressure).
|
|
63
|
-
|
|
64
|
-
### `on_dead_letter { |subscriber_id| ... }`
|
|
65
|
-
|
|
66
|
-
Called for each NACK, receiving the subscriber ID.
|
data/docs/api/delivery.md
DELETED
|
@@ -1,73 +0,0 @@
|
|
|
1
|
-
# Delivery
|
|
2
|
-
|
|
3
|
-
`TypedBus::Delivery`
|
|
4
|
-
|
|
5
|
-
Envelope wrapping a message delivered to a single subscriber. Each subscriber receives its own Delivery instance for the same message.
|
|
6
|
-
|
|
7
|
-
## Constructor
|
|
8
|
-
|
|
9
|
-
### `Delivery.new(message, channel_name:, subscriber_id:, timeout:, on_ack:, on_nack:)`
|
|
10
|
-
|
|
11
|
-
| Parameter | Default | Description |
|
|
12
|
-
|-----------|---------|-------------|
|
|
13
|
-
| `message` | required | The published payload |
|
|
14
|
-
| `channel_name` | required | Originating channel name |
|
|
15
|
-
| `subscriber_id` | required | Target subscriber's ID |
|
|
16
|
-
| `timeout` | `nil` | Seconds before auto-nack; `nil` = no timeout |
|
|
17
|
-
| `on_ack` | `nil` | Callback proc called with subscriber_id on ack |
|
|
18
|
-
| `on_nack` | `nil` | Callback proc called with subscriber_id on nack |
|
|
19
|
-
|
|
20
|
-
!!! note
|
|
21
|
-
Deliveries are created internally by `Channel#publish`. You don't normally construct them directly.
|
|
22
|
-
|
|
23
|
-
## Attributes
|
|
24
|
-
|
|
25
|
-
### `message` → `Object`
|
|
26
|
-
|
|
27
|
-
The published payload.
|
|
28
|
-
|
|
29
|
-
### `channel_name` → `Symbol`
|
|
30
|
-
|
|
31
|
-
The originating channel.
|
|
32
|
-
|
|
33
|
-
### `subscriber_id` → `Integer`
|
|
34
|
-
|
|
35
|
-
The target subscriber's ID.
|
|
36
|
-
|
|
37
|
-
## Resolution
|
|
38
|
-
|
|
39
|
-
### `ack!`
|
|
40
|
-
|
|
41
|
-
Mark as successfully processed. Cancels the timeout timer.
|
|
42
|
-
|
|
43
|
-
**Raises:** `RuntimeError` if already resolved.
|
|
44
|
-
|
|
45
|
-
### `nack!`
|
|
46
|
-
|
|
47
|
-
Mark as failed. Routes to the dead letter queue. Cancels the timeout timer.
|
|
48
|
-
|
|
49
|
-
**Raises:** `RuntimeError` if already resolved.
|
|
50
|
-
|
|
51
|
-
## State
|
|
52
|
-
|
|
53
|
-
### `pending?` → `Boolean`
|
|
54
|
-
|
|
55
|
-
Not yet resolved.
|
|
56
|
-
|
|
57
|
-
### `acked?` → `Boolean`
|
|
58
|
-
|
|
59
|
-
Successfully acknowledged.
|
|
60
|
-
|
|
61
|
-
### `nacked?` → `Boolean`
|
|
62
|
-
|
|
63
|
-
Explicitly rejected or timed out.
|
|
64
|
-
|
|
65
|
-
### `timed_out?` → `Boolean`
|
|
66
|
-
|
|
67
|
-
True if the nack was caused by timeout (as opposed to explicit `nack!`).
|
|
68
|
-
|
|
69
|
-
## Timeout
|
|
70
|
-
|
|
71
|
-
### `cancel_timeout`
|
|
72
|
-
|
|
73
|
-
Cancel the timeout timer without resolving the delivery. Used internally during `close` and `clear!`.
|
data/docs/api/index.md
DELETED
|
@@ -1,45 +0,0 @@
|
|
|
1
|
-
# API Reference
|
|
2
|
-
|
|
3
|
-
Complete method reference for every TypedBus class.
|
|
4
|
-
|
|
5
|
-
## Module
|
|
6
|
-
|
|
7
|
-
- [`TypedBus`](#typedbus-module) — top-level configuration and logger access
|
|
8
|
-
|
|
9
|
-
## Classes
|
|
10
|
-
|
|
11
|
-
- [Configuration](configuration.md) — global defaults and cascade resolution
|
|
12
|
-
- [MessageBus](message-bus.md) — registry facade for named channels
|
|
13
|
-
- [Channel](channel.md) — named pub/sub topic with acknowledgment tracking
|
|
14
|
-
- [Delivery](delivery.md) — per-subscriber message envelope
|
|
15
|
-
- [DeliveryTracker](delivery-tracker.md) — aggregates subscriber responses per publish
|
|
16
|
-
- [DeadLetterQueue](dead-letter-queue.md) — collects failed deliveries
|
|
17
|
-
- [Stats](stats.md) — per-channel counter map
|
|
18
|
-
|
|
19
|
-
---
|
|
20
|
-
|
|
21
|
-
## TypedBus Module
|
|
22
|
-
|
|
23
|
-
### `TypedBus.configuration`
|
|
24
|
-
|
|
25
|
-
Returns the global `Configuration` instance.
|
|
26
|
-
|
|
27
|
-
### `TypedBus.configuration=(config)`
|
|
28
|
-
|
|
29
|
-
Replaces the global `Configuration` instance.
|
|
30
|
-
|
|
31
|
-
### `TypedBus.configure { |config| ... }`
|
|
32
|
-
|
|
33
|
-
Yields the global `Configuration` for block-style setup.
|
|
34
|
-
|
|
35
|
-
### `TypedBus.reset_configuration!`
|
|
36
|
-
|
|
37
|
-
Restores factory defaults.
|
|
38
|
-
|
|
39
|
-
### `TypedBus.logger`
|
|
40
|
-
|
|
41
|
-
Shortcut for `TypedBus.configuration.logger`.
|
|
42
|
-
|
|
43
|
-
### `TypedBus.logger=(log)`
|
|
44
|
-
|
|
45
|
-
Shortcut for `TypedBus.configuration.logger = log`.
|
data/docs/api/message-bus.md
DELETED
|
@@ -1,101 +0,0 @@
|
|
|
1
|
-
# MessageBus
|
|
2
|
-
|
|
3
|
-
`TypedBus::MessageBus`
|
|
4
|
-
|
|
5
|
-
Registry facade for named, typed pub/sub channels with shared statistics.
|
|
6
|
-
|
|
7
|
-
## Constructor
|
|
8
|
-
|
|
9
|
-
### `MessageBus.new(timeout:, max_pending:, throttle:)`
|
|
10
|
-
|
|
11
|
-
Creates a new bus. All parameters default to `:use_default`, inheriting from the global configuration.
|
|
12
|
-
|
|
13
|
-
| Parameter | Default | Description |
|
|
14
|
-
|-----------|---------|-------------|
|
|
15
|
-
| `timeout` | `:use_default` | Delivery ACK deadline for channels |
|
|
16
|
-
| `max_pending` | `:use_default` | Backpressure limit for channels |
|
|
17
|
-
| `throttle` | `:use_default` | Throttle threshold for channels |
|
|
18
|
-
|
|
19
|
-
```ruby
|
|
20
|
-
bus = TypedBus::MessageBus.new(timeout: 10, throttle: 0.5)
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
## Attributes
|
|
24
|
-
|
|
25
|
-
### `stats` → `Stats`
|
|
26
|
-
|
|
27
|
-
The shared Stats instance for all channels on this bus.
|
|
28
|
-
|
|
29
|
-
### `config` → `Configuration`
|
|
30
|
-
|
|
31
|
-
The bus-level Configuration (independent copy of global config with overrides applied).
|
|
32
|
-
|
|
33
|
-
## Channel Management
|
|
34
|
-
|
|
35
|
-
### `add_channel(name, type:, timeout:, max_pending:, throttle:)` → `Channel`
|
|
36
|
-
|
|
37
|
-
Register a named channel. Parameters default to `:use_default`, inheriting from the bus config.
|
|
38
|
-
|
|
39
|
-
| Parameter | Default | Description |
|
|
40
|
-
|-----------|---------|-------------|
|
|
41
|
-
| `name` | required | `Symbol` channel name |
|
|
42
|
-
| `type` | `nil` | Optional type constraint |
|
|
43
|
-
| `timeout` | `:use_default` | Delivery ACK deadline in seconds |
|
|
44
|
-
| `max_pending` | `:use_default` | Backpressure limit |
|
|
45
|
-
| `throttle` | `:use_default` | Throttle threshold |
|
|
46
|
-
|
|
47
|
-
### `remove_channel(name)`
|
|
48
|
-
|
|
49
|
-
Close and remove a channel. No-op for unknown channels.
|
|
50
|
-
|
|
51
|
-
### `channel?(name)` → `Boolean`
|
|
52
|
-
|
|
53
|
-
Check if a channel exists.
|
|
54
|
-
|
|
55
|
-
### `channel_names` → `Array<Symbol>`
|
|
56
|
-
|
|
57
|
-
List registered channel names.
|
|
58
|
-
|
|
59
|
-
## Pub/Sub
|
|
60
|
-
|
|
61
|
-
### `publish(channel_name, message)` → `DeliveryTracker`, `nil`
|
|
62
|
-
|
|
63
|
-
Publish a message to a named channel. Returns the `DeliveryTracker` or `nil` if no subscribers.
|
|
64
|
-
|
|
65
|
-
**Raises:** `ArgumentError` for unknown channels, type mismatches. `RuntimeError` for closed channels.
|
|
66
|
-
|
|
67
|
-
### `subscribe(channel_name, &block)` → `Integer`
|
|
68
|
-
|
|
69
|
-
Subscribe to a named channel. Returns the subscriber ID.
|
|
70
|
-
|
|
71
|
-
### `unsubscribe(channel_name, id_or_block)`
|
|
72
|
-
|
|
73
|
-
Remove a subscriber by ID or block reference.
|
|
74
|
-
|
|
75
|
-
## Query
|
|
76
|
-
|
|
77
|
-
### `pending?(channel_name)` → `Boolean`
|
|
78
|
-
|
|
79
|
-
Check if a channel has unresolved deliveries.
|
|
80
|
-
|
|
81
|
-
### `pending_count(channel_name)` → `Integer`
|
|
82
|
-
|
|
83
|
-
Number of unresolved deliveries.
|
|
84
|
-
|
|
85
|
-
### `dead_letters(channel_name)` → `DeadLetterQueue`
|
|
86
|
-
|
|
87
|
-
Access a channel's dead letter queue.
|
|
88
|
-
|
|
89
|
-
## Lifecycle
|
|
90
|
-
|
|
91
|
-
### `close(channel_name)`
|
|
92
|
-
|
|
93
|
-
Close a specific channel. Pending deliveries are force-NACKed.
|
|
94
|
-
|
|
95
|
-
### `close_all`
|
|
96
|
-
|
|
97
|
-
Close all channels.
|
|
98
|
-
|
|
99
|
-
### `clear!`
|
|
100
|
-
|
|
101
|
-
Close all channels, clear DLQs, and reset stats.
|
data/docs/api/stats.md
DELETED
|
@@ -1,50 +0,0 @@
|
|
|
1
|
-
# Stats
|
|
2
|
-
|
|
3
|
-
`TypedBus::Stats`
|
|
4
|
-
|
|
5
|
-
Simple counter map for message bus activity. Fiber-safe — no mutex needed within a single Async reactor.
|
|
6
|
-
|
|
7
|
-
## Constructor
|
|
8
|
-
|
|
9
|
-
### `Stats.new`
|
|
10
|
-
|
|
11
|
-
Creates a new Stats instance with no counters.
|
|
12
|
-
|
|
13
|
-
## Methods
|
|
14
|
-
|
|
15
|
-
### `increment(key)` → `Integer`
|
|
16
|
-
|
|
17
|
-
Increment a named counter. Returns the new value.
|
|
18
|
-
|
|
19
|
-
```ruby
|
|
20
|
-
stats.increment(:orders_published) # => 1
|
|
21
|
-
stats.increment(:orders_published) # => 2
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
### `[](key)` → `Integer`
|
|
25
|
-
|
|
26
|
-
Read a counter value. Returns `0` for unknown keys.
|
|
27
|
-
|
|
28
|
-
```ruby
|
|
29
|
-
stats[:orders_published] # => 2
|
|
30
|
-
stats[:nonexistent] # => 0
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
### `reset!`
|
|
34
|
-
|
|
35
|
-
Zero all counters. Keys are preserved, values set to `0`.
|
|
36
|
-
|
|
37
|
-
### `to_h` → `Hash<Symbol, Integer>`
|
|
38
|
-
|
|
39
|
-
Return a snapshot (dup) of all counters.
|
|
40
|
-
|
|
41
|
-
```ruby
|
|
42
|
-
stats.to_h
|
|
43
|
-
# => { orders_published: 2, orders_delivered: 1 }
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
## Attributes
|
|
47
|
-
|
|
48
|
-
### `data` → `Hash`
|
|
49
|
-
|
|
50
|
-
Direct access to the underlying counter hash. Prefer `[]` and `to_h` for read access.
|
|
@@ -1,38 +0,0 @@
|
|
|
1
|
-
# Concurrency Model
|
|
2
|
-
|
|
3
|
-
TypedBus uses **fiber-only concurrency** powered by the [async](https://github.com/socketry/async) gem. There are no mutexes and no threads anywhere in the library.
|
|
4
|
-
|
|
5
|
-
## Single Reactor
|
|
6
|
-
|
|
7
|
-
All TypedBus state lives within a single Async reactor. The `Async { }` block creates the reactor, and all publish/subscribe operations run as fibers within it.
|
|
8
|
-
|
|
9
|
-
```ruby
|
|
10
|
-
Async do
|
|
11
|
-
bus.publish(:events, "hello") # runs as a fiber
|
|
12
|
-
bus.publish(:events, "world") # runs as a fiber
|
|
13
|
-
end
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
## Why Fibers?
|
|
17
|
-
|
|
18
|
-
Ruby fibers provide cooperative concurrency:
|
|
19
|
-
|
|
20
|
-
- **No race conditions** — only one fiber runs at a time within a reactor
|
|
21
|
-
- **No locks needed** — shared state is safe without mutexes
|
|
22
|
-
- **Yielding, not blocking** — `sleep`, backpressure waits, and throttle delays yield the fiber, allowing other fibers to progress
|
|
23
|
-
|
|
24
|
-
## Where Async Tasks Are Created
|
|
25
|
-
|
|
26
|
-
TypedBus creates Async tasks in two places:
|
|
27
|
-
|
|
28
|
-
1. **Subscriber dispatch** — each subscriber's block runs in its own `Async` task when a message is published. This allows multiple subscribers to process concurrently.
|
|
29
|
-
|
|
30
|
-
2. **Delivery timeout** — each Delivery starts an `Async` task that sleeps for the timeout duration and then auto-nacks if the delivery is still pending.
|
|
31
|
-
|
|
32
|
-
## Implications
|
|
33
|
-
|
|
34
|
-
- `publish` must be called inside an `Async { }` block (or within an existing reactor)
|
|
35
|
-
- Subscriber blocks execute concurrently with each other
|
|
36
|
-
- A subscriber that never returns will keep its Delivery pending until the timeout fires
|
|
37
|
-
- Backpressure (`wait_for_capacity`) blocks the *publishing fiber* — other fibers continue running
|
|
38
|
-
- Throttle delays (`sleep`) yield the *publishing fiber* — other fibers continue running
|
|
@@ -1,76 +0,0 @@
|
|
|
1
|
-
# Configuration Cascade
|
|
2
|
-
|
|
3
|
-
TypedBus resolves configurable parameters through three tiers:
|
|
4
|
-
|
|
5
|
-
```
|
|
6
|
-
Global → Bus → Channel
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
Each tier inherits from the one above unless explicitly overridden.
|
|
10
|
-
|
|
11
|
-
## How It Works
|
|
12
|
-
|
|
13
|
-
```mermaid
|
|
14
|
-
flowchart LR
|
|
15
|
-
G[Global Config] -->|dup| B[Bus Config]
|
|
16
|
-
B -->|resolve| C[Channel Values]
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
1. **Global** — `TypedBus.configure { |c| ... }` sets defaults for all buses. Stored as a singleton `Configuration` instance.
|
|
20
|
-
2. **Bus** — `MessageBus.new(timeout: 10)` creates a `dup` of the global config, then applies any explicit overrides. Each bus holds its own independent `Configuration`.
|
|
21
|
-
3. **Channel** — `bus.add_channel(:name, timeout: 5)` resolves values via the bus's config. The channel receives fully resolved scalars — it has no awareness of the cascade.
|
|
22
|
-
|
|
23
|
-
## The `:use_default` Sentinel
|
|
24
|
-
|
|
25
|
-
The sentinel value `:use_default` means "inherit from the tier above." It is the default for all cascade parameters at both bus and channel levels.
|
|
26
|
-
|
|
27
|
-
This sentinel is necessary to distinguish "not provided" from an explicit `nil`. For `max_pending`, `nil` means "unbounded" — a meaningful value that must be distinguishable from "use whatever the parent says."
|
|
28
|
-
|
|
29
|
-
```ruby
|
|
30
|
-
# These are different:
|
|
31
|
-
bus.add_channel(:a) # max_pending inherited from bus
|
|
32
|
-
bus.add_channel(:b, max_pending: nil) # max_pending explicitly unbounded
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Cascaded Parameters
|
|
36
|
-
|
|
37
|
-
| Parameter | Default | Cascades? |
|
|
38
|
-
|-----------|---------|-----------|
|
|
39
|
-
| `timeout` | `30` | Global → Bus → Channel |
|
|
40
|
-
| `max_pending` | `nil` | Global → Bus → Channel |
|
|
41
|
-
| `throttle` | `0.0` | Global → Bus → Channel |
|
|
42
|
-
| `logger` | `nil` | Global only |
|
|
43
|
-
| `log_level` | `Logger::INFO` | Global only |
|
|
44
|
-
|
|
45
|
-
`logger` and `log_level` are global-only because the logger is a shared resource. All buses and channels read the logger via `TypedBus.logger`.
|
|
46
|
-
|
|
47
|
-
## Isolation
|
|
48
|
-
|
|
49
|
-
Each bus gets an independent config snapshot via `dup`. Changing a bus's config does not affect the global or other buses:
|
|
50
|
-
|
|
51
|
-
```ruby
|
|
52
|
-
TypedBus.configure { |c| c.timeout = 60 }
|
|
53
|
-
|
|
54
|
-
bus_a = TypedBus::MessageBus.new(timeout: 10)
|
|
55
|
-
bus_b = TypedBus::MessageBus.new(timeout: 99)
|
|
56
|
-
|
|
57
|
-
bus_a.config.timeout # => 10
|
|
58
|
-
bus_b.config.timeout # => 99
|
|
59
|
-
TypedBus.configuration.timeout # => 60 (unchanged)
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
## Implementation
|
|
63
|
-
|
|
64
|
-
The cascade logic lives in `Configuration#resolve`:
|
|
65
|
-
|
|
66
|
-
```ruby
|
|
67
|
-
def resolve(timeout: :use_default, max_pending: :use_default, throttle: :use_default)
|
|
68
|
-
{
|
|
69
|
-
timeout: timeout == :use_default ? @timeout : timeout,
|
|
70
|
-
max_pending: max_pending == :use_default ? @max_pending : max_pending,
|
|
71
|
-
throttle: throttle == :use_default ? @throttle : throttle
|
|
72
|
-
}
|
|
73
|
-
end
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
`MessageBus#initialize` calls `resolve` on the global config. `MessageBus#add_channel` calls `resolve` on the bus config. The channel receives the final resolved values.
|
data/docs/architecture/index.md
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
# Architecture
|
|
2
|
-
|
|
3
|
-
TypedBus is a small library with a clear internal structure. This section explains the core design decisions.
|
|
4
|
-
|
|
5
|
-
- [Publish Flow](publish-flow.md) — what happens when you call `publish`
|
|
6
|
-
- [Concurrency Model](concurrency-model.md) — fiber-only design with Async
|
|
7
|
-
- [Configuration Cascade](configuration-cascade.md) — three-tier parameter resolution
|