local_bus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc7597ce848ed87503b21e8b893d9637f7f601945d4e6d0904938f2319b691f0
+  data.tar.gz: 6b65f578aac4e885afc4d76265fdf3812b2b3d8d32b2f0ba7d6abdc6f824fcf7
+SHA512:
+  metadata.gz: 18c4ca9e676956c6b2571093bec9f57a76714ceb833f7aae021ac6563965d438499c05fcd5214e63b5b9cb8a192ed739d6926b54bc9d97e87a9f33b193289052
+  data.tar.gz: b1b99ef58b04fcfcf45808596be55bc9919f455aeb65a3ef53a56157305bff5aaf1310d418a02c14413f6db735a06dea58440d5f9d3a849073fd6a53f837247d

data/README.md

@@ -0,0 +1,245 @@
+<p align="center">
+  <a href="http://blog.codinghorror.com/the-best-code-is-no-code-at-all/">
+    <img alt="Lines of Code" src="https://img.shields.io/badge/loc-328-47d299.svg" />
+  </a>
+  <a href="https://rubygems.org/gems/local_bus">
+    <img alt="GEM Version" src="https://img.shields.io/gem/v/local_bus">
+  </a>
+  <a href="https://rubygems.org/gems/local_bus">
+    <img alt="GEM Downloads" src="https://img.shields.io/gem/dt/local_bus">
+  </a>
+  <a href="https://github.com/hopsoft/local_bus/actions">
+    <img alt="Tests" src="https://github.com/hopsoft/local_bus/actions/workflows/tests.yml/badge.svg" />
+  </a>
+  <a href="https://github.com/testdouble/standard">
+    <img alt="Ruby Style" src="https://img.shields.io/badge/style-standard-168AFE?logo=ruby&logoColor=FE1616" />
+  </a>
+  <a href="https://github.com/sponsors/hopsoft">
+    <img alt="Sponsors" src="https://img.shields.io/github/sponsors/hopsoft?color=eb4aaa&logo=GitHub%20Sponsors" />
+  </a>
+  <a href="https://twitter.com/hopsoft">
+    <img alt="Twitter Follow" src="https://img.shields.io/twitter/url?label=%40hopsoft&style=social&url=https%3A%2F%2Ftwitter.com%2Fhopsoft">
+  </a>
+</p>
+
+# LocalBus
+
+LocalBus is a lightweight pub/sub system for Ruby that helps organize and simplify intra-process communication.
+
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [Why LocalBus?](#why-localbus)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Interfaces](#interfaces)
+  - [Bus (immediate processing)](#bus-immediate-processing)
+  - [Station (background processing)](#station-background-processing)
+- [Advanced Usage & Considerations](#advanced-usage--considerations)
+  - [Concurrency Controls](#concurrency-controls)
+    - [Bus Interface (Async)](#bus-interface-async)
+    - [Station Interface (Thread Pool)](#station-interface-thread-pool)
+  - [Error Handling & Recovery](#error-handling--recovery)
+  - [Memory Considerations](#memory-considerations)
+  - [Blocking Operations](#blocking-operations)
+  - [Shutdown & Cleanup](#shutdown--cleanup)
+  - [Limitations](#limitations)
+- [Sponsors](#sponsors)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
+## Why LocalBus?
+
+A message bus (or enterprise service bus) is an architectural pattern that enables different parts of an application to communicate without direct knowledge of each other. Think of it as a smart postal service for your application - components can send messages to topics, and other components can listen for those messages, all without knowing about each other directly.
+
+Even within a single process, this pattern offers powerful benefits:
+
+- **Decouple Components**: Break complex systems into maintainable parts that can evolve independently
+- **Single Responsibility**: Each component can focus on its core task without handling cross-cutting concerns
+- **Flexible Architecture**: Easily add new features by subscribing to existing events without modifying original code
+- **Control Flow**: Choose immediate or background processing based on your needs
+- **Testing**: Simplified testing as components can be tested in isolation
+- **Stay Reliable**: Built-in error handling and thread safety
+- **Non-Blocking**: Efficient message processing with async I/O
+
+## Installation
+
+```sh
+bundle add local_bus
+```
+
+## Quick Start
+
+### Interfaces
+
+- **Bus**: Single-threaded, immediate message delivery using Socketry Async with non-blocking I/O operations
+- **Station**: Multi-threaded message queuing powered by Concurrent Ruby's thread pool, processing messages through the Bus without blocking the main thread
+
+Both interfaces ensure optimal performance:
+
+- Bus leverages async I/O to prevent blocking on network or disk operations
+- Station offloads work to a managed thread pool, keeping the main thread responsive
+- Both interfaces support an explicit `wait` for subscribers
+
+### Bus (immediate processing)
+
+Best for real-time operations like logging, metrics, and state updates.
+
+```ruby
+bus = LocalBus.instance.bus
+
+bus.subscribe "user.created" do |message|
+  AuditLog.record(message.payload)
+  true
+end
+
+# publish returns a promise-like object that resolves to subscribers
+result = bus.publish("user.created", user_id: 123)
+
+result.wait  # blocks until all subscribers complete
+result.value # blocks and waits until all subscribers complete and returns the subscribers
+```
+
+### Station (background processing)
+
+Best for async operations like emails, notifications, and resource-intensive tasks.
+
+```ruby
+station = LocalBus::Station.new # ... or LocalBus.instance.station
+
+station.subscribe "email.welcome" do |message|
+  WelcomeMailer.deliver(message.payload[:user_id])
+  true
+end
+
+# Returns a Promise or Future that resolves to subscribers
+result = station.publish("email.welcome", user_id: 123)
+
+result.wait  # blocks until all subscribers complete
+result.value # blocks and waits until all subscribers complete and returns the subscribers
+```
+
+## Advanced Usage & Considerations
+
+### Concurrency Controls
+
+#### Bus Interface (Async)
+
+The Bus interface uses Async's Semaphore to limit resource consumption:
+
+```ruby
+# Configure concurrency limits for the Bus
+bus = LocalBus::Bus.new(concurrency_limit: 10)
+
+# The semaphore ensures only N concurrent operations run at once
+bus.subscribe "resource.intensive" do |message|
+  # Only 10 of these will run concurrently
+  perform_intensive_operation(message)
+end
+```
+
+When the concurrency limit is reached, new publish operations will wait until a slot becomes available. This prevents memory bloat but means you should be mindful of timeouts in your subscribers.
+
+#### Station Interface (Thread Pool)
+
+The Station interface uses Concurrent Ruby's fixed thread pool with a fallback policy:
+
+```ruby
+# Configure the thread pool size for the Station
+station = LocalBus::Station.new(
+  max_queue: 5_000, # Maximum number of queued items
+  threads: 10, # Maximum pool size
+  fallback_policy: :caller_runs # Runs on calling thread
+)
+```
+
+The fallback policy determines behavior when the thread pool is saturated:
+
+- `:caller_runs` - Executes the task in the publishing thread (can block)
+- `:abort` - Raises an error
+- `:discard` - Silently drops the task
+
+### Error Handling & Recovery
+
+Both interfaces implement error boundaries to prevent individual subscriber failures from affecting others:
+
+```ruby
+bus.subscribe "user.created" do |message|
+  raise "Something went wrong!"
+  true # Never reached
+end
+
+bus.subscribe "user.created" do |message|
+  # This still executes despite the error above
+  notify_admin(message)
+  true
+end
+
+# The publish operation completes with partial success
+result = bus.publish("user.created", user_id: 123)
+result.wait
+errored_subscribers = result.value.select(&:error)
+```
+
+### Memory Considerations
+
+Messages are held in memory until all subscribers complete processing. For the Station interface, this includes time spent in the thread pool queue. Consider this when publishing large payloads or during high load:
+
+```ruby
+# Memory-efficient publishing of large datasets
+large_dataset.each_slice(100) do |batch|
+  station.publish("data.process", items: batch).wait
+end
+```
+
+### Blocking Operations
+
+The Bus interface uses non-blocking I/O but can still be blocked by CPU-intensive operations:
+
+```ruby
+# Bad - blocks the event loop
+bus.subscribe "cpu.intensive" do |message|
+  perform_heavy_calculation(message)
+end
+
+# Better - offload to Station for CPU-intensive work
+station.subscribe "cpu.intensive" do |message|
+  perform_heavy_calculation(message)
+end
+```
+
+### Shutdown & Cleanup
+
+LocalBus does its best to handle graceful shutdown when the process exits, and works to ensure published messages are processed.
+However, it's possible that some messages may be lost when the process exits.
+
+Factor for potential message loss when designing your system.
+For example, idempotency _(i.e. messages that can be re-published without unintended side effects)_.
+
+### Limitations
+
+- The Bus interface is single-threaded - long-running subscribers can impact latency
+- The Station interface may drop messages if configured with `:discard` fallback policy
+- No persistence - pending messages are lost on process restart
+- No distributed support - communication limited to single process
+- Large payloads can impact memory usage, especially under high load
+- No built-in retry mechanism for failed subscribers
+
+Consider these limitations when designing your system architecture.
+
+## See Also
+
+- [Message Bus](https://github.com/discourse/message_bus) - A reliable and robust messaging bus for Ruby and Rack
+- [Wisper](https://github.com/krisleech/wisper) - A micro library providing Ruby objects with Publish-Subscribe capabilities
+
+## Sponsors
+
+<p align="center">
+  <em>Proudly sponsored by</em>
+</p>
+<p align="center">
+  <a href="https://www.clickfunnels.com?utm_source=hopsoft&utm_medium=open-source&utm_campaign=local_bus">
+    <img src="https://images.clickfunnel.com/uploads/digital_asset/file/176632/clickfunnels-dark-logo.svg" width="575" />
+  </a>
+</p>

data/lib/local_bus/bus.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+class LocalBus
+  # Local in-process single threaded "message bus" with non-blocking I/O
+  class Bus
+    include MonitorMixin
+
+    # Constructor
+    # @note Creates a new Bus instance with specified concurrency
+    # @rbs concurrency: Integer -- maximum number of concurrent tasks (default: Concurrent.processor_count)
+    def initialize(concurrency: Concurrent.processor_count)
+      super()
+      @concurrency = concurrency.to_i
+      @subscriptions = Concurrent::Hash.new do |hash, key|
+        hash[key] = Concurrent::Set.new
+      end
+    end
+
+    # Maximum number of concurrent tasks that can run in "parallel"
+    # @rbs return: Integer -- current concurrency value
+    def concurrency
+      synchronize { @concurrency }
+    end
+
+    # Sets the concurrency
+    # @rbs concurrency: Integer -- max number of concurrent tasks that can run in "parallel"
+    # @rbs return: Integer -- new concurrency value
+    def concurrency=(value)
+      synchronize { @concurrency = value.to_i }
+    end
+
+    # Registered topics that have subscribers
+    # @rbs return: Array[String] -- list of topic names
+    def topics
+      @subscriptions.keys
+    end
+
+    # Registered subscriptions
+    # @rbs return: Hash[String, Array[callable]] -- mapping of topics to callables
+    def subscriptions
+      @subscriptions.each_with_object({}) do |(topic, callables), memo|
+        memo[topic] = callables.to_a
+      end
+    end
+
+    # Subscribes a callable to a topic
+    # @rbs topic: String -- topic name
+    # @rbs callable: (Message) -> untyped -- callable that will process messages published to the topic
+    # @rbs &block: (Message) -> untyped -- alternative way to provide a callable
+    # @rbs return: self
+    # @raise [ArgumentError] if neither callable nor block is provided
+    def subscribe(topic, callable: nil, &block)
+      callable ||= block
+      raise ArgumentError, "Subscriber must respond to #call" unless callable.respond_to?(:call, false)
+      @subscriptions[topic.to_s].add callable
+      self
+    end
+
+    # Unsubscribes a callable from a topic
+    # @rbs topic: String -- topic name
+    # @rbs callable: (Message) -> untyped -- subscriber that should no longer receive messages
+    # @rbs return: self
+    def unsubscribe(topic, callable:)
+      topic = topic.to_s
+      @subscriptions[topic].delete callable
+      @subscriptions.delete(topic) if @subscriptions[topic].empty?
+      self
+    end
+
+    # Unsubscribes all subscribers from a topic and removes the topic
+    # @rbs topic: String -- topic name
+    # @rbs return: self
+    def unsubscribe_all(topic)
+      @subscriptions[topic].clear
+      @subscriptions.delete topic
+      self
+    end
+
+    # Executes a block and unsubscribes all subscribers from the topic afterwards
+    # @rbs topic: String -- topic name
+    # @rbs block: (String) -> void -- block to execute (yields the topic)
+    def with_topic(topic, &block)
+      block.call topic.to_s
+    ensure
+      unsubscribe_all topic
+    end
+
+    # Publishes a message to a topic
+    #
+    # @note If subscribers are rapidly created/destroyed mid-publish, there's a theoretical
+    #       possibility of object_id reuse. However, this is extremely unlikely in practice.
+    #
+    #       * If subscribers are added mid-publish, they will not receive the message
+    #       * If subscribers are removed mid-publish, they will still receive the message
+    #
+    # @note If the timeout is exceeded, the task will be cancelled before all subscribers have completed.
+    #
+    # Check the Subscriber for any errors.
+    #
+    # @rbs topic: String -- topic name
+    # @rbs timeout: Float -- seconds to wait before cancelling (default: 300)
+    # @rbs payload: Hash -- message payload
+    # @rbs return: Array[Subscriber] -- list of performed subscribers (empty if no subscribers)
+    def publish(topic, timeout: 300, **payload)
+      barrier = Async::Barrier.new
+      message = Message.new(topic, timeout: timeout, **payload)
+      subscribers = subscriptions.fetch(message.topic, []).map { Subscriber.new _1, message }
+
+      if subscribers.any?
+        Sync do |task|
+          task.with_timeout timeout.to_f do
+            semaphore = Async::Semaphore.new(concurrency, parent: barrier)
+
+            subscribers.each do |subscriber|
+              semaphore.async do
+                subscriber.perform
+              end
+            end
+          rescue Async::TimeoutError => cause
+            barrier.stop
+
+            subscribers.select(&:pending?).each do |subscriber|
+              subscriber.timeout cause
+            end
+          end
+        end
+      end
+
+      Pledge.new(barrier, *subscribers)
+    end
+  end
+end

data/lib/local_bus/message.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+class LocalBus
+  # Represents a message in the LocalBus system
+  class Message
+    # Constructor
+    # @note Creates a new Message instance with the given topic and payload
+    # @rbs topic: String -- the topic of the message
+    # @rbs timeout: Float? -- optional timeout for message processing (in seconds)
+    # @rbs payload: Hash -- the message payload
+    def initialize(topic, timeout: nil, **payload)
+      @id = SecureRandom.uuid_v7
+      @topic = topic.to_s.freeze
+      @payload = payload.transform_keys(&:to_sym).freeze
+      @created_at = Time.now
+      @thread_id = Thread.current.object_id
+      @timeout = timeout.to_f
+      @metadata ||= {
+        id: id,
+        topic: topic,
+        payload: payload,
+        created_at: created_at,
+        thread_id: thread_id,
+        timeout: timeout
+      }.freeze
+      freeze
+    end
+
+    # Unique identifier for the message
+    # @rbs return: String
+    attr_reader :id
+
+    # Message topic
+    # @rbs return: String
+    attr_reader :topic
+
+    # Message payload
+    # @rbs return: Hash
+    attr_reader :payload
+
+    # Time when the message was created or published
+    # @rbs return: Time
+    attr_reader :created_at
+
+    # ID of the thread that created the message
+    # @rbs return: Integer
+    attr_reader :thread_id
+
+    # Timeout for message processing (in seconds)
+    # @rbs return: Float
+    attr_reader :timeout
+
+    # Metadata for the message
+    # @rbs return: Hash[Symbol, untyped]
+    attr_reader :metadata
+
+    # Converts the message to a hash
+    # @rbs return: Hash[Symbol, untyped]
+    alias_method :to_h, :metadata
+
+    # Allows pattern matching on message attributes
+    # @rbs keys: Array[Symbol] -- keys to extract from the message
+    # @rbs return: Hash[Symbol, untyped]
+    def deconstruct_keys(keys)
+      keys.any? ? to_h.slice(*keys) : to_h
+    end
+  end
+end

data/lib/local_bus/pledge.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+class LocalBus
+  # A promise-like object that wraps an Async::Barrier and a list of Subscribers.
+  # Delegates #wait to the barrier and all other methods to the subscriber list.
+  class Pledge
+    # Constructor
+    # @rbs barrier: Async::Barrier -- barrier used to wait for all tasks
+    # @rbs subscribers: Array[Subscriber]
+    def initialize(barrier, *subscribers)
+      @barrier = barrier
+      @subscribers = subscribers
+    end
+
+    # Blocks and waits for the barrier... all subscribers to complete
+    # @rbs return: void
+    def wait
+      @barrier.wait
+      self
+    end
+
+    # Blocks and waits then returns all subscribers
+    # @rbs return: Array[Subscriber]
+    def value
+      wait
+      @subscribers
+    end
+
+    ## @!group Delegatation to subscribers
+
+    # def method_missing(...)
+    # return @subscribers.send(...) if @subscribers.respond_to?(...)
+    # super
+    # end
+
+    # def respond_to_missing?(...)
+    # return true if @subscribers.respond_to?(...)
+    # super
+    # end
+  end
+end

data/lib/local_bus/station.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+# rubocop:disable Lint/MissingCopEnableDirective
+# rubocop:disable Style/ArgumentsForwarding
+
+class LocalBus
+  # An in-process message queuing system that buffers and publishes messages to Bus.
+  # This class acts as an intermediary, queuing messages internally before publishing them to the Bus.
+  #
+  # @note Station shares the same interface as Bus and is thus a message bus.
+  #       The key difference is that Stations are multi-threaded and will not block the main thread.
+  #
+  # Three fallback policies are supported:
+  # 1. `abort` - Raises an exception and discards the task when the queue is full (default)
+  # 2. `discard` - Discards the task when the queue is full
+  # 3. `caller_runs` - Executes the task on the calling thread when the queue is full,
+  #                 This effectively jumps the queue (and blocks the main thread) but ensures the task is performed
+  #
+  # IMPORTANT: Be sure to release resources like database connections in subscribers when publishing via Station.
+  #
+  class Station
+    include MonitorMixin
+
+    class TimeoutError < StandardError; end
+
+    # Default options for Concurrent::FixedThreadPool (can be overridden via the constructor)
+    # @see https://ruby-concurrency.github.io/concurrent-ruby/1.3.4/Concurrent/ThreadPoolExecutor.html
+    THREAD_POOL_OPTIONS = {
+      max_queue: 5_000, # max number of pending tasks allowed in the queue
+      fallback_policy: :caller_runs # Options: :abort, :discard, :caller_runs
+    }.freeze
+
+    # Constructor
+    # @rbs bus: Bus -- local message bus (default: Bus.new)
+    # @rbs threads: Integer -- number of threads (default: Concurrent.processor_count)
+    # @rbs default_timeout: Float -- seconds to wait for a future to complete
+    # @rbs shutdown_timeout: Float -- seconds to wait for all futures to complete on process exit
+    # @rbs options: Hash[Symbol, untyped] -- Concurrent::FixedThreadPool options
+    # @rbs return: void
+    def initialize(
+      bus: Bus.new,
+      threads: Concurrent.processor_count,
+      default_timeout: 0,
+      shutdown_timeout: 8,
+      **options
+    )
+      super()
+      @bus = bus
+      @threads = [2, threads].max.to_i
+      @default_timeout = default_timeout.to_f
+      @shutdown_timeout = shutdown_timeout.to_f
+      @shutdown = Concurrent::AtomicBoolean.new(false)
+      start(**options)
+    end
+
+    # Bus instance
+    # @rbs return: Bus
+    attr_reader :bus
+
+    # Number of threads used to process messages
+    # @rbs return: Integer
+    attr_reader :threads
+
+    # Default timeout for message processing (in seconds)
+    # @rbs return: Float
+    attr_reader :default_timeout
+
+    # Timeout for graceful shutdown (in seconds)
+    # @rbs return: Float
+    attr_reader :shutdown_timeout
+
+    # Starts the broker
+    # @rbs options: Hash[Symbol, untyped] -- Concurrent::FixedThreadPool options
+    # @rbs return: void
+    def start(**options)
+      synchronize do
+        return if running?
+
+        start_shutdown_handler
+        @pool = Concurrent::FixedThreadPool.new(threads, THREAD_POOL_OPTIONS.merge(options))
+        enable_safe_shutdown on: ["HUP", "INT", "QUIT", "TERM"]
+      end
+    end
+
+    # Stops the broker
+    # @rbs timeout: Float -- seconds to wait for all futures to complete
+    # @rbs return: void
+    def stop(timeout: shutdown_timeout)
+      return unless @shutdown.make_true # Ensure we only stop once
+
+      synchronize do
+        if running?
+          # First try graceful shutdown
+          pool.shutdown
+
+          # If graceful shutdown fails, force termination
+          pool.kill unless pool.wait_for_termination(timeout)
+
+          @pool = nil
+        end
+      end
+
+      # Clean up shutdown handler
+      if @shutdown_thread&.alive?
+        @shutdown_queue&.close
+        @shutdown_thread&.join timeout
+      end
+
+      @shutdown_thread = nil
+      @shutdown_queue = nil
+      @shutdown_completed&.set
+    end
+
+    # Indicates if the broker is running
+    # @rbs return: bool
+    def running?
+      synchronize { pool&.running? }
+    end
+
+    # Subscribe to a topic
+    # @rbs topic: String -- topic name
+    # @rbs callable: (Message) -> untyped -- callable that will process messages published to the topic
+    # @rbs &block: (Message) -> untyped -- alternative way to provide a callable
+    # @rbs return: self
+    def subscribe(topic, callable: nil, &block)
+      callable ||= block
+      bus.subscribe(topic, &callable)
+      self
+    end
+
+    # Unsubscribe from a topic
+    # @rbs topic: String -- topic name
+    # @rbs return: self
+    def unsubscribe(topic)
+      bus.unsubscribe(topic)
+      self
+    end
+
+    # Unsubscribes all subscribers from a topic and removes the topic
+    # @rbs topic: String -- topic name
+    # @rbs return: self
+    def unsubscribe_all(topic)
+      bus.unsubscribe_all topic
+      self
+    end
+
+    # Publishes a message to Bus on a separate thread keeping the main thread free for additional work.
+    #
+    # @note This allows you to publish messages when performing operations like handling web requests
+    #       without blocking the main thread and slowing down the response.
+    #
+    # @see https://ruby-concurrency.github.io/concurrent-ruby/1.3.4/Concurrent/Promises/Future.html
+    #
+    # @rbs topic: String | Symbol -- topic name
+    # @rbs timeout: Float -- seconds to wait before cancelling
+    # @rbs payload: Hash[Symbol, untyped] -- message payload
+    # @rbs return: Concurrent::Promises::Future
+    def publish(topic, timeout: default_timeout, **payload)
+      timeout = timeout.to_f
+
+      future = Concurrent::Promises.future_on(pool) do
+        case timeout
+        in 0 then bus.publish(topic, **payload).value
+        else bus.publish(topic, timeout: timeout, **payload).value
+        end
+      end
+
+      # ensure calls to future.then use the thread pool
+      executor = pool
+      future.singleton_class.define_method :then do |&block|
+        future.then_on(executor, &block)
+      end
+
+      future
+    end
+
+    private
+
+    # Thread pool used for asynchronous operations
+    # @rbs return: Concurrent::FixedThreadPool
+    attr_reader :pool
+
+    # Starts the shutdown handler thread
+    # @rbs return: void
+    def start_shutdown_handler
+      return if @shutdown.true?
+
+      @shutdown_queue = Queue.new
+      @shutdown_completed = Concurrent::Event.new
+      @shutdown_thread = Thread.new do
+        catch :shutdown do
+          loop do
+            signal = @shutdown_queue.pop # blocks until something is available
+            throw :shutdown if @shutdown_queue.closed?
+
+            stop # initiate shutdown sequence
+
+            # Re-raise the signal to let the process terminate
+            if signal
+              # Remove our trap handler before re-raising
+              trap signal, "DEFAULT"
+              Process.kill signal, Process.pid
+            end
+          rescue ThreadError, ClosedQueueError
+            break # queue was closed, exit gracefully
+          end
+        end
+        @shutdown_completed.set
+      end
+    end
+
+    # Enables safe shutdown on process exit by trapping specified signals
+    # @rbs on: Array[String] -- signals to trap
+    # @rbs return: void
+    def enable_safe_shutdown(on:)
+      on.each do |signal|
+        trap signal do
+          # Only queue the signal if we haven't started shutdown
+          @shutdown_queue.push signal unless @shutdown.true?
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/local_bus/subscriber.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+class LocalBus
+  # Wraps a Callable (Proc) and Message intended for asynchronous execution.
+  class Subscriber
+    # Custom error class for Subscriber errors
+    class Error < StandardError
+      # Constructor
+      # @rbs message: String -- error message
+      # @rbs cause: StandardError? -- underlying cause of the error
+      def initialize(message, cause:)
+        super(message)
+        @cause = cause
+      end
+
+      # Underlying cause of the error
+      # @rbs return: StandardError?
+      attr_reader :cause
+    end
+
+    # Constructor
+    # @rbs callable: #call -- the subscriber's callable object
+    # @rbs message: Message -- the message to be processed
+    def initialize(callable, message)
+      @callable = callable
+      @message = message
+      @id = callable.object_id
+      @source_location = callable.source_location
+      @metadata = {}
+    end
+
+    # Unique identifier for the subscriber
+    # @rbs return: String
+    attr_reader :id
+
+    # Source location of the callable
+    # @rbs return: Array[String, Integer]?
+    attr_reader :source_location
+
+    # Callable object -- Proc, lambda, etc. (must respond to #call)
+    # @rbs return: #call
+    attr_reader :callable
+
+    # Error if the subscriber fails (available after performing)
+    # @rbs return: Error?
+    attr_reader :error
+
+    # Message for the subscriber to process
+    # @rbs return: Message
+    attr_reader :message
+
+    # Metadata for the subscriber (available after performing)
+    # @rbs return: Hash[Symbol, untyped]
+    attr_reader :metadata
+
+    # Value returned by the callable (available after performing)
+    # @rbs return: untyped
+    attr_reader :value
+
+    # Indicates if the subscriber has been performed
+    # @rbs return: bool
+    def performed?
+      metadata.any?
+    end
+
+    # Checks if the subscriber is pending
+    # @rbs return: bool
+    def pending?
+      metadata.empty?
+    end
+
+    # Performs the subscriber's callable
+    # @rbs return: void
+    def perform
+      return if performed?
+
+      with_metadata do
+        @value = callable.call(message)
+      rescue => cause
+        @error = Error.new("Invocation failed! #{cause.message}", cause: cause)
+      end
+    end
+
+    # Handles timeout for the subscriber
+    # @rbs cause: StandardError -- the cause of the timeout
+    # @rbs return: void
+    def timeout(cause)
+      return if performed?
+
+      with_metadata do
+        @error = Error.new("Timeout expired before invocation! Waited #{message.timeout} seconds!", cause: cause)
+      end
+    end
+
+    # Returns the subscriber's data as a hash
+    # @rbs return: Hash[Symbol, untyped]
+    def to_h
+      {
+        error: error,
+        metadata: metadata,
+        value: value
+      }
+    end
+
+    # Allows pattern matching on subscriber attributes
+    # @rbs keys: Array[Symbol] -- keys to extract from the subscriber
+    # @rbs return: Hash[Symbol, untyped]
+    def deconstruct_keys(keys)
+      keys.any? ? to_h.slice(*keys) : to_h
+    end
+
+    private
+
+    # Captures metadata for the subscriber's performance
+    # @rbs return: void
+    def with_metadata
+      started_at = Time.now
+      yield
+      @metadata = {
+        id: SecureRandom.uuid_v7,
+        thread_id: Thread.current.object_id,
+        source_location: source_location,
+        started_at: started_at,
+        finished_at: Time.now,
+        duration: Time.now - started_at,
+        latency: Time.now - message.created_at,
+        message: message
+      }.freeze
+    end
+  end
+end

data/lib/local_bus/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+class LocalBus
+  VERSION = "0.1.0"
+end

data/lib/local_bus.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+require "async"
+require "async/barrier"
+require "async/semaphore"
+require "concurrent-ruby"
+require "monitor"
+require "securerandom"
+require "singleton"
+
+class LocalBus
+  include Singleton
+
+  attr_reader :bus
+  attr_reader :station
+
+  private
+
+  def initialize
+    @bus = Bus.new
+    @station = Station.new(bus: bus)
+  end
+end

metadata

@@ -0,0 +1,268 @@
+--- !ruby/object:Gem::Specification
+name: local_bus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nate Hopkins (hopsoft)
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-11-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: amazing_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-doc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rbs-inline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tocer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  LocalBus is a lightweight yet powerful pub/sub system for Ruby applications that enables decoupled communication within a single process.
+  It offers both non-blocking I/O and thread pool processing modes, robust error handling, and fine-grained concurrency controls.
+  Perfect for organizing event-driven architectures, handling background jobs, and managing complex workflows without external dependencies."
+email:
+- natehop@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/local_bus.rb
+- lib/local_bus/bus.rb
+- lib/local_bus/message.rb
+- lib/local_bus/pledge.rb
+- lib/local_bus/station.rb
+- lib/local_bus/subscriber.rb
+- lib/local_bus/version.rb
+homepage: https://github.com/hopsoft/local_bus
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hopsoft/local_bus
+  source_code_uri: https://github.com/hopsoft/local_bus
+  changelog_uri: https://github.com/hopsoft/local_bus/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: A lightweight pub/sub system for decoupled intra-process communication in
+  Ruby applications
+test_files: []