koine-event_manager 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83204e64656ac138a1079ca46b9380d9e925ab10a4d0e4b3af45a25d5253d5fe
-  data.tar.gz: 7db31b4a992772eefce2cda6a15588e29c199d7ba6bf2999e77598129f02a366
+  metadata.gz: 48dfe1c350d523d6dc0b09cec81848a225fa41cf02edd07fbe3c902f4e9ba826
+  data.tar.gz: c5d594bac4dc7e8ed338d485e5e5a2fcd4558f35533cd496d4497783644a543f
 SHA512:
-  metadata.gz: d29000bd69044fd15aae4935ce9d7dbc937b0e569aee4ade80393cbe32e054898b369fbd2cbe755a21bd2c64671e4e867e33d6887205e3ae09ad3caabaf5ed1a
-  data.tar.gz: 8326965bdc59e68b12c858f13c8196a813f33cb0596c800a236f0c0ebde88b627d9ce6c94341c0422aa840f059c162b742678d03ea18ee2c2b71af31ed20a860
+  metadata.gz: a465c356d1944acb9cb2c2aea7f4f269877a253dce7fce66798cb9cd6560c80c196c0151f7fbba0c746e6816bbca3038ac31f6e0a1bc272d42696f52b6af7755
+  data.tar.gz: 87700e2f619c41c382cace295d90b3d76afba14c3af5174769117b78196796199ed6921faa4b6e97ece79bb1889589b6b48089d9dc811d71d82081347230fcd1

data/README.md

@@ -242,12 +242,69 @@ class SessionsController < ApplicationController
 end
 ```
 
+### Error Isolation
+
+By default, an exception raised by a listener or subscriber propagates and aborts
+the dispatch. Pass an `on_error` callback to isolate failures so the remaining
+listeners still run:
+
+```ruby
+event_manager = Koine::EventManager::EventManager.new(
+  on_error: ->(error, event:, listener:) { Bugsnag.notify(error) }
+)
+```
+
+The callback is invoked as `on_error.call(error, event:, listener:)`, so it **must
+accept the `event:` and `listener:` keyword arguments** (the failing event and the
+listener/subscriber that raised). Use them to attribute the failure, or ignore them
+with a splat:
+
+```ruby
+on_error: ->(error, **) { Bugsnag.notify(error) }
+```
+
+Without `on_error` the behavior is unchanged (errors re-raise).
+
+### Post-commit Dispatch (Rails)
+
+`require "koine/event_manager/rails"` adds `TransactionalEventManager`, a drop-in
+subclass that defers dispatch until the current database transaction commits (or
+runs immediately when none is open), via `ActiveRecord.after_all_transactions_commit`.
+This keeps listeners from reacting to changes that a rollback would undo.
+
+```ruby
+require "koine/event_manager/rails"
+
+bus = Koine::EventManager::TransactionalEventManager.new(
+  on_error: ->(error, **) { Bugsnag.notify(error) }
+)
+```
+
+Requires ActiveRecord >= 7.2; the core library remains dependency-free, so only load
+this file from within a Rails/ActiveRecord process.
+
+Subscribers (and block listeners) are deferred by default. A reaction that must run
+**inside** the transaction — e.g. to write a related record atomically, or to raise
+and roll the whole operation back — can opt out with `after_commit: false`:
+
+```ruby
+bus.subscribe(AuditWriter.new, to: ProposalCreated)                      # post-commit, isolated
+bus.subscribe(InventoryReserver.new, to: ProposalCreated, after_commit: false) # in-transaction
+bus.listen_to(ProposalCreated, after_commit: false) { |e| ... }          # in-transaction block
+```
+
+Synchronous (`after_commit: false`) listeners run inline and their errors **propagate**
+(bypassing `on_error`), so a failed integrity reaction aborts the surrounding
+transaction. Deferred listeners stay isolated by `on_error`.
+
 ## API Reference
 
 ### EventManager
 
+- `EventManager.new(on_error: nil)` - Optionally isolate listener errors (see Error Isolation)
 - `listen_to(event_class, &block)` - Register a block to handle events
 - `trigger(event)` - Dispatch an event to all listeners and subscribers
+- `publish(event)` - Alias for `trigger` (pub/sub vocabulary)
 - `subscribe(subscriber, to: event_type)` - Add a subscriber for an event type
 - `unsubscribe(subscriber, from: event_type)` - Remove a subscriber
 - `attach_listener(listener)` - Attach an EventListener instance

data/lib/koine/event_manager/event_listener.rb

@@ -3,9 +3,10 @@
 module Koine
   module EventManager
     class EventListener
-      def initialize
+      def initialize(on_error: nil)
         @listeners = {}
         @subscribers = {}
+        @on_error = on_error
       end
 
       def listen_to(event_type, &block)
@@ -30,13 +31,13 @@ module Koine
 
       def trigger(event_object)
         listeners_for(event_object.class).each do |block|
-          block.call(event_object)
+          dispatch(event_object, block) { block.call(event_object) }
         end
 
         subscribers.each do |subscriber, events|
           events.each do |event|
             if event_object.class.ancestors.map(&:to_s).include?(event.to_s)
-              subscriber.publish(event_object)
+              dispatch(event_object, subscriber) { subscriber.publish(event_object) }
             end
           end
         end
@@ -50,6 +51,14 @@ module Koine
 
       private
 
+      def dispatch(event, listener)
+        yield
+      rescue StandardError => e
+        raise if @on_error.nil?
+
+        @on_error.call(e, event: event, listener: listener)
+      end
+
       def add_listener(event_type, &block)
         listeners[event_type.to_s] ||= []
         listeners[event_type.to_s] << block

data/lib/koine/event_manager/event_manager.rb

@@ -3,8 +3,13 @@
 module Koine
   module EventManager
     class EventManager
-      def initialize
-        @internal_listener = EventListener.new
+      def initialize(on_error: nil)
+        @on_error = on_error
+        @internal_listener = EventListener.new(on_error: on_error)
+      end
+
+      def publish(event)
+        trigger(event)
       end
 
       def listen_to(event, &block)
@@ -31,13 +36,23 @@ module Koine
         @internal_listener.trigger(event)
 
         listeners.each do |listener|
-          listener.trigger(event)
+          dispatch(event, listener) { listener.trigger(event) }
         end
       end
 
       def listeners
         @listeners ||= []
       end
+
+      private
+
+      def dispatch(event, listener)
+        yield
+      rescue StandardError => e
+        raise if @on_error.nil?
+
+        @on_error.call(e, event: event, listener: listener)
+      end
     end
   end
 end

data/lib/koine/event_manager/rails.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'koine/event_manager'
+
+module Koine
+  module EventManager
+    # Dispatches listeners after the current DB transaction commits (or runs
+    # immediately when none is open), so they never react to changes a rollback
+    # would undo. Requires ActiveRecord >= 7.2.
+    #
+    # Individual subscribers/listeners may opt into synchronous, in-transaction
+    # dispatch with `after_commit: false`. Those run inline and their errors
+    # propagate (bypassing `on_error` isolation), so an integrity reaction can
+    # abort the surrounding transaction. Post-commit listeners stay isolated.
+    class TransactionalEventManager < EventManager
+      alias deferred_dispatch trigger
+
+      def initialize(on_error: nil)
+        super
+        # In-transaction listeners: no on_error isolation, so a failure propagates
+        # and can roll the surrounding transaction back.
+        @synchronous = EventListener.new
+      end
+
+      def subscribe(subscriber, to:, after_commit: true)
+        return @synchronous.subscribe(subscriber, to: to) unless after_commit
+
+        super(subscriber, to: to)
+      end
+
+      def listen_to(event, after_commit: true, &block)
+        return @synchronous.listen_to(event, &block) unless after_commit
+
+        super(event, &block)
+      end
+
+      def unsubscribe(subscriber, from:)
+        @synchronous.unsubscribe(subscriber, from: from)
+        super
+      end
+
+      def trigger(event)
+        @synchronous.trigger(event)
+
+        unless active_record_available?
+          raise LoadError, 'TransactionalEventManager requires ActiveRecord >= 7.2 ' \
+                           '(after_all_transactions_commit). Load Rails before using it.'
+        end
+
+        ::ActiveRecord.after_all_transactions_commit do
+          deferred_dispatch(event)
+        end
+      end
+
+      private :deferred_dispatch
+
+      private
+
+      def active_record_available?
+        defined?(::ActiveRecord) &&
+          ::ActiveRecord.respond_to?(:after_all_transactions_commit)
+      end
+    end
+  end
+end

data/lib/koine/event_manager/version.rb

@@ -2,6 +2,6 @@
 
 module Koine
   module EventManager
-    VERSION = '3.0.0'
+    VERSION = '3.1.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: koine-event_manager
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Marcelo Jacobus
@@ -32,6 +32,7 @@ files:
 - lib/koine/event_manager.rb
 - lib/koine/event_manager/event_listener.rb
 - lib/koine/event_manager/event_manager.rb
+- lib/koine/event_manager/rails.rb
 - lib/koine/event_manager/version.rb
 homepage: https://github.com/mjacobus/koine-event-manager
 licenses: