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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 224bbbe8b04be67cc4dae6a52e0f92dd3ca2deb4effc25cf3517b933156f593c
4
- data.tar.gz: 611c39a052bd96acdab879a75f7433b0908c1b07d7481df44aa0d246b2caa8a8
3
+ metadata.gz: 46e0e8e4a5166c89a104b9cdf73e134513974dccec04f1a40c2efd2195288550
4
+ data.tar.gz: 192c12c30a5ef0d1c82b6d526acd768241e49ccb40a8c31a8b948d39f0f36860
5
5
  SHA512:
6
- metadata.gz: b4186843ef3b9cb04c7f74654b4d701f807b93fe52d9a197a87917830fda00ebc694c6b6322d6ea488c69989a87dc00c8dbbd1f1e0bd11b1dfb01671a556de5e
7
- data.tar.gz: 792c3c97efdb51798e8149513ea8a51b15f711be73c8e496a80d9fd290fd2e57a12fdf73158acc150e83873758091a19840594471dc1f678c6be493928aec8ac
6
+ metadata.gz: 8dd92cf4e4a53a3ab7cd30655395166f54f3fc518591103d8ccffbda094f9f56ead2f48f00f6338d919ec0cff6f9c5eefb29a302ebf04755d8f89e6b7c181238
7
+ data.tar.gz: f94ac001714274ee658c90e682dd0a144ab957e8ca795cfc50f5bfeeeba5bd352b2d0dcb981e25e61de19e96d51d228a97fd7a9d225a61e34e83f236547b3f08
data/CHANGELOG.md CHANGED
@@ -1,5 +1,163 @@
1
1
  ## [Unreleased]
2
2
 
3
+ ## [0.1.0] - 2026-11-19
4
+
5
+ First release since 0.0.1. In short:
6
+
7
+ - **Ruby 4.0 or newer is now required.** Ruby 3.2 and 3.3 are no longer
8
+ supported.
9
+ - **Reliability fixes.** Publishers and deliveries no longer hang or stay
10
+ pending forever when a channel closes, a subscriber unsubscribes, or an
11
+ `on_dead_letter` callback raises; `DeadLetterQueue#drain` no longer loses
12
+ or loops on entries; stats no longer miscount.
13
+ - **Stricter validation.** Invalid `type:`, `throttle:`, `max_pending:` and
14
+ `log_level` values, and `subscribe` without a block, now raise
15
+ `ArgumentError` up front instead of failing or hanging later.
16
+ - **A much smaller gem.** The package holds only the library and top-level
17
+ docs: about 15 KB instead of 19.9 MB.
18
+ - **Project tooling.** CI, Dependabot, a LICENSE file, `llms.txt`, and
19
+ quality gates run through asgard in place of Rake.
20
+
21
+ ### Fixed
22
+
23
+ - `Channel#close` now nacks every pending delivery even when an
24
+ `on_dead_letter` callback raises, and `MessageBus#close_all` closes every
25
+ channel even when closing one raises. Both re-raise the first error once
26
+ all the work is done. Previously the first error stopped the loop, so with
27
+ `timeout: nil` the remaining deliveries stayed pending forever and later
28
+ channels were left open (#75).
29
+ - `MessageBus#publish` no longer counts a message in `<channel>_published`
30
+ when the channel is already closed or the message has the wrong type.
31
+ Those publishes raise and were still counted, which inflated the counter
32
+ and skewed rates computed from it.
33
+ - `Channel#subscribe` and `MessageBus#subscribe` now raise `ArgumentError`
34
+ when called without a block. Previously a blockless subscriber was
35
+ registered with a nil handler, so every published message waited on an
36
+ acknowledgment that could never arrive, and a bounded channel blocked
37
+ publishers forever (#16). Found and fixed by BomberBot.
38
+ - `DeadLetterQueue#drain` with a block no longer loses entries when the
39
+ block raises, and no longer loops when the block re-queues entries. It
40
+ empties the queue first and yields that snapshot once; entries added
41
+ during the drain (such as a retry that fails again) wait for the next
42
+ drain. If the block raises, the entry it was handling and the ones not
43
+ yet yielded go back to the front of the queue (#6). If the block exits
44
+ early with `break` or `return`, the entry it was handling counts as done
45
+ and the ones not yet yielded go back on the queue; in 0.0.1 they were
46
+ lost (#29). Found and fixed by BomberBot.
47
+ - Declare `logger` as a runtime dependency in the gemspec so
48
+ `require "typed_bus"` loads under Bundler on Ruby 4.0+, where `logger`
49
+ is a bundled gem rather than a default gem. Found and fixed by BomberBot.
50
+ - A throttled, bounded channel no longer hangs forever when published to at
51
+ full capacity. Previously the adaptive backoff computed an infinite delay
52
+ (`1 / 0`) and slept indefinitely; the throttle now yields at full capacity
53
+ and lets backpressure block the publisher instead. Found and fixed by
54
+ BomberBot.
55
+ - The packaged gem now contains only the git-tracked `lib/**/*.rb` files,
56
+ `README.md`, `CHANGELOG.md`, and `LICENSE`. It previously shipped the
57
+ docs site (including a 16.6 MB GIF and a 2.7 MB MP4), examples, CI
58
+ workflows, and local dotfiles, making the `.gem` about 19.9 MB instead
59
+ of 15 KB (#3). Found and fixed by BomberBot.
60
+ - Unsubscribing a subscriber while a publish is fanning out no longer leaves
61
+ that message's delivery tracker pending forever (and, on a bounded channel,
62
+ holding a `max_pending` slot). `Channel#publish` now snapshots subscriber
63
+ ids and handlers together, so a subscriber removed mid-publish still
64
+ receives that one message (#4).
65
+ - `max_pending` must be `nil` or a positive `Integer`. `Channel.new`,
66
+ `MessageBus.new`, `MessageBus#add_channel`, and
67
+ `Configuration#max_pending=` raise `ArgumentError` for `0`, negative, or
68
+ non-Integer values instead of hanging or crashing on a later publish (#5).
69
+ - Logging examples 11-14 now print their DEBUG output (#17), and
70
+ `examples/15_performance.rb` no longer requires the unused `csv` gem (#19).
71
+ - `Channel#publish` now raises the closed-channel error when the channel is
72
+ closed while the publisher is sleeping in the throttle or blocked on
73
+ backpressure. Previously that publish still delivered into the closed
74
+ channel and left a delivery pending until its timeout.
75
+ - A raising `on_dead_letter` callback no longer drops the `nacked`/`timed_out`
76
+ and `dead_lettered` stats for that delivery. The channel now records them
77
+ before it pushes to the dead letter queue (#36).
78
+ - The DEBUG "backpressure: waiting for capacity" and "capacity available"
79
+ lines are logged only when a publisher actually waits, not on every
80
+ publish to a bounded channel (#31).
81
+ - `timeout: nil` now logs as `timeout=none` instead of `timeout=s`, and the
82
+ option tables document that `nil` means never auto-nack (#27).
83
+ - `MessageBus#add_channel` logs `added channel :name` after the channel is
84
+ built, instead of `adding channel :name` before validation, so a rejected
85
+ `add_channel` no longer logs as if the channel had been added (#47).
86
+ - `Channel#close` now always wakes publishers waiting for capacity, so they
87
+ raise the closed error even when an `on_dead_letter` callback raises during
88
+ the force-nack. Previously such a publisher stayed blocked forever with
89
+ `timeout: nil` (#43).
90
+ - `DeliveryTracker#on_complete`, `#on_resolved` and `#on_dead_letter` now add
91
+ a callback instead of replacing the previous one. Hooking the tracker that
92
+ `publish` returns no longer replaces the channel's own bookkeeping, which left
93
+ the tracker pending, skipped the `delivered` stat, and on a bounded channel
94
+ blocked the next `publish` forever (#50).
95
+ - `Channel#publish` and `MessageBus#publish` YARD now document the `nil`
96
+ return when there are no subscribers, and the `throttle` params list the
97
+ accepted `Numeric`/`nil` values (#42).
98
+ - Closing a channel from a subscriber handler while `publish` is still fanning
99
+ out no longer leaves the remaining subscribers' deliveries pending. They are
100
+ nacked into the dead letter queue instead of being dispatched (#48).
101
+ - `Configuration#log_level=` now rejects an invalid level before storing it.
102
+ Previously a bad level was stored anyway, leaving `log_level` out of step
103
+ with the logger, or raising only later at `logger=` (#74).
104
+
105
+ ### Changed
106
+
107
+ - **Breaking:** Ruby 4.0 or newer is required
108
+ (`required_ruby_version = ">= 4.0"`, previously `>= 3.2.0`). Support for
109
+ Ruby 3.2 and 3.3 is dropped, and CI runs on Ruby 4.0 only.
110
+ - The `MessageBus` "Unknown channel" `ArgumentError` now shows the name with
111
+ `inspect` and lists the registered channels, e.g.
112
+ `Unknown channel: "orders" (registered: :orders, :payments)`, so a
113
+ String/Symbol mix-up is visible. Found and fixed by BomberBot.
114
+ - A channel's `type:` must be `nil`, a `Class`, or a `Module`. `Channel.new`
115
+ and `MessageBus#add_channel` raise `ArgumentError` for anything else;
116
+ previously the channel was created and every publish raised a bare
117
+ `TypeError` (#34).
118
+ - `throttle` must be `nil`, `0`, or a number strictly between 0 and 1.
119
+ `Configuration#throttle=`, `MessageBus.new`, `MessageBus#add_channel`, and
120
+ `Channel.new` raise `ArgumentError` for anything else as soon as it is set.
121
+ Previously an out-of-range bus or global throttle failed only when a
122
+ channel was added, and a non-numeric one silently turned throttling
123
+ off (#33).
124
+ - `ratatui_ruby` and `aigcm` moved to an optional `:extras` bundle group;
125
+ the default bundle no longer builds a Rust native extension.
126
+ - Refreshed `Gemfile.lock` to async 2.46.0 (#14).
127
+ - Refreshed the development `Gemfile.lock` with a full `bundle update`
128
+ (minitest 6.1, rake 13.4, simplecov 1.3, rdoc 8.1, prism 2.1) (#41).
129
+ - Removed the no-op `Configuration#initialize_copy` override (#21).
130
+ - `Channel#publish` is split into small private steps, and repeated lookups
131
+ in `Channel`, `DeliveryTracker` and `MessageBus` are tidied. No public API
132
+ or behaviour change.
133
+ - Development tasks now run through asgard (`.loki`, importing the shared
134
+ task files from the sibling `dev` repository) instead of Rake. The
135
+ `Rakefile` and the `rake` development dependency are removed; CI runs the
136
+ suite with plain `ruby`.
137
+ - The documentation now states what `<channel>_nacked` counts and that the
138
+ delivery counters are per delivery, not per message (#78), lists the
139
+ `ArgumentError`s the constructors raise, and describes how publishers
140
+ waiting on a channel are woken when it closes.
141
+
142
+ ### Added
143
+
144
+ - MIT `LICENSE` file (#11); `documentation_uri`, `bug_tracker_uri`, and
145
+ `rubygems_mfa_required` gemspec metadata (#12).
146
+ - CI workflow running the test suite plus a load smoke test outside the dev
147
+ bundle (#20); Dependabot configuration (#15), with its update PRs
148
+ targeting the `develop` branch (#40).
149
+ - `llms.txt`, a summary of the gem for LLM readers (#65), also served from
150
+ the docs site at `/typed_bus/llms.txt` (#77).
151
+ - `examples/15_performance.rb`, a live terminal dashboard of throughput,
152
+ memory and GC built on `ratatui_ruby` (optional `:extras` bundle group).
153
+ - Quality gates run with `asgard quality`: RuboCop, Flog, Flay, Reek, typos,
154
+ bundler-audit, Exhale and SCRAP, configured by `.rubocop.yml`, `.reek.yml`
155
+ and `_typos.toml`.
156
+
157
+ ## [0.0.1] - 2026-02-07
158
+
159
+ - Initial release
160
+
3
161
  ### Changed
4
162
 
5
163
  - Renamed gem from `async_typed_bus` to `typed_bus` (module `TypedBus`).
@@ -13,7 +171,3 @@
13
171
  - `MessageBus.new(throttle: 0.5)` sets a bus-wide default applied to every
14
172
  `add_channel` call. Per-channel override or `throttle: 0.0` to disable.
15
173
  - `:throttled` stat counter recorded each time a publish is rate-limited.
16
-
17
- ## [0.1.0] - 2026-02-06
18
-
19
- - Initial release
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dewayne VanHoozer
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  <table>
5
5
  <tr>
6
6
  <td width="50%" align="center" valign="top">
7
- <img src="docs/assets/images/typed_bus.gif" alt="TypedBus" width="438"><br>
7
+ <img src="docs/assets/images/typed_bus.png" alt="TypedBus" width="438"><br>
8
8
  <a href="https://madbomber.github.io/typed_bus">Comprehensive Documentation</a>
9
9
  </td>
10
10
  <td width="50%" valign="top">
@@ -67,10 +67,10 @@ channel = TypedBus::Channel.new(:orders, timeout: 10)
67
67
 
68
68
  | Option | Type | Default | Description |
69
69
  |--------|------|---------|-------------|
70
- | `type` | `Class` | `nil` | Restricts published messages to a specific class |
71
- | `timeout` | `Numeric` | `30` | Seconds before unresolved deliveries auto-nack |
72
- | `max_pending` | `Integer` | `nil` | Backpressure limit; `nil` = unbounded |
73
- | `throttle` | `Float` | `0.0` | Remaining-capacity ratio where backoff begins; `0.0` = disabled |
70
+ | `type` | `Class` or `Module` | `nil` | Restricts published messages to a specific class or module |
71
+ | `timeout` | `Numeric`, `nil` | `30` | Seconds before unresolved deliveries auto-nack; `nil` = never auto-nack |
72
+ | `max_pending` | `Integer`, `nil` | `nil` | Backpressure limit (positive `Integer`); `nil` = unbounded |
73
+ | `throttle` | `Numeric`, `nil` | `0.0` | Remaining-capacity ratio where backoff begins; `0` or `nil` = off, else strictly between `0` and `1`; requires `max_pending` |
74
74
 
75
75
  ### Typed Channels
76
76
 
@@ -176,7 +176,11 @@ channel = TypedBus::Channel.new(:work,
176
176
 
177
177
  When a bounded channel approaches capacity, adaptive throttling progressively slows publishers before they hit the hard block.
178
178
 
179
- Set `throttle` to a `Float` between `0.0` (exclusive) and `1.0` (exclusive). The value is the remaining-capacity ratio at which backoff begins. Below that threshold, each publish sleeps for `1 / (max_pending * remaining_ratio)` seconds.
179
+ Set `throttle` to a number strictly between `0` and `1`, on a channel that also sets `max_pending`. The value is the remaining-capacity ratio at which backoff begins. Below that threshold, each publish sleeps for `1 / (max_pending * remaining_ratio)` seconds.
180
+
181
+ - `throttle: 0.0` (or `0`, or `nil`) disables throttling (the default)
182
+ - Any other value outside that range raises `ArgumentError` as soon as it is set, in `Configuration#throttle=`, `MessageBus.new`, `add_channel`, or `Channel.new`
183
+ - A non-zero `throttle` without `max_pending` raises `ArgumentError` when the channel is created
180
184
 
181
185
  ```ruby
182
186
  channel = TypedBus::Channel.new(:pipeline,
@@ -220,9 +224,9 @@ TypedBus resolves parameters through a three-tier cascade: **Global → Bus →
220
224
 
221
225
  | Parameter | Default | Description |
222
226
  |-----------|---------|-------------|
223
- | `timeout` | `30` | Delivery ACK deadline in seconds |
224
- | `max_pending` | `nil` | Backpressure limit; `nil` = unbounded |
225
- | `throttle` | `0.0` | Remaining-capacity ratio where backoff begins; `0.0` = disabled |
227
+ | `timeout` | `30` | Delivery ACK deadline in seconds; `nil` = never auto-nack |
228
+ | `max_pending` | `nil` | Backpressure limit (positive `Integer`); `nil` = unbounded |
229
+ | `throttle` | `0.0` | Remaining-capacity ratio where backoff begins; `0` or `nil` = off, else strictly between `0` and `1`; requires `max_pending` |
226
230
  | `logger` | `nil` | Ruby Logger instance (global-only) |
227
231
  | `log_level` | `Logger::INFO` | Log level applied to the logger (global-only) |
228
232
 
@@ -326,7 +330,7 @@ bus.add_channel(:logs, throttle: 0.0)
326
330
  ```ruby
327
331
  bus.stats[:orders_published] # messages published
328
332
  bus.stats[:orders_delivered] # all subscribers acked
329
- bus.stats[:orders_nacked] # explicit nacks
333
+ bus.stats[:orders_nacked] # nacks: nack!, raising handler, close, or no subscribers
330
334
  bus.stats[:orders_timed_out] # delivery timeouts
331
335
  bus.stats[:orders_dead_lettered] # entries added to DLQ
332
336
  bus.stats[:orders_throttled] # publishes that were rate-limited
@@ -335,6 +339,10 @@ bus.stats.to_h # snapshot of all counters
335
339
  bus.stats.reset! # zero all counters
336
340
  ```
337
341
 
342
+ `published` and `delivered` count once per message. `nacked`, `timed_out` and
343
+ `dead_lettered` count once per subscriber delivery, so one publish to a channel
344
+ with three subscribers can add up to 3 to each of them.
345
+
338
346
  When using `Channel` directly, pass a `Stats` instance:
339
347
 
340
348
  ```ruby
@@ -342,6 +350,9 @@ stats = TypedBus::Stats.new
342
350
  channel = TypedBus::Channel.new(:work, stats: stats, timeout: 5)
343
351
  ```
344
352
 
353
+ A bare `Channel` records every counter except `published`, which
354
+ `MessageBus#publish` counts.
355
+
345
356
  ## Logging
346
357
 
347
358
  Assign a standard Ruby `Logger` to get structured log output from all components:
@@ -382,7 +393,7 @@ channel.clear!
382
393
 
383
394
  ```ruby
384
395
  bus.close_all # close every channel
385
- bus.clear! # close, clear DLQs, and reset stats
396
+ bus.clear! # discard pending deliveries and DLQ entries, reset stats; channels stay open
386
397
  ```
387
398
 
388
399
  ## Architecture
@@ -408,9 +419,10 @@ DeliveryTracker (aggregates N responses)
408
419
 
409
420
  ## Requirements
410
421
 
411
- - Ruby >= 3.2.0
422
+ - Ruby >= 4.0
412
423
  - [async](https://github.com/socketry/async) ~> 2.0
424
+ - [logger](https://github.com/ruby/logger)
413
425
 
414
426
  ## License
415
427
 
416
- MIT
428
+ [MIT](LICENSE)