nti_event_bus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20a81903201667f24f670449fdcd72d0c5dc7e2ff317fc992a32d129c585eb60
+  data.tar.gz: 91b184e622a256994b980f6ed0fae575768144ee195b8dcf97ab1477dc86fa60
+SHA512:
+  metadata.gz: 1f711d6690c639c15e71cab839ec930ef5d0e86e01e290f537757386ead3dd330ee88e91826f8ea9b54788c311b146c0de296f3f55271823369a510dfd8440a3
+  data.tar.gz: 2e50543c96df318dc59523ee3f03a97bfcb6eea141d26ec919988428ce6c4f4fa91b746032bb55d7393ee728efd50b961f380f76d1ec18c750946083ca114442

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [0.1.0] - 2026-07-07
+
+- Initial release. Extracted from the Tindahang Tapat OnPrem application.
+- `NtiEventBus.publish` fans a `domain.action` event out to subscribed handler classes.
+- `NtiEventBus::DSL` (`draw` / `on_event` / `perform`) declares subscriptions loaded from event files.
+- `NtiEventBus::Registry` — deep-frozen after `finalize!` for lock-free reads.
+- `NtiEventBus::HandlerBase` — base class for handlers (indifferent-access frozen payload, `require_keys`).
+- `NtiEventBus::HandleEventJob` — ActiveJob-backed asynchronous dispatch on a configurable queue.
+- `NtiEventBus::Dispatchers::ActiveJob` (default) and `NtiEventBus::Dispatchers::Inline`.
+- `NtiEventBus::Railtie` — sets event-file path defaults and rebuilds the registry on `to_prepare`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Nueca Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+# NTI Event Bus
+
+[![CI](https://github.com/nueca-tech/nti_event_bus/actions/workflows/ci.yml/badge.svg)](https://github.com/nueca-tech/nti_event_bus/actions/workflows/ci.yml)
+
+A small, production-grade **publish/subscribe event bus** for Ruby & Rails.
+
+Declare `domain.action` subscriptions in a compact DSL, `publish` events, and fan them out to handler classes **asynchronously** via ActiveJob. The subscription registry is built once at boot and **deep-frozen**, so publishing is a lock-free hash lookup with no per-call allocation and no long-lived, unbounded state — no thread pools, no notification subscribers, nothing to leak.
+
+```
+publisher → NtiEventBus.publish("order.created", payload)
+              → registry.handlers_for("order.created")   # frozen O(1) lookup
+                  → dispatcher.call(handler_name, payload)
+                      → NtiEventBus::HandleEventJob (ActiveJob, async)
+                          → Handler.new(payload).call
+```
+
+## Installation
+
+```ruby
+gem 'nti_event_bus'
+```
+
+## Rails usage
+
+On Rails the bundled `NtiEventBus::Railtie` wires everything up automatically:
+
+- Defaults `configuration.root_events_file` to `config/events.rb` and `configuration.events_dir` to
+  `config/events/`.
+- Rebuilds the registry on every `to_prepare` (once in production; per code-reload in development, so edits to event files are picked up and old handler references are released).
+
+Define the root events file and one or more drawn files:
+
+```ruby
+# config/events.rb
+draw :internal_events
+
+# config/events/internal_events.rb
+on_event 'order.created' do
+  perform Orders::Handlers::Created
+  perform Notifications::Handlers::OrderCreated
+end
+```
+
+Publish from anywhere:
+
+```ruby
+NtiEventBus.publish('order.created', { order_id: order.id })
+```
+
+Write handlers by subclassing `HandlerBase`:
+
+```ruby
+module Orders::Handlers
+  class Created < NtiEventBus::HandlerBase
+    def call
+      order_id = payload.fetch(:order_id)   # payload is an indifferent-access, frozen hash
+      # ...
+    end
+  end
+end
+```
+
+## Configuration
+
+```ruby
+NtiEventBus.configure do |config|
+  config.root_events_file = Rails.root.join('config/events.rb').to_s  # defaulted by the Railtie
+  config.events_dir       = Rails.root.join('config/events').to_s     # defaulted by the Railtie
+  config.queue_name       = :events                                   # ActiveJob queue (default)
+  config.dispatcher       = NtiEventBus::Dispatchers::ActiveJob.new    # default; async
+  config.logger           = Rails.logger                              # optional
+end
+```
+
+### Dispatchers
+
+- `NtiEventBus::Dispatchers::ActiveJob` (default) — enqueues `HandleEventJob` on `config.queue_name`.
+- `NtiEventBus::Dispatchers::Inline` — runs the handler synchronously in-process (tests / non-ActiveJob hosts).
+- Any object responding to `#call(handler_name, payload)` may be used.
+
+## Non-Rails usage
+
+```ruby
+NtiEventBus.configure do |config|
+  config.root_events_file = '/path/to/events.rb'
+  config.events_dir       = '/path/to/events'
+end
+NtiEventBus.setup!          # build the registry
+NtiEventBus.publish('order.created', { order_id: 1 })
+```
+
+## Thread-safety & reloads
+
+`setup!` builds a fresh `Registry`, deep-freezes it, and atomically swaps it in under a mutex. Readers always see a fully-frozen registry (the previous one or the new one), so `publish` never locks and never observes a half-built registry.
+
+## Event naming
+
+Event names must be non-empty strings in `domain.action` form (they must contain a `.`). This is enforced at subscription time by the DSL.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/nti_event_bus/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module NtiEventBus
+  # Runtime configuration. On Rails the Railtie fills in path defaults; hosts may override any of it.
+  class Configuration
+    # Absolute path to the root events file that is evaluated by `setup!` (e.g. config/events.rb).
+    attr_accessor :root_events_file
+    # Absolute path to the directory that `draw` resolves nested event files from (e.g. config/events).
+    attr_accessor :events_dir
+    # ActiveJob queue used by the default dispatcher.
+    attr_accessor :queue_name
+    # Optional logger; when set, receives debug lines from the bus.
+    attr_accessor :logger
+
+    attr_writer :dispatcher
+
+    def initialize
+      @queue_name = :events
+      @root_events_file = nil
+      @events_dir = nil
+      @logger = nil
+      @dispatcher = nil
+    end
+
+    # Object responding to `#call(handler_name, payload)`. Defaults to asynchronous ActiveJob dispatch.
+    def dispatcher
+      @dispatcher ||= Dispatchers::ActiveJob.new
+    end
+
+    def root_events_file!
+      root_events_file ||
+        raise(NotConfiguredError, 'NtiEventBus.configuration.root_events_file must be set')
+    end
+  end
+end

data/lib/nti_event_bus/dispatchers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module NtiEventBus
+  # Strategies for turning a resolved (handler_name, payload) pair into actual handler execution.
+  # A dispatcher is any object responding to `#call(handler_name, payload)`.
+  module Dispatchers
+    # Default. Enqueues handler execution asynchronously via ActiveJob (Solid Queue, Sidekiq, ...).
+    class ActiveJob
+      def call(handler_name, payload)
+        NtiEventBus::HandleEventJob.perform_later(handler_name, payload)
+      end
+    end
+
+    # Runs the handler synchronously, in-process. Useful for tests or hosts without a job backend.
+    class Inline
+      def call(handler_name, payload)
+        NtiEventBus::HandleEventJob.perform_now(handler_name, payload)
+      end
+    end
+  end
+end

data/lib/nti_event_bus/dsl.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module NtiEventBus
+  # Evaluation context for event-definition files.
+  #
+  # A root file is `instance_eval`ed against a DSL instance; it may `draw` additional files from the
+  # configured `events_dir`, and declares subscriptions with `on_event` / `perform`:
+  #
+  #   on_event 'order.created' do
+  #     perform Orders::Handlers::Created
+  #   end
+  class DSL
+    def initialize(registry, events_dir)
+      @registry = registry
+      @events_dir = events_dir
+      @current_event_name = nil
+    end
+
+    def on_event(event_name, &block)
+      raise ArgumentError, 'Nested `on_event` not allowed' if @current_event_name
+      raise ArgumentError, 'Block required for `on_event`' unless block
+
+      event_name = normalize_event!(event_name)
+
+      @current_event_name = event_name
+      instance_eval(&block)
+    ensure
+      @current_event_name = nil
+    end
+
+    def perform(handlers)
+      raise ArgumentError, 'perform must be inside `on_event`' unless @current_event_name
+
+      Array(handlers).each do |handler|
+        @registry.add(@current_event_name, handler)
+      end
+    end
+
+    def draw(name)
+      raise NotConfiguredError, 'NtiEventBus.configuration.events_dir must be set' unless @events_dir
+
+      path = File.join(@events_dir.to_s, "#{name}.rb")
+      raise LoadError, "Event file not found: #{path}" unless File.exist?(path)
+
+      instance_eval(File.read(path), path.to_s)
+    end
+
+    private
+
+    def normalize_event!(event_name)
+      raise ArgumentError, 'event_name must be a String' unless event_name.is_a?(String)
+
+      event_name = event_name.strip
+      raise ArgumentError, 'event_name cannot be empty' if event_name.empty?
+
+      # enforce naming convention: domain.action
+      raise ArgumentError, "event_name must follow 'domain.action' format" unless event_name.include?('.')
+
+      event_name.freeze
+    end
+  end
+end

data/lib/nti_event_bus/handle_event_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'active_job'
+require 'active_support/core_ext/string/inflections'
+
+module NtiEventBus
+  # ActiveJob that runs a single handler for a published event.
+  #
+  # The handler is passed by name (a String) rather than as a class so the argument serializes
+  # cleanly and is re-resolved to the current class version at run time (reload-safe). The queue is
+  # read from configuration at enqueue time so hosts can route event work to a dedicated queue.
+  class HandleEventJob < ::ActiveJob::Base
+    queue_as { NtiEventBus.configuration.queue_name }
+
+    def perform(handler_name, payload)
+      handler = handler_name.constantize
+
+      handler.new(payload).call
+    end
+  end
+end

data/lib/nti_event_bus/handler_base.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/indifferent_access'
+
+module NtiEventBus
+  # Base class for all event handlers.
+  #
+  # A handler lives inside the *subscribing* module and is responsible for:
+  #   1. Extracting what it needs from the raw event payload
+  #   2. Doing any lookups / transformations
+  #   3. Calling the module's Main interactor (or service) with normalized params
+  #
+  # Subclasses must implement #call.
+  #
+  # Example:
+  #   class CreateAuditLog::Handlers::OrderVoided < NtiEventBus::HandlerBase
+  #     def call
+  #       CreateAuditLog::Main.call(
+  #         cashier_id: payload.fetch(:cashier_id),
+  #         ...
+  #       )
+  #     end
+  #   end
+  class HandlerBase
+    attr_reader :payload
+
+    def initialize(payload)
+      @payload = payload.with_indifferent_access.freeze
+    end
+
+    def call
+      raise NotImplementedError, "#{self.class}#call must be implemented"
+    end
+
+    private
+
+    # Convenience — fetch multiple required keys at once.
+    # Raises KeyError with a clear message if any are missing.
+    #
+    #   cashier_id, order_id = require_keys(:cashier_id, :order_id)
+    #
+    def require_keys(*keys)
+      keys.map { |key| payload.fetch(key) }
+    end
+  end
+end

data/lib/nti_event_bus/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module NtiEventBus
+  # Rails integration: sets sensible event-file path defaults and (re)builds the registry whenever the
+  # framework prepares the app. `to_prepare` runs once during boot in production and on every code
+  # reload in development, so event-file edits are picked up and stale handler references are released.
+  class Railtie < ::Rails::Railtie
+    initializer 'nti_event_bus.set_defaults' do
+      NtiEventBus.configure do |config|
+        config.root_events_file ||= Rails.root.join('config/events.rb').to_s
+        config.events_dir ||= Rails.root.join('config/events').to_s
+      end
+    end
+
+    config.to_prepare do
+      NtiEventBus.setup!
+    end
+  end
+end

data/lib/nti_event_bus/registry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module NtiEventBus
+  # Maps event names to the ordered, de-duplicated list of handler classes subscribed to them.
+  #
+  # Built once during `NtiEventBus.setup!` and then deep-frozen via `#finalize!`, which makes reads
+  # (`#handlers_for`) lock-free and allocation-free on the hot path.
+  class Registry
+    EMPTY = [].freeze
+
+    def initialize
+      @handlers = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def add(event_name, handler)
+      list = @handlers[event_name]
+      list << handler unless list.include?(handler)
+    end
+
+    def finalize!
+      @handlers.each_value(&:freeze)
+      @handlers.freeze
+      self
+    end
+
+    def handlers_for(event_name)
+      @handlers.fetch(event_name, EMPTY)
+    end
+  end
+end

data/lib/nti_event_bus/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NtiEventBus
+  VERSION = '0.1.0'
+end

data/lib/nti_event_bus.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/string/inflections'
+
+require_relative 'nti_event_bus/version'
+require_relative 'nti_event_bus/configuration'
+require_relative 'nti_event_bus/registry'
+require_relative 'nti_event_bus/dsl'
+require_relative 'nti_event_bus/handler_base'
+require_relative 'nti_event_bus/dispatchers'
+require_relative 'nti_event_bus/handle_event_job'
+require_relative 'nti_event_bus/railtie' if defined?(Rails::Railtie)
+
+# Publish/subscribe event bus.
+#
+#   NtiEventBus.publish('order.created', { order_id: 1 })
+#
+# Handlers are declared in event files (see NtiEventBus::DSL) and executed asynchronously via a
+# configurable dispatcher (see NtiEventBus::Dispatchers). The subscription registry is built once by
+# `setup!`, deep-frozen, and read lock-free on the publish path.
+module NtiEventBus
+  class Error < StandardError; end
+
+  # Raised when the bus is used before `setup!` has run or when required configuration is missing.
+  class NotConfiguredError < Error; end
+
+  # Guards registry (re)builds; reads of the frozen registry never take this lock.
+  SETUP_MUTEX = Mutex.new
+
+  class << self
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Resets configuration to defaults. Intended for test suites.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Build the subscription registry from the configured event files and atomically install it.
+    #
+    # A fresh Registry is built, deep-frozen, then swapped in under SETUP_MUTEX. Readers always see a
+    # fully-frozen registry (the previous one or the new one) — never a half-built one.
+    def setup!
+      SETUP_MUTEX.synchronize do
+        registry = Registry.new
+        path = configuration.root_events_file!
+        DSL.new(registry, configuration.events_dir).instance_eval(File.read(path), path.to_s)
+        registry.finalize!
+
+        configuration.logger&.debug { "[NtiEventBus] registry built from #{path}" }
+        @registry = registry
+      end
+      self
+    end
+
+    def registry
+      @registry || raise(NotConfiguredError, 'NtiEventBus.setup! has not been run')
+    end
+
+    # Fan an event out to every subscribed handler via the configured dispatcher.
+    # Returns nil. Unknown events (no handlers) are a no-op.
+    def publish(event_name, payload)
+      handlers = registry.handlers_for(event_name)
+      return if handlers.empty?
+
+      dispatcher = configuration.dispatcher
+      handlers.each { |handler| dispatcher.call(handler.name, payload) }
+      nil
+    end
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: nti_event_bus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Den Meralpis
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: NtiEventBus is a lightweight publish/subscribe event bus. Declare `domain.action`
+  subscriptions in a small DSL, publish events, and fan them out to handler classes
+  asynchronously via ActiveJob. The subscription registry is built once and deep-frozen
+  for lock-free reads, so publishing adds no locking and no unbounded state.
+email:
+- denmark@nueca.com.ph
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/nti_event_bus.rb
+- lib/nti_event_bus/configuration.rb
+- lib/nti_event_bus/dispatchers.rb
+- lib/nti_event_bus/dsl.rb
+- lib/nti_event_bus/handle_event_job.rb
+- lib/nti_event_bus/handler_base.rb
+- lib/nti_event_bus/railtie.rb
+- lib/nti_event_bus/registry.rb
+- lib/nti_event_bus/version.rb
+homepage: https://github.com/nueca-tech/nti_event_bus
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/nueca-tech/nti_event_bus
+  source_code_uri: https://github.com/nueca-tech/nti_event_bus
+  changelog_uri: https://github.com/nueca-tech/nti_event_bus/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A production-grade event bus with a Rails DSL and asynchronous ActiveJob
+  dispatch.
+test_files: []