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