listenable 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa0682e0a477e1a2367d552bab4b480cfdb2d902628cc0f3eff9b566750332b4
-  data.tar.gz: 81f80897906e86612474240bf7b1dedb2e7e21e4572d4313e61e65208f830d64
+  metadata.gz: 39c0faefb1a4b56eb6e359bc950a75bad47be727181b3fa7e751722c737a9fb3
+  data.tar.gz: 271cb3a4ccf5b357943967e9c503e8c6344be7e10e0439b7f6b0838b205fa228
 SHA512:
-  metadata.gz: 781cc4d59e3a98604a8c2e06a5d0d981513ab08814949695b0da3b4ff4d9bb3ce737386e414969ae13e1fca1bee2b67708a12f71d7b46a9f76fe2b19c4c961f3
-  data.tar.gz: c2ae5d198f292ea9fb2c9792da90cc0bb9a97ec950b48dbf79090a2c0ddbdef832289a807b958d9f83739d8b0999e48a50560e3a21b3be176041923a903a1669
+  metadata.gz: 4012acf44c48b3ebbc64060fe4488f81efd61eac703f476d20447ca6270003df1ddb5b27a997c43a59474827a2c2ab0bb0e92b18226379a7e19a3325540d8830
+  data.tar.gz: a8046f1f29c00b3b2db7fa90603c5b6acf69ccf868fdd84ce7064f1964a6e112e44cd9749a67c5bd538064b72bc4112e203cfd47674918945a97d6e792c57c9e

data/README.md

@@ -2,7 +2,7 @@
 
 Listenable is a Rails DSL that connects your ActiveRecord models to dedicated listener classes using `ActiveSupport::Notifications`.
 
-Instead of cluttering your models with callbacks, you declare listeners in `app/listeners`. Listenable automatically wires up the callbacks, instruments events, and runs your listener methods.
+Instead of cluttering your models with callbacks, you declare listeners in `app/listeners`. Listenable automatically wires up the callbacks, instruments events, and runs your listener methods. It supports both synchronous (blocking) and asynchronous (non-blocking) execution modes.
 
 ## Installation
 
@@ -18,6 +18,8 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install listenable
 ```
 
+**Note**: For asynchronous listener support, make sure you have the `concurrent-ruby` gem installed (usually included with Rails by default).
+
 ## Usage
 
 #### 1. Define a model
@@ -36,19 +38,19 @@ class UserListener
   listen :on_created, :on_updated, :on_deleted
 
   # Handle user creation
-  def on_created(record)
+  def self.on_created(record)
     Rails.logger.info "User created: #{user.id}"
     SendWelcomeEmailJob.perform_later(user)
   end
 
   # Handle user update
-  def on_updated(record)
+  def self.on_updated(record)
     Rails.logger.info "User updated: #{user.id}"
     SendProfileUpdateNotificationJob.perform_later(user)
   end
 
   # Handle user deletion
-  def on_deleted(record)
+  def self.on_deleted(record)
     Rails.logger.info "User deleted: #{user.id}"
     ArchiveUserDataJob.perform_later(user)
   end
@@ -65,12 +67,203 @@ Under the hood:
 * `ActiveSupport::Notifications.instrument` fires events like `user.created`.
 * The Railtie subscribes your listener methods to those events.
 
+## Synchronous vs Asynchronous Execution
+
+Listenable supports both synchronous (blocking) and asynchronous (non-blocking) listener execution:
+
+### Synchronous Listeners (Default)
+By default, listeners execute synchronously in the same thread as your model operations:
+
+```ruby
+class UserListener
+  include Listenable
+
+  # Synchronous execution (default)
+  listen :on_created, :on_updated, :on_deleted
+
+  def self.on_created(user)
+    Rails.logger.info "User created: #{user.id}"
+    # This runs in the same request thread
+  end
+end
+```
+
+### Asynchronous Listeners
+For non-blocking execution, use the `async: true` option:
+
+```ruby
+class UserListener
+  include Listenable
+
+  # Asynchronous execution - runs in background thread
+  listen :on_created, :on_updated, :on_deleted, async: true
+
+  def self.on_created(user)
+    Rails.logger.info "User created: #{user.id}"
+    # This runs in a separate thread, doesn't block the request
+    SendWelcomeEmailService.call(user)  # Safe for heavier operations
+  end
+end
+```
+
+### Mixed Execution Modes
+You can mix synchronous and asynchronous listeners by calling `listen` multiple times:
+
+```ruby
+class UserListener
+  include Listenable
+
+  # Some listeners run synchronously
+  listen :on_created
+
+  # Others run asynchronously
+  listen :on_updated, :on_deleted, async: true
+
+  def self.on_created(user)
+    # Runs synchronously - blocks request
+    user.update!(status: 'active')
+  end
+
+  def self.on_updated(user)
+    # Runs asynchronously - doesn't block request
+    UserAnalyticsService.new(user).calculate_metrics
+  end
+
+  def self.on_deleted(user)
+    # Also runs asynchronously
+    CleanupUserDataService.call(user)
+  end
+end
+```
+
 ## Supported hooks
-| Listener hook         | Model callback        |
-|-----------------------|-----------------------|
-| `on_created`          | `after_create`       |
-| `on_updated`          | `after_update`       |
-| `on_deleted`          | `after_destroy`      |
+| Listener hook         | Model callback        | Execution Mode |
+|-----------------------|-----------------------|----------------|
+| `on_created`          | `after_create`       | Synchronous (default) or Asynchronous with `async: true` |
+| `on_updated`          | `after_update`       | Synchronous (default) or Asynchronous with `async: true` |
+| `on_deleted`          | `after_destroy`      | Synchronous (default) or Asynchronous with `async: true` |
+
+All hooks support both synchronous and asynchronous execution modes via the `async: true` option.
+
+## Runtime Toggle
+By default, listeners are always active in development and production.
+
+You can enable/disable them dynamically at runtime using:
+
+```ruby
+Listenable.enabled = false  # disable all listeners
+Listenable.enabled = true   # re-enable listeners
+```
+
+This does not require restarting your Rails server or test suite.
+
+## RSpec/Test Integration
+You usually don’t want listeners firing in tests (e.g. sending jobs or emails).
+
+Disable them globally in your test suite:
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  config.before(:suite) do
+    Listenable.enabled = false
+  end
+
+  # Enable listeners selectively
+  config.around(:each, listenable: true) do |example|
+    prev = Listenable.enabled
+    Listenable.enabled = true
+    example.run
+    Listenable.enabled = prev
+  end
+end
+```
+
+Now:
+
+```ruby
+RSpec.describe User do
+  it 'does not fire listeners by default' do
+    expect(UserListener).not_to receive(:on_created)
+    User.create!(name: 'Pedro')
+  end
+
+  it 'fires synchronous listeners when enabled', listenable: true do
+    expect(UserListener).to receive(:on_created)
+    User.create!(name: 'Pedro')
+  end
+end
+```
+
+## ⚠️ Important: Execution Modes and Performance
+
+### Synchronous Listeners (Default Behavior)
+
+**Synchronous listeners execute in the same thread and will block the current request.** This means that all synchronous listener methods run in the same request/transaction as your model operations, which can impact performance and response times.
+
+**For synchronous listeners**: Always queue heavy operations in background jobs to maintain application performance:
+
+```ruby
+class UserListener
+  include Listenable
+
+  # Synchronous listeners (default)
+  listen :on_created, :on_updated
+
+  def self.on_created(user)
+    # ✅ Good - Lightweight operations or queue background jobs
+    SendWelcomeEmailJob.perform_later(user)
+    NotifyAdminsJob.perform_later(user)
+  end
+
+  def self.on_updated(user)
+    # ❌ Avoid - Heavy synchronous operations that block requests
+    # UserAnalyticsService.new(user).calculate_metrics  # This blocks!
+
+    # ✅ Better - Queue in background
+    CalculateUserMetricsJob.perform_later(user)
+  end
+end
+```
+
+### Asynchronous Listeners (Non-blocking)
+
+**Asynchronous listeners execute in separate threads and don't block requests.** This allows for heavier operations without impacting response times:
+
+```ruby
+class UserListener
+  include Listenable
+
+  # Asynchronous listeners - safe for heavier operations
+  listen :on_created, :on_updated, async: true
+
+  def self.on_created(user)
+    # ✅ Safe - Runs in background thread
+    UserAnalyticsService.new(user).calculate_metrics
+    SendWelcomeEmailService.call(user)
+  end
+
+  def self.on_updated(user)
+    # ✅ Safe - Heavy operations won't block requests
+    ExternalApiService.notify_user_update(user)
+    GenerateUserReportService.call(user)
+  end
+end
+```
+
+**Note**: Asynchronous listeners use `Concurrent::Promises` for thread-safe execution. Errors in async listeners are logged but won't affect the main request flow.
+
+### Choosing the Right Mode
+
+- **Use synchronous listeners** for:
+  - Critical operations that must complete before the request finishes
+  - Simple, fast operations (logging, simple updates)
+  - Operations that need to participate in the same database transaction
+
+- **Use asynchronous listeners** for:
+  - Heavy computations or external API calls
+  - Non-critical operations that can fail independently
+  - Operations that don't need to complete before the response is sent
 
 ## Development
 
@@ -80,7 +273,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Todo:
 * Create rake tasks to generate listener files.
-* RSpec tests for Railtie and integration tests.
 
 ## Contributing
 

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/lib/listenable/concern.rb

@@ -2,9 +2,9 @@
 
 module Listenable
   CALLBACK_MAP = {
-    "created" => :after_create,
-    "updated" => :after_update,
-    "deleted" => :after_destroy
+    'created' => :after_create,
+    'updated' => :after_update,
+    'deleted' => :after_destroy
   }.freeze
 
   def self.included(base)
@@ -12,9 +12,12 @@ module Listenable
   end
 
   module ClassMethods
-    def listen(*hooks)
+    def listen(*hooks, async: false)
       @pending_hooks ||= []
-      @pending_hooks.concat(hooks.map(&:to_s))
+
+      hooks.each do |hook|
+        @pending_hooks << { name: hook.to_s, async: async }
+      end
     end
 
     def pending_hooks

data/lib/listenable/railtie.rb

@@ -2,39 +2,58 @@
 
 module Listenable
   class Railtie < Rails::Railtie
-    initializer "listenable.load" do
+    initializer 'listenable.load' do
       Rails.application.config.to_prepare do
-        # Load all listeners (supports nested paths)
-        Dir[Rails.root.join("app/listeners/**/*.rb")].each { |f| require_dependency f }
+        # Load all listeners (recursive, supports namespaced)
+        Dir[Rails.root.join('app/listeners/**/*.rb')].each { |f| require_dependency f }
 
-        # Wire models + listeners
+        # Find all listener classes
         ObjectSpace.each_object(Class).select { |klass| klass < Listenable }.each do |listener_class|
-          model_class_name = listener_class.name.sub("Listener", "")
-          model_class = model_class_name.safe_constantize
+          model_class_name = listener_class.name.sub('Listener', '')
+          model_class      = model_class_name.safe_constantize
           next unless model_class
 
-          listener_class.pending_hooks.each do |hook|
-            action   = hook.sub("on_", "")
+          listener_class.pending_hooks.each do |hook_info|
+            hook     = hook_info[:name]
+            async    = hook_info[:async]
+            action   = hook.sub('on_', '')
             callback = Listenable::CALLBACK_MAP[action] or next
             method   = "on_#{action}"
             event    = "#{model_class_name.underscore}.#{action}"
 
-            # Avoid duplicate subscriptions on reload
+            # unsubscribe old subscribers
             ActiveSupport::Notifications.notifier.listeners_for(event).each do |subscriber|
               ActiveSupport::Notifications.unsubscribe(subscriber)
             end
 
-            # Inject ActiveRecord callback
-            model_class.send(callback) do
-              ActiveSupport::Notifications.instrument(event, record: self)
+            injected_events = model_class.instance_variable_get(:@_listenable_injected_events) || []
+            unless injected_events.include?(event)
+              model_class.send(callback) do
+                next unless Listenable.enabled
+
+                ActiveSupport::Notifications.instrument(event, record: self)
+              end
+              injected_events << event
+              model_class.instance_variable_set(:@_listenable_injected_events, injected_events)
             end
 
-            # Subscribe listener
             next unless listener_class.respond_to?(method)
 
             ActiveSupport::Notifications.subscribe(event) do |*args|
+              next unless Listenable.enabled
+
               _name, _start, _finish, _id, payload = args
-              listener_class.public_send(method, payload[:record])
+              record = payload[:record]
+
+              if async
+                Concurrent::Promises.future do
+                  listener_class.public_send(method, record)
+                end.rescue do |e|
+                  Rails.logger.error("[Listenable] #{listener_class}##{method} failed: #{e.message}")
+                end
+              else
+                listener_class.public_send(method, record)
+              end
             end
           end
         end

data/lib/listenable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Listenable
-  VERSION = "0.1.0"
+  VERSION = '0.2.0'
 end

data/lib/listenable.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
-require "active_support"
-require "active_support/concern"
-require "active_support/notifications"
+require 'active_support'
+require 'active_support/concern'
+require 'active_support/notifications'
 
-require_relative "listenable/version"
-require_relative "listenable/concern"
-require_relative "listenable/railtie" if defined?(Rails)
+require_relative 'listenable/version'
+require_relative 'listenable/concern'
+require_relative 'listenable/railtie' if defined?(Rails)
 
 module Listenable
+  mattr_accessor :enabled, default: true
+
   class Error < StandardError; end
   # Your code goes here...
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: listenable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Den Meralpis
@@ -23,6 +23,62 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
 description: Listenable makes it easy to wire ActiveRecord models to listener classes.
   Define <Model>Listener classes in app/listeners, declare listen :on_created, :on_updated,
   etc., and Listenable automatically injects callbacks and subscribes to ActiveSupport::Notifications.