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,101 +0,0 @@
1
- #!/usr/bin/env ruby
2
- # frozen_string_literal: true
3
-
4
- # 14 — Adaptive Rate Limiting (Throttle)
5
- #
6
- # Demonstrates asymptotic backoff using throttle: Float.
7
- # The value is the remaining-capacity ratio at which backoff begins.
8
- # Below that threshold, each publish sleeps for
9
- # 1 / (max_pending * remaining_ratio) seconds — progressively slower
10
- # as the channel fills, approaching a hard block at 0% remaining.
11
- #
12
- # max_pending: 20, throttle: 0.5
13
- # 50% remaining (10 slots) → delay = 1/(20*0.50) = 0.10s
14
- # 25% remaining ( 5 slots) → delay = 1/(20*0.25) = 0.20s
15
- # 10% remaining ( 2 slots) → delay = 1/(20*0.10) = 0.50s
16
- # 5% remaining ( 1 slot) → delay = 1/(20*0.05) = 1.00s
17
- # 0% remaining → hard block (existing behavior)
18
- #
19
- # Also shows bus-level defaults that apply to every channel.
20
-
21
- require "logger"
22
- require_relative "../lib/typed_bus"
23
-
24
- logger = Logger.new($stdout)
25
- logger.level = Logger::DEBUG
26
- logger.formatter = proc do |severity, datetime, _progname, msg|
27
- timestamp = datetime.strftime("%H:%M:%S.%L")
28
- color = case severity
29
- when "WARN" then "\e[33m"
30
- when "ERROR" then "\e[31m"
31
- when "DEBUG" then "\e[36m"
32
- when "INFO" then "\e[32m"
33
- else "\e[0m"
34
- end
35
- "#{color}#{timestamp} [#{severity.ljust(5)}]\e[0m #{msg}\n"
36
- end
37
-
38
- TypedBus.logger = logger
39
-
40
- # --- Example 1: Channel-level throttle ---
41
-
42
- puts "=== Channel-level throttle (50% threshold) ==="
43
- puts
44
-
45
- channel = TypedBus::Channel.new(
46
- :pipeline,
47
- type: Integer,
48
- timeout: 5,
49
- max_pending: 20,
50
- throttle: 0.5
51
- )
52
-
53
- # Slow subscriber — takes 0.1s per message
54
- channel.subscribe do |delivery|
55
- sleep 0.1
56
- delivery.ack!
57
- end
58
-
59
- Async do
60
- 30.times do |i|
61
- puts "--- Publisher: sending message #{i + 1} ---"
62
- channel.publish(i + 1)
63
- end
64
-
65
- sleep 2
66
- puts
67
- puts "All messages processed."
68
- channel.close
69
- end
70
-
71
- puts
72
- puts "=== Bus-level default throttle (50% threshold) ==="
73
- puts
74
-
75
- # --- Example 2: Bus-level defaults ---
76
-
77
- bus = TypedBus::MessageBus.new(throttle: 0.5)
78
-
79
- bus.add_channel(:orders, type: Integer, max_pending: 50, timeout: 5) # inherits 0.5
80
- bus.add_channel(:alerts, type: String, max_pending: 10, timeout: 5,
81
- throttle: 0.3) # overrides to 30%
82
- bus.add_channel(:logs, type: String, max_pending: 100, timeout: 5,
83
- throttle: 0.0) # disables throttle
84
-
85
- bus.subscribe(:orders) { |d| sleep 0.05; d.ack! }
86
- bus.subscribe(:alerts) { |d| d.ack! }
87
- bus.subscribe(:logs) { |d| d.ack! }
88
-
89
- Async do
90
- 10.times { |i| bus.publish(:orders, i + 1) }
91
- 3.times { |i| bus.publish(:alerts, "alert-#{i}") }
92
- 5.times { |i| bus.publish(:logs, "log-#{i}") }
93
-
94
- sleep 1
95
- puts
96
- puts "Bus stats: #{bus.stats.to_h.inspect}"
97
- bus.close_all
98
- end
99
-
100
- # Clean up
101
- TypedBus.logger = nil
data/examples/README.md DELETED
@@ -1,27 +0,0 @@
1
- # Examples
2
-
3
- Run any example from the project root:
4
-
5
- ```bash
6
- ruby -Ilib examples/01_basic_usage.rb
7
- ```
8
-
9
- ## Demos
10
-
11
- | # | File | Description |
12
- |---|------|-------------|
13
- | 00 | `00_config.rb` | Three-tier configuration cascade. Shows `TypedBus.configure` for global defaults, bus-level overrides, and per-channel overrides with inheritance and `reset_configuration!`. |
14
- | 01 | `01_basic_usage.rb` | Basic pub/sub with explicit acknowledgment. One channel, one subscriber, `ack!` after each message. |
15
- | 02 | `02_typed_channels.rb` | Type-constrained channels. Publishing the wrong type raises `ArgumentError` at the publish site. |
16
- | 03 | `03_multiple_subscribers.rb` | Fan-out delivery. Every subscriber gets its own `Delivery`; a message is only "delivered" when all subscribers ack. Shows `DeliveryTracker` state queries. |
17
- | 04 | `04_nack_and_dead_letters.rb` | Explicit rejection with `nack!`. Rejected deliveries route to the dead letter queue. Shows DLQ iteration and `drain` for retry. |
18
- | 05 | `05_delivery_timeout.rb` | Delivery deadlines. Subscribers that don't respond within the timeout are auto-nacked. Shows `timed_out?` flag to distinguish timeouts from explicit nacks. |
19
- | 06 | `06_backpressure.rb` | Bounded channels with `max_pending`. The publisher fiber blocks when the limit is reached and resumes as subscribers ack. |
20
- | 07 | `07_message_bus.rb` | `MessageBus` registry facade. Manages multiple typed channels, aggregates stats, and provides a single entry point for publish/subscribe. |
21
- | 08 | `08_error_handling.rb` | Edge case handling: subscriber exceptions (auto-nack), publishing with no subscribers (DLQ), unsubscribe mid-stream, close force-nacks pending deliveries, and publishing to a closed channel. |
22
- | 09 | `09_stats_and_monitoring.rb` | Per-channel stat counters (published, delivered, nacked, timed_out, dead_lettered). Combines DLQ callbacks with stats for real-time alerting. Shows `reset!`. |
23
- | 10 | `10_concurrent_pipeline.rb` | Multi-stage event pipeline: ingest, validate, process. Combines typed messages, backpressure, timeouts, DLQ monitoring, and graceful shutdown into a realistic scenario. |
24
- | 11 | `11_logging_basic.rb` | Structured logging via `TypedBus.logger`. Shows lifecycle log output for channel creation, subscriber registration, publish, delivery, ack, and tracker resolution. |
25
- | 12 | `12_logging_failures.rb` | Failure-path logging: explicit nacks, delivery timeouts, no-subscriber dead-lettering, and DLQ drain. Colorized output highlights warnings and errors. |
26
- | 13 | `13_logging_backpressure.rb` | Backpressure logging. Shows DEBUG-level messages as the publisher fiber blocks and resumes while a slow subscriber drains a bounded channel. |
27
- | 14 | `14_adaptive_throttling.rb` | Adaptive rate limiting with `throttle: Float`. Demonstrates asymptotic backoff as a bounded channel fills, plus bus-level throttle defaults with per-channel overrides. |
data/examples/temp.md DELETED
@@ -1,95 +0,0 @@
1
-
2
- You: what is the mathematical term of an orderly approach to a limit?
3
-
4
- AI:
5
- The mathematical term you're looking for is **convergence**.
6
-
7
- When a sequence or function approaches a limit in an orderly, systematic manner, we say it **converges** to that limit. The process itself is called **convergence**.
8
-
9
- For example:
10
- - A **sequence** converges to a limit if the terms get arbitrarily close to some value as you progress through the sequence
11
- - A **function** converges to a limit as the input approaches some value
12
- - A **series** converges if the sum of its terms approaches a finite value
13
-
14
- The opposite concept is **divergence**, where a sequence, function, or series does not approach any finite limit.
15
-
16
- There are also more specific terms depending on the context:
17
- - **Uniform convergence**: convergence that happens at the same rate across an entire domain
18
- - **Absolute convergence**: for series, when the sum of absolute values converges
19
- - **Conditional convergence**: for series, when the series converges but the series of absolute values does not
20
-
21
- Is there a specific type of convergence or context you'd like to know more about?
22
-
23
- You: convergence is not it I'm looking for something asemtonic half of a hyperbolic
24
-
25
- AI:
26
- Ah, you're looking for **asymptote**!
27
-
28
- An **asymptote** is a line that a curve approaches as it tends toward infinity. It's an orderly, systematic approach to a limit.
29
-
30
- There are different types of asymptotes:
31
- - **Horizontal asymptote**: a horizontal line that the curve approaches as x approaches infinity
32
- - **Vertical asymptote**: a vertical line that the curve approaches (usually where the function is undefined)
33
- - **Oblique (or slant) asymptote**: a diagonal line that the curve approaches
34
-
35
- Asymptotes are particularly common in hyperbolic functions and rational functions. For example, the hyperbola y = 1/x has:
36
- - A horizontal asymptote at y = 0 (as x → ∞)
37
- - A vertical asymptote at x = 0
38
-
39
- The word "asymptote" comes from Greek, meaning "not falling together" - describing how the curve and line get closer but never actually meet.
40
-
41
- Is that the term you were thinking of?
42
-
43
- You: what is the name of the curve that apporaches a vertical asymptote
44
-
45
- AI:
46
- The curve you're referring to is a **hyperbola**.
47
-
48
- A hyperbola is a type of conic section that has two branches, and each branch approaches a vertical asymptote. The most common example is the rectangular hyperbola:
49
-
50
- **y = 1/x**
51
-
52
- This hyperbola has:
53
- - A vertical asymptote at x = 0
54
- - A horizontal asymptote at y = 0
55
- - Two branches: one in the first quadrant and one in the third quadrant
56
-
57
- More generally, any hyperbola of the form:
58
- - **(x²/a²) - (y²/b²) = 1** (opens left-right, has vertical asymptotes)
59
- - **(y²/b²) - (x²/a²) = 1** (opens up-down, has horizontal asymptotes)
60
-
61
- will have asymptotes that the curve approaches but never touches.
62
-
63
- Hyperbolas are fundamental curves in mathematics and appear frequently in physics, engineering, and other applications. The defining characteristic is that the curve gets arbitrarily close to its asymptotes as you move along the curve.
64
-
65
- You: how do these terms apply in computer science to a dynamic rate limit backoff time where the backoff time gets larger the closer it approaches its limit
66
-
67
- AI:
68
- Great question! These mathematical concepts apply very well to backoff algorithms in computer science. Here's how:
69
-
70
- **Asymptotic Behavior in Backoff:**
71
- - The backoff time **approaches a vertical asymptote** (the maximum allowed wait time) but never quite reaches it
72
- - As retry attempts increase, the wait time grows larger in an **orderly, systematic way** (convergence toward the limit)
73
- - The curve of backoff time vs. retry attempts resembles a **hyperbola** - it rises steeply at first, then flattens out as it approaches the asymptote
74
-
75
- **Common Backoff Strategies:**
76
-
77
- 1. **Exponential Backoff** (most common):
78
- - Wait time = base × (multiplier ^ attempt_number)
79
- - Example: 1s, 2s, 4s, 8s, 16s, 32s...
80
- - Often capped at a maximum (the asymptote)
81
-
82
- 2. **Exponential Backoff with Jitter**:
83
- - Adds randomness to prevent thundering herd
84
- - Still approaches the maximum limit asymptotically
85
-
86
- 3. **Decorrelated Jitter**:
87
- - `backoff = min(max_backoff, base × 3 ^ attempt)`
88
- - The `min()` function enforces the vertical asymptote (maximum backoff)
89
-
90
- **In Mathematical Terms:**
91
- - The backoff function **converges** to the maximum backoff time
92
- - The maximum backoff time is the **asymptote** (vertical)
93
- - The relationship between attempts and backoff time follows a **hyperbolic-like curve**
94
-
95
- This ensures reasonable behavior: rapid initial retries for transient errors, while still respecting server limits and preventing cascading failures.
data/mkdocs.yml DELETED
@@ -1,183 +0,0 @@
1
- # MkDocs Configuration for TypedBus Documentation
2
- site_name: TypedBus
3
- site_description: Async pub/sub message bus with typed channels, ACK-based delivery, and dead letter queues for Ruby
4
- site_author: Dewayne VanHoozer
5
- site_url: https://madbomber.github.io/typed_bus
6
- copyright: Copyright © 2025 Dewayne VanHoozer
7
-
8
- # Repository information
9
- repo_name: MadBomber/typed_bus
10
- repo_url: https://github.com/MadBomber/typed_bus
11
- edit_uri: edit/main/docs/
12
-
13
- # Configuration
14
- theme:
15
- name: material
16
-
17
- # Color scheme
18
- palette:
19
- - scheme: default
20
- primary: teal
21
- accent: amber
22
- toggle:
23
- icon: material/brightness-7
24
- name: Switch to dark mode
25
-
26
- - scheme: slate
27
- primary: teal
28
- accent: amber
29
- toggle:
30
- icon: material/brightness-4
31
- name: Switch to light mode
32
-
33
- # Typography
34
- font:
35
- text: Roboto
36
- code: Roboto Mono
37
-
38
- # Logo and icon
39
- icon:
40
- repo: fontawesome/brands/github
41
- logo: material/bus-multiple
42
-
43
- # Theme features
44
- features:
45
- - navigation.instant
46
- - navigation.tracking
47
- - navigation.tabs
48
- - navigation.tabs.sticky
49
- - navigation.path
50
- - navigation.indexes
51
- - navigation.top
52
- - navigation.footer
53
- - toc.follow
54
- - search.suggest
55
- - search.highlight
56
- - search.share
57
- - header.autohide
58
- - content.code.copy
59
- - content.code.annotate
60
- - content.tabs.link
61
- - content.tooltips
62
- - content.action.edit
63
- - content.action.view
64
-
65
- # Plugins
66
- plugins:
67
- - search:
68
- separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
69
- - tags
70
-
71
- # Extensions
72
- markdown_extensions:
73
- - abbr
74
- - admonition
75
- - attr_list
76
- - def_list
77
- - footnotes
78
- - md_in_html
79
- - tables
80
- - toc:
81
- permalink: true
82
- title: On this page
83
-
84
- - pymdownx.arithmatex:
85
- generic: true
86
- - pymdownx.betterem:
87
- smart_enable: all
88
- - pymdownx.caret
89
- - pymdownx.critic
90
- - pymdownx.details
91
- - pymdownx.emoji:
92
- emoji_generator: !!python/name:material.extensions.emoji.to_svg
93
- emoji_index: !!python/name:material.extensions.emoji.twemoji
94
- - pymdownx.highlight:
95
- anchor_linenums: true
96
- line_spans: __span
97
- pygments_lang_class: true
98
- - pymdownx.inlinehilite
99
- - pymdownx.keys
100
- - pymdownx.magiclink:
101
- repo_url_shorthand: true
102
- user: MadBomber
103
- repo: typed_bus
104
- normalize_issue_symbols: true
105
- - pymdownx.mark
106
- - pymdownx.smartsymbols
107
- - pymdownx.snippets:
108
- check_paths: true
109
- - pymdownx.superfences:
110
- custom_fences:
111
- - name: mermaid
112
- class: mermaid
113
- format: !!python/name:pymdownx.superfences.fence_code_format
114
- - pymdownx.tabbed:
115
- alternate_style: true
116
- - pymdownx.tasklist:
117
- custom_checkbox: true
118
- - pymdownx.tilde
119
-
120
- # Extra CSS
121
- extra_css:
122
- - assets/css/custom.css
123
-
124
- # Social media and extra configuration
125
- extra:
126
- social:
127
- - icon: fontawesome/brands/github
128
- link: https://github.com/MadBomber/typed_bus
129
- name: TypedBus on GitHub
130
- - icon: fontawesome/solid/gem
131
- link: https://rubygems.org/gems/typed_bus
132
- name: TypedBus on RubyGems
133
-
134
- analytics:
135
- feedback:
136
- title: Was this page helpful?
137
- ratings:
138
- - icon: material/emoticon-happy-outline
139
- name: This page was helpful
140
- data: 1
141
- note: Thanks for your feedback!
142
- - icon: material/emoticon-sad-outline
143
- name: This page could be improved
144
- data: 0
145
- note: Thanks for your feedback! Help us improve by creating an issue.
146
-
147
- # Navigation
148
- nav:
149
- - Home:
150
- - Overview: index.md
151
- - Concepts: concepts.md
152
- - Getting Started:
153
- - getting-started/index.md
154
- - Installation: getting-started/installation.md
155
- - Quick Start: getting-started/quick-start.md
156
- - Configuration: getting-started/configuration.md
157
- - Architecture:
158
- - architecture/index.md
159
- - Publish Flow: architecture/publish-flow.md
160
- - Concurrency Model: architecture/concurrency-model.md
161
- - Configuration Cascade: architecture/configuration-cascade.md
162
- - Guides:
163
- - guides/index.md
164
- - Typed Channels: guides/typed-channels.md
165
- - Delivery and Acknowledgment: guides/delivery-and-ack.md
166
- - Dead Letter Queues: guides/dead-letter-queues.md
167
- - Backpressure: guides/backpressure.md
168
- - Adaptive Throttling: guides/adaptive-throttling.md
169
- - Stats and Monitoring: guides/stats-and-monitoring.md
170
- - Logging: guides/logging.md
171
- - Error Handling: guides/error-handling.md
172
- - Graceful Shutdown: guides/graceful-shutdown.md
173
- - API Reference:
174
- - api/index.md
175
- - Configuration: api/configuration.md
176
- - MessageBus: api/message-bus.md
177
- - Channel: api/channel.md
178
- - Delivery: api/delivery.md
179
- - DeliveryTracker: api/delivery-tracker.md
180
- - DeadLetterQueue: api/dead-letter-queue.md
181
- - Stats: api/stats.md
182
- - Examples:
183
- - examples/index.md