servus 0.1.4 → 0.1.6

data/lib/servus/events/bus.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Servus
+  module Events
+    # Thread-safe event bus for registering and dispatching event handlers.
+    #
+    # The Bus acts as a central registry that maps event names to their
+    # corresponding handler classes. It uses ActiveSupport::Notifications
+    # internally to provide instrumentation and thread-safe event dispatch.
+    #
+    # Events are automatically instrumented and will appear in Rails logs
+    # with timing information, making it easy to monitor event performance.
+    #
+    # @example Registering a handler
+    #   class UserCreatedHandler < Servus::EventHandler
+    #     handles :user_created
+    #   end
+    #
+    #   Servus::Events::Bus.register_handler(:user_created, UserCreatedHandler)
+    #
+    # @example Retrieving handlers for an event
+    #   handlers = Servus::Events::Bus.handlers_for(:user_created)
+    #   handlers.each { |handler| handler.handle(payload) }
+    #
+    # @example Instrumentation in logs
+    #   Bus.emit(:user_created, user_id: 123)
+    #   # Rails log: servus.events.user_created (1.2ms) {:user_id=>123}
+    #
+    # @see Servus::EventHandler
+    class Bus
+      class << self
+        # Registers a handler class for a specific event.
+        #
+        # Multiple handlers can be registered for the same event, and they
+        # will all be invoked when the event is emitted. The handler is
+        # automatically subscribed to ActiveSupport::Notifications.
+        #
+        # Handlers are typically registered automatically when EventHandler
+        # classes are loaded at boot time via the `handles` DSL method.
+        #
+        # @param event_name [Symbol] the name of the event
+        # @param handler_class [Class] the handler class to register
+        # @return [Array] the updated array of handlers for this event
+        #
+        # @example
+        #   Bus.register_handler(:user_created, UserCreatedHandler)
+        def register_handler(event_name, handler_class)
+          handlers[event_name] ||= []
+          handlers[event_name] << handler_class
+
+          # Subscribe to ActiveSupport::Notifications
+          subscription = ActiveSupport::Notifications.subscribe(notification_name(event_name)) do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            handler_class.handle(event.payload)
+          end
+
+          # Store subscription for cleanup
+          subscriptions[event_name] ||= []
+          subscriptions[event_name] << subscription
+        end
+
+        # Retrieves all registered handlers for a specific event.
+        #
+        # Returns a duplicate array to prevent external modification of the
+        # internal handler registry.
+        #
+        # @param event_name [Symbol] the name of the event
+        # @return [Array<Class>] array of handler classes registered for this event
+        #
+        # @example
+        #   handlers = Bus.handlers_for(:user_created)
+        #   handlers.each { |handler| handler.handle(payload) }
+        def handlers_for(event_name)
+          (handlers[event_name] || []).dup
+        end
+
+        # Emits an event to all registered handlers with instrumentation.
+        #
+        # Uses ActiveSupport::Notifications to instrument the event, providing
+        # automatic timing and logging. The event will appear in Rails logs
+        # with duration and payload information.
+        #
+        # @param event_name [Symbol] the name of the event to emit
+        # @param payload [Hash] the event payload to pass to handlers
+        # @return [void]
+        #
+        # @example
+        #   Bus.emit(:user_created, { user_id: 123, email: 'user@example.com' })
+        #   # Rails log: servus.events.user_created (1.2ms) {:user_id=>123, :email=>"user@example.com"}
+        def emit(event_name, payload)
+          ActiveSupport::Notifications.instrument(notification_name(event_name), payload)
+        end
+
+        # Clears all registered handlers and unsubscribes from notifications.
+        #
+        # Useful for testing and development mode reloading.
+        #
+        # @return [void]
+        #
+        # @example
+        #   Bus.clear
+        def clear
+          subscriptions.values.flatten.each do |subscription|
+            ActiveSupport::Notifications.unsubscribe(subscription)
+          end
+
+          @handlers = nil
+          @subscriptions = nil
+        end
+
+        private
+
+        # Hash storing event handlers.
+        #
+        # @return [Hash] hash mapping event names to handler arrays
+        def handlers
+          @handlers ||= {}
+        end
+
+        # Hash storing ActiveSupport::Notifications subscriptions.
+        #
+        # @return [Hash] hash mapping event names to subscription objects
+        def subscriptions
+          @subscriptions ||= {}
+        end
+
+        # Converts an event name to a namespaced notification name.
+        #
+        # @param event_name [Symbol] the event name
+        # @return [String] the namespaced notification name
+        def notification_name(event_name)
+          "servus.events.#{event_name}"
+        end
+      end
+    end
+  end
+end

data/lib/servus/events/emitter.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Servus
+  module Events
+    # Provides event emission DSL for service objects.
+    #
+    # This module adds the `emits` class method to services, allowing them to
+    # declare events that will be automatically emitted on success, failure, or error.
+    #
+    # @example Basic usage
+    #   class CreateUser < Servus::Base
+    #     emits :user_created, on: :success
+    #     emits :user_failed, on: :failure
+    #   end
+    module Emitter
+      extend ActiveSupport::Concern
+
+      # Emits events for a service result.
+      #
+      # Called automatically after service execution completes. Determines the
+      # trigger type based on the result and emits all configured events.
+      #
+      # @param instance [Servus::Base] the service instance
+      # @param result [Servus::Support::Response] the service result
+      # @return [void]
+      # @api private
+      def self.emit_result_events!(instance, result)
+        trigger = result.success? ? :success : :failure
+        instance.send(:emit_events_for, trigger, result)
+      end
+
+      class_methods do
+        # Declares an event that this service will emit.
+        #
+        # Events are automatically emitted when the service completes with the specified
+        # trigger condition (:success, :failure, or :error). Use the `with` option to
+        # provide a custom payload builder, or pass a block.
+        #
+        # @param event_name [Symbol] the name of the event to emit
+        # @param on [Symbol] when to emit (:success, :failure, or :error)
+        # @param with [Symbol, nil] optional instance method name for building the payload
+        # @yield [result] optional block for building the payload
+        # @yieldparam result [Servus::Support::Response] the service result
+        # @yieldreturn [Hash] the event payload
+        # @return [void]
+        #
+        # @example Emit on success with default payload
+        #   class CreateUser < Servus::Base
+        #     emits :user_created, on: :success
+        #   end
+        #
+        # @example Emit with custom payload builder method
+        #   class CreateUser < Servus::Base
+        #     emits :user_created, on: :success, with: :user_payload
+        #
+        #     private
+        #
+        #     def user_payload(result)
+        #       { user_id: result.data[:user].id }
+        #     end
+        #   end
+        #
+        # @example Emit with custom payload builder block
+        #   class CreateUser < Servus::Base
+        #     emits :user_created, on: :success do |result|
+        #       { user_id: result.data[:user].id }
+        #     end
+        #   end
+        #
+        # @note Best Practice: Services should typically emit ONE event per trigger
+        #   that represents their core concern. Multiple downstream reactions should
+        #   be coordinated by EventHandler classes, not by emitting multiple events
+        #   from the service. This maintains separation of concerns.
+        #
+        # @example Recommended pattern (one event, multiple handlers)
+        #   # Service emits one event
+        #   class CreateUser < Servus::Base
+        #     emits :user_created, on: :success
+        #   end
+        #
+        #   # Handler coordinates multiple reactions
+        #   class UserCreatedHandler < Servus::EventHandler
+        #     handles :user_created
+        #     invoke SendWelcomeEmail::Service, async: true
+        #     invoke TrackAnalytics::Service, async: true
+        #   end
+        #
+        # @see Servus::Events::Bus
+        # @see Servus::EventHandler
+        def emits(event_name, on:, with: nil, &block)
+          valid_triggers = %i[success failure error!]
+
+          unless valid_triggers.include?(on)
+            raise ArgumentError, "Invalid trigger: #{on}. Must be one of: #{valid_triggers.join(', ')}"
+          end
+
+          @event_emissions ||= { success: [], failure: [], error!: [] }
+          @event_emissions[on] << {
+            event_name: event_name,
+            payload_builder: block || with
+          }
+        end
+
+        # Returns all event emissions declared for this service.
+        #
+        # @return [Hash] hash of event emissions grouped by trigger
+        #   { success: [...], failure: [...], error!: [...] }
+        def event_emissions
+          @event_emissions || { success: [], failure: [], error!: [] }
+        end
+
+        # Returns event emissions for a specific trigger.
+        #
+        # @param trigger [Symbol] the trigger type (:success, :failure, :error!)
+        # @return [Array<Hash>] array of event configurations for this trigger
+        def emissions_for(trigger)
+          event_emissions[trigger] || []
+        end
+      end
+
+      # Emits events for a specific trigger with the given result.
+      #
+      # @param trigger [Symbol] the trigger type (:success, :failure, :error!)
+      # @param result [Servus::Support::Response] the service result
+      # @return [void]
+      # @api private
+      def emit_events_for(trigger, result)
+        self.class.emissions_for(trigger).each do |emission|
+          payload = build_event_payload(emission, result)
+          Servus::Events::Bus.emit(emission[:event_name], payload)
+        end
+      end
+
+      # Instance methods for emitting events during service execution
+      private
+
+      # Builds the event payload using the configured payload builder or defaults.
+      #
+      # @param emission [Hash] the emission configuration
+      # @param result [Servus::Support::Response] the service result
+      # @return [Hash] the event payload
+      # @api private
+      def build_event_payload(emission, result)
+        builder = emission[:payload_builder]
+
+        if builder.is_a?(Proc)
+          # Block-based payload builder
+          builder.call(result)
+        elsif builder.is_a?(Symbol)
+          # Method-based payload builder
+          send(builder, result)
+        elsif result.success?
+          # Default for success: return data
+          result.data
+        else
+          # Default for failure/error: return error
+          result.error
+        end
+      end
+    end
+  end
+end

data/lib/servus/events/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Servus
+  module Events
+    # Raised when an event handler subscribes to an event that no service emits.
+    #
+    # This helps catch typos in event names and orphaned handlers.
+    class OrphanedHandlerError < StandardError; end
+  end
+end

data/lib/servus/railtie.rb

@@ -18,5 +18,21 @@ module Servus
         Servus::Base.extend Servus::Extensions::Async::Call
       end
     end
+
+    # Load event handlers and clear on reload
+    config.to_prepare do
+      Servus::Events::Bus.clear if Rails.env.development?
+
+      # Eager load all event handlers
+      events_path = Rails.root.join(Servus.config.events_dir)
+      Dir[File.join(events_path, '**/*_handler.rb')].each do |handler_file|
+        require_dependency handler_file
+      end
+    end
+
+    # NOTE: Event validation is available but not run automatically due to load order issues.
+    # To validate handlers match emitted events, call manually:
+    #   Servus::EventHandler.validate_all_handlers!
+    # Or create a rake task for CI validation.
   end
 end

data/lib/servus/support/validator.rb

@@ -90,6 +90,33 @@ module Servus
         result
       end
 
+      # Validates event payload against the handler's payload schema.
+      #
+      # @param handler_class [Class] the event handler class
+      # @param payload [Hash] the event payload to validate
+      # @return [Boolean] true if validation passes
+      # @raise [Servus::Support::Errors::ValidationError] if payload fails validation
+      #
+      #
+      # @example
+      #   Validator.validate_event_payload!(MyEventHandler, { user_id: 123 })
+      #
+      # @api private
+      def self.validate_event_payload!(handler_class, payload)
+        schema = handler_class.payload_schema
+        return true unless schema
+
+        serialized_payload = payload.as_json
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_payload)
+
+        if validation_errors.any?
+          raise Servus::Support::Errors::ValidationError,
+                "Invalid payload for event :#{handler_class.event_name}: #{validation_errors.join(', ')}"
+        end
+
+        true
+      end
+
       # Loads and caches a schema for a service.
       #
       # Implements a three-tier lookup strategy:

data/lib/servus/testing/matchers.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+require 'rspec/expectations'
+
+module Servus
+  module Testing
+    # RSpec matchers for testing Servus services and events.
+    module Matchers
+    end
+  end
+end
+
+# Matcher for asserting event emission
+RSpec::Matchers.define :emit_event do |handler_class_or_symbol|
+  supports_block_expectations
+
+  chain :with do |payload|
+    @expected_payload = payload
+  end
+
+  match do |block|
+    @captured_events = []
+
+    subscription = ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, *_args, payload|
+      event_name = name.sub('servus.events.', '').to_sym
+      @captured_events << { name: event_name, payload: payload }
+    end
+
+    block.call
+
+    # Determine event name
+    @event_name = if handler_class_or_symbol.is_a?(Symbol)
+                    handler_class_or_symbol
+                  else
+                    handler_class_or_symbol.event_name
+                  end
+
+    @matching_event = @captured_events.find { |e| e[:name] == @event_name }
+
+    return false unless @matching_event
+    return true unless @expected_payload
+
+    RSpec::Matchers::BuiltIn::Match.new(@expected_payload).matches?(@matching_event[:payload])
+  ensure
+    ActiveSupport::Notifications.unsubscribe(subscription) if subscription
+  end
+
+  failure_message do
+    if @matching_event.nil?
+      "expected event :#{@event_name} to be emitted, but it was not.\n" \
+        "Emitted: #{@captured_events.map { |e| e[:name] }}"
+    else
+      "expected event :#{@event_name} payload to match #{@expected_payload.inspect}, " \
+        "got: #{@matching_event[:payload].inspect}"
+    end
+  end
+end
+
+# Matcher for asserting service invocation
+RSpec::Matchers.define :call_service do |service_class|
+  supports_block_expectations
+
+  chain :with do |args|
+    @expected_args = args
+  end
+
+  chain :async do
+    @expect_async = true
+  end
+
+  match do |block|
+    method_name = @expect_async ? :call_async : :call
+
+    expectation = expect(service_class).to receive(method_name)
+    expectation.with(@expected_args) if @expected_args
+
+    block.call
+
+    true
+  end
+
+  failure_message do
+    method = @expect_async ? 'call_async' : 'call'
+    "expected #{service_class} to receive #{method}"
+  end
+end
+# rubocop:enable Metrics/BlockLength

data/lib/servus/testing.rb

@@ -9,9 +9,11 @@ module Servus
   #
   # @see Servus::Testing::ExampleBuilders
   # @see Servus::Testing::ExampleExtractor
+  # @see Servus::Testing::Matchers
   module Testing
   end
 end
 
 require_relative 'testing/example_extractor'
 require_relative 'testing/example_builders'
+require_relative 'testing/matchers'

data/lib/servus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Servus
-  VERSION = '0.1.4'
+  VERSION = '0.1.6'
 end

data/lib/servus.rb

@@ -25,6 +25,12 @@ require_relative 'servus/support/validator'
 require_relative 'servus/support/errors'
 require_relative 'servus/support/rescuer'
 
+# Events
+require_relative 'servus/events/errors'
+require_relative 'servus/events/bus'
+require_relative 'servus/events/emitter'
+require_relative 'servus/event_handler'
+
 # Core
 require_relative 'servus/version'
 require_relative 'servus/base'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -74,10 +74,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/commands/check-docs.md"
+- ".claude/commands/consistency-check.md"
+- ".claude/commands/fine-tooth-comb.md"
+- ".claude/commands/red-green-refactor.md"
+- ".claude/settings.json"
 - ".rspec"
 - ".rubocop.yml"
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - IDEAS.md
 - LICENSE.txt
 - READme.md
@@ -87,13 +93,16 @@ files:
 - builds/servus-0.1.2.gem
 - builds/servus-0.1.3.gem
 - builds/servus-0.1.4.gem
+- builds/servus-0.1.5.gem
 - docs/core/1_overview.md
 - docs/core/2_architecture.md
 - docs/core/3_service_objects.md
+- docs/current_focus.md
 - docs/features/1_schema_validation.md
 - docs/features/2_error_handling.md
 - docs/features/3_async_execution.md
 - docs/features/4_logging.md
+- docs/features/5_event_bus.md
 - docs/guides/1_common_patterns.md
 - docs/guides/2_migration_guide.md
 - docs/integration/1_configuration.md
@@ -177,6 +186,9 @@ files:
 - docs/yard/js/jquery.js
 - docs/yard/method_list.html
 - docs/yard/top-level-namespace.html
+- lib/generators/servus/event_handler/event_handler_generator.rb
+- lib/generators/servus/event_handler/templates/handler.rb.erb
+- lib/generators/servus/event_handler/templates/handler_spec.rb.erb
 - lib/generators/servus/service/service_generator.rb
 - lib/generators/servus/service/templates/arguments.json.erb
 - lib/generators/servus/service/templates/result.json.erb
@@ -185,6 +197,10 @@ files:
 - lib/servus.rb
 - lib/servus/base.rb
 - lib/servus/config.rb
+- lib/servus/event_handler.rb
+- lib/servus/events/bus.rb
+- lib/servus/events/emitter.rb
+- lib/servus/events/errors.rb
 - lib/servus/extensions/async/call.rb
 - lib/servus/extensions/async/errors.rb
 - lib/servus/extensions/async/ext.rb
@@ -199,6 +215,7 @@ files:
 - lib/servus/testing.rb
 - lib/servus/testing/example_builders.rb
 - lib/servus/testing/example_extractor.rb
+- lib/servus/testing/matchers.rb
 - lib/servus/version.rb
 - sig/servus.rbs
 homepage: https://github.com/zarpay/servus
@@ -208,6 +225,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/zarpay/servus
   changelog_uri: https://github.com/zarpay/servus/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib