listenable 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebe46a89c412b54c70f0af2f7851f46176dfd08c3dc5a611ef61c35d0bea1717
-  data.tar.gz: c19ed7b192adc50833b432058cfcdf652add0401bbbca28e869c282186ef7e88
+  metadata.gz: 39c0faefb1a4b56eb6e359bc950a75bad47be727181b3fa7e751722c737a9fb3
+  data.tar.gz: 271cb3a4ccf5b357943967e9c503e8c6344be7e10e0439b7f6b0838b205fa228
 SHA512:
-  metadata.gz: 6083b9a19eb74cceaec96942846f3a7b7754bf0ed27f42686f67351e8b6bd7246392c485a7b0ad4e35d909d85eb2b0f4f2cf33ebf0529ff475c9ed11b9857e68
-  data.tar.gz: 2b4c5d0b93694b35f3431f9cef48794182a621e8f937fc01bb745b895d3edbff5b38ce27c42a78c69622fecd2d2e5e1d35d5b2e171f5080dd2fd4344619c6ebd
+  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,83 @@ 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.
@@ -115,13 +188,82 @@ RSpec.describe User do
     User.create!(name: 'Pedro')
   end
 
-  it 'fires listeners when enabled', listenable: true do
+  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
 
@@ -131,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,45 +2,57 @@
 
 module Listenable
   class Railtie < Rails::Railtie
-    initializer "listenable.load" do
+    initializer 'listenable.load' do
       Rails.application.config.to_prepare do
         # Load all listeners (recursive, supports namespaced)
-        Dir[Rails.root.join("app/listeners/**/*.rb")].each { |f| require_dependency f }
+        Dir[Rails.root.join('app/listeners/**/*.rb')].each { |f| require_dependency f }
 
         # 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_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}"
 
-            # Unsubscribe duplicates
+            # unsubscribe old subscribers
             ActiveSupport::Notifications.notifier.listeners_for(event).each do |subscriber|
               ActiveSupport::Notifications.unsubscribe(subscriber)
             end
 
-            # Inject AR callback once per model/event
             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 (runtime-guarded)
-            if 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])
+            next unless listener_class.respond_to?(method)
+
+            ActiveSupport::Notifications.subscribe(event) do |*args|
+              next unless Listenable.enabled
+
+              _name, _start, _finish, _id, payload = args
+              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

data/lib/listenable/version.rb

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

data/lib/listenable.rb

@@ -1,12 +1,12 @@
 # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: listenable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  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.