servus 0.4.0 → 0.5.0

data/lib/servus/events/class_router.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Servus
+  module Events
+    # Default router that reads +invoke+ declarations from Event classes.
+    #
+    # ClassRouter is what ships with Servus and is the default when no
+    # routers are configured. It resolves invocations by looking up all
+    # Event classes registered for the given event name and calling
+    # +invocations_for+ on each — which evaluates if/unless conditions
+    # and returns Invocation objects for actions that should run.
+    #
+    # Applications can add additional routers (e.g. a data-driven router
+    # backed by a database table) alongside the ClassRouter:
+    #
+    #   Servus.configure do |config|
+    #     config.routers = [
+    #       Servus::Events::ClassRouter.new,
+    #       MyApp::DataDrivenRouter.new
+    #     ]
+    #   end
+    #
+    # @see Servus::Events::Router
+    # @see Servus::Event#invocations_for
+    class ClassRouter < Router
+      # Resolves invocations by reading +invoke+ declarations from all
+      # Event classes registered for the given event name.
+      #
+      # @param event_name [Symbol] the name of the emitted event
+      # @param payload [Hash] the event payload
+      # @return [Array<Servus::Events::Invocation>] invocations to execute
+      def resolve(event_name, payload)
+        event_class = Bus.event_for(event_name)
+        return [] unless event_class
+
+        event_class.invocations_for(payload)
+      end
+    end
+  end
+end

data/lib/servus/events/emitter.rb

@@ -69,24 +69,24 @@ module Servus
         #
         # @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
+        #   be coordinated by Event classes, not by emitting multiple events
         #   from the service. This maintains separation of concerns.
         #
-        # @example Recommended pattern (one event, multiple handlers)
+        # @example Recommended pattern (one event, multiple reactions)
         #   # 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
+        #   # Event coordinates multiple reactions
+        #   class UserCreated < Servus::Event
+        #     event_name :user_created
         #     invoke SendWelcomeEmail::Service, async: true
         #     invoke TrackAnalytics::Service, async: true
         #   end
         #
         # @see Servus::Events::Bus
-        # @see Servus::EventHandler
+        # @see Servus::Event
         def emits(event_name, on:, with: nil, &block)
           valid_triggers = %i[success failure error!]
 
@@ -128,7 +128,6 @@ module Servus
         self.class.emissions_for(trigger).each do |emission|
           payload = build_event_payload(emission, result)
           validate_event_payload!(emission[:event_name], payload)
-          Servus::Support::Logger.log_event(emission[:event_name], payload)
           Servus::Events::Bus.emit(emission[:event_name], payload)
         end
       end
@@ -136,7 +135,7 @@ module Servus
       # Instance methods for emitting events during service execution
       private
 
-      # Validates the payload against all handler schemas registered for the event.
+      # Validates the payload against the Event class's schema registered for the event.
       #
       # @param event_name [Symbol] the event name
       # @param payload [Hash] the event payload
@@ -144,9 +143,10 @@ module Servus
       # @raise [Servus::Support::Errors::ValidationError] if payload fails validation
       # @api private
       def validate_event_payload!(event_name, payload)
-        Servus::Events::Bus.handlers_for(event_name).each do |handler_class|
-          Servus::Support::Validator.validate_event_payload!(handler_class, payload)
-        end
+        event_class = Servus::Events::Bus.event_for(event_name)
+        return unless event_class
+
+        Servus::Support::Validator.validate_event_payload!(event_class, payload)
       end
 
       # Builds the event payload using the configured payload builder or defaults.

data/lib/servus/events/invocation.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Servus
+  module Events
+    # A normalized, executable representation of "call this service with
+    # these params."
+    #
+    # Routers return arrays of Invocation objects. The Bus collects them,
+    # deduplicates by +#key+ (first wins), and calls +#execute+ on each.
+    #
+    # An Invocation separates *identity* (service + params) from
+    # *execution strategy* (async, queue, priority, etc.). The +#key+
+    # is derived only from the identity — two invocations that call the
+    # same service with the same params are considered duplicates
+    # regardless of their options.
+    #
+    # @example Sync invocation
+    #   Invocation.new(
+    #     service: Rewards::Grant::Service,
+    #     params:  { user_id: "abc-123" },
+    #     options: {}
+    #   )
+    #
+    # @example Async invocation with scheduling options
+    #   Invocation.new(
+    #     service: Notifications::Send::Service,
+    #     params:  { user_id: "abc-123" },
+    #     options: { async: true, queue: :mailers, priority: 5 }
+    #   )
+    #
+    # @see Servus::Events::Router
+    # @see Servus::Events::Bus
+    class Invocation
+      # @return [Class] the service class to call (must respond to +.call+ or +.call_async+)
+      attr_reader :service
+
+      # @return [Hash] keyword arguments passed to the service
+      attr_reader :params
+
+      # @return [Hash] execution options — +async+, +queue+, +wait+,
+      #   +wait_until+, +priority+, +job_options+
+      attr_reader :options
+
+      # @param service [Class] the service class
+      # @param params [Hash] keyword arguments for the service
+      # @param options [Hash] execution options
+      def initialize(service:, params:, options: {})
+        @service = service
+        @params  = params
+        @options = options
+      end
+
+      # Executes the invocation.
+      #
+      # Delegates to +service.call+ for synchronous invocations or
+      # +service.call_async+ for asynchronous ones. Async scheduling
+      # options (queue, wait, priority, etc.) are merged into the
+      # call_async kwargs.
+      #
+      # @return [Servus::Support::Response, void]
+      def execute
+        if options[:async]
+          service.call_async(**params, **async_options)
+        else
+          service.call(**params)
+        end
+      end
+
+      # A deterministic deduplication key derived from the service class
+      # and params. Two invocations with the same key are considered
+      # duplicates — the Bus keeps the first and skips the rest.
+      #
+      # Options are intentionally excluded: identity is *what* to call,
+      # not *how* to call it.
+      #
+      # @return [String] SHA-256 hex digest
+      def key
+        Digest::SHA256.hexdigest("#{service}:#{params.to_json}")
+      end
+
+      private
+
+      # Extracts scheduling options for +call_async+.
+      #
+      # @return [Hash]
+      def async_options
+        options.slice(:queue, :wait, :wait_until, :priority, :job_options).compact
+      end
+    end
+  end
+end

data/lib/servus/events/router.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Servus
+  module Events
+    # Abstract base class for event routers.
+    #
+    # Routers resolve which services should be invoked when an event fires.
+    # The Bus iterates all configured routers (in order), collects the
+    # Invocation objects they return, deduplicates by key, and executes.
+    #
+    # Servus ships one built-in router — ClassRouter — which reads the
+    # +invoke+ declarations from Event classes. Applications can add their
+    # own routers (e.g. a data-driven router backed by a database table)
+    # by subclassing Router and implementing +#resolve+.
+    #
+    # Configure routers in the Servus initializer:
+    #
+    #   Servus.configure do |config|
+    #     config.routers = [
+    #       Servus::Events::ClassRouter.new,
+    #       MyApp::DataDrivenRouter.new
+    #     ]
+    #   end
+    #
+    # @see Servus::Events::ClassRouter
+    # @see Servus::Events::Invocation
+    # @see Servus::Events::Bus
+    class Router
+      # Resolves which service invocations should run for the given event.
+      #
+      # Implementations must evaluate any conditions (if/unless) internally
+      # and return only invocations that *will* run. The Bus does not
+      # perform further filtering.
+      #
+      # @param event_name [Symbol] the name of the emitted event
+      # @param payload [Hash] the event payload
+      # @return [Array<Servus::Events::Invocation>] invocations to execute
+      # @raise [NotImplementedError] when called on the abstract base class
+      def resolve(event_name, payload)
+        raise NotImplementedError, "#{self.class}#resolve must be implemented"
+      end
+    end
+  end
+end

data/lib/servus/railtie.rb

@@ -25,7 +25,11 @@ module Servus
       end
     end
 
-    # Load guards and event handlers, clear caches on reload
+    initializer 'servus.event_logging' do
+      Servus::Events::Bus.enable_logging!
+    end
+
+    # Load guards and event classes, clear caches on reload
     config.to_prepare do
       # Load custom guards from guards_dir
       guards_path = Rails.root.join(Servus.config.guards_dir)
@@ -37,16 +41,14 @@ module Servus
 
       Servus::Events::Bus.clear if Rails.env.development?
 
-      # Eager load all event handlers
+      # Eager load all event classes
       events_path = Rails.root.join(Servus.config.events_dir)
-      Dir[File.join(events_path, '**/*_handler.rb')].each do |file|
+      Dir[File.join(events_path, '**/*_event.rb')].each do |file|
         require_dependency 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.
+      # Infer and register event names for classes that didn't call event_name explicitly
+      Servus::Event.descendants.each(&:ensure_registered!)
+    end
   end
 end

data/lib/servus/support/errors.rb

@@ -267,7 +267,7 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
-      # Raised when a service or event handler is invoked without a required schema.
+      # Raised when a service or Event class is used without a required schema.
       #
       # Triggered by the +require_service_arguments_schema+,
       # +require_service_result_schema+, or +require_event_payload_schema+

data/lib/servus/support/logger.rb

@@ -63,12 +63,14 @@ module Servus
         logger.warn("#{service_class.name} guard failed: #{error.message}")
       end
 
-      # Logs an event emission
+      # Logs an event emission with correlation ID and duration.
       #
       # @param event_name [Symbol] The event name
       # @param payload [Hash] The event payload
-      def self.log_event(event_name, payload)
-        logger.info("Event :#{event_name} emitted with payload: #{payload.inspect}")
+      # @param event_id [String] The unique event correlation ID
+      # @param duration_ms [Float] The dispatch duration in milliseconds
+      def self.log_event(event_name, payload, event_id:, duration_ms:)
+        logger.info("[#{event_id}] Event :#{event_name} (#{duration_ms.round(1)}ms) #{payload.inspect}")
       end
 
       # Logs a validation error from a service

data/lib/servus/support/validator.rb

@@ -102,27 +102,26 @@ module Servus
         end
       end
 
-      # Validates event payload against the handler's payload schema.
+      # Validates event payload against the Event class's payload schema.
       #
-      # @param handler_class [Class] the event handler class
+      # @param event_class [Class] the Event subclass
       # @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 })
+      #   Validator.validate_event_payload!(UserCreated, { user_id: 123 })
       #
       # @api private
-      def self.validate_event_payload!(handler_class, payload)
-        schema = handler_class.payload_schema
-        enforce_schema_presence!(schema, handler_class, :require_event_payload_schema)
+      def self.validate_event_payload!(event_class, payload)
+        schema = event_class.payload_schema
+        enforce_schema_presence!(schema, event_class, :require_event_payload_schema)
         return true unless schema
 
         validate_data_against_schema!(
           payload,
           schema,
-          "Invalid payload for event :#{handler_class.event_name}"
+          "Invalid payload for event :#{event_class.event_name}"
         )
 
         true
@@ -210,7 +209,7 @@ module Servus
       # Returns the schema if present. Raises if absent and the config flag is enabled.
       #
       # @param schema [Hash, nil] the loaded schema
-      # @param klass [Class] the service or handler class
+      # @param klass [Class] the service or Event class
       # @param config_flag [Symbol] the config method to check
       # @return [Hash, nil] the schema
       # @raise [Servus::Support::Errors::SchemaRequiredError] if schema is nil and enforcement is enabled

data/lib/servus/testing/matchers.rb

@@ -12,7 +12,7 @@ module Servus
 end
 
 # Matcher for asserting event emission
-RSpec::Matchers.define :emit_event do |handler_class_or_symbol|
+RSpec::Matchers.define :emit_event do |event_class_or_symbol|
   supports_block_expectations
 
   chain :with do |payload|
@@ -30,10 +30,10 @@ RSpec::Matchers.define :emit_event do |handler_class_or_symbol|
     block.call
 
     # Determine event name
-    @event_name = if handler_class_or_symbol.is_a?(Symbol)
-                    handler_class_or_symbol
+    @event_name = if event_class_or_symbol.is_a?(Symbol)
+                    event_class_or_symbol
                   else
-                    handler_class_or_symbol.event_name
+                    event_class_or_symbol.event_name
                   end
 
     @matching_event = @captured_events.find { |e| e[:name] == @event_name }
@@ -86,7 +86,7 @@ RSpec::Matchers.define :call_service do |service_class|
   end
 end
 
-# Matcher for asserting schema presence on a service or event handler
+# Matcher for asserting schema presence on a service or Event class
 RSpec::Matchers.define :have_schema do |schema_type|
   match do |klass|
     if schema_type.to_s == 'payload'

data/lib/servus/version.rb

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

data/lib/servus.rb

@@ -29,10 +29,14 @@ require_relative 'servus/support/lockdown'
 require_relative 'servus/support/message_resolver'
 
 # Events
-require_relative 'servus/events/errors'
 require_relative 'servus/events/bus'
 require_relative 'servus/events/emitter'
-require_relative 'servus/event_handler'
+require_relative 'servus/event'
+
+# Routing
+require_relative 'servus/events/router'
+require_relative 'servus/events/invocation'
+require_relative 'servus/events/class_router'
 
 # Guards (guards.rb loads defaults based on config)
 require_relative 'servus/guard'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Sebastian Scholl
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-30 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_model_serializers
@@ -75,9 +75,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- 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/event/event_generator.rb
+- lib/generators/servus/event/templates/event.rb.erb
+- lib/generators/servus/event/templates/event_spec.rb.erb
 - lib/generators/servus/guard/guard_generator.rb
 - lib/generators/servus/guard/templates/guard.rb.erb
 - lib/generators/servus/guard/templates/guard_spec.rb.erb
@@ -89,10 +89,12 @@ files:
 - lib/servus.rb
 - lib/servus/base.rb
 - lib/servus/config.rb
-- lib/servus/event_handler.rb
+- lib/servus/event.rb
 - lib/servus/events/bus.rb
+- lib/servus/events/class_router.rb
 - lib/servus/events/emitter.rb
-- lib/servus/events/errors.rb
+- lib/servus/events/invocation.rb
+- lib/servus/events/router.rb
 - lib/servus/extensions/async/call.rb
 - lib/servus/extensions/async/errors.rb
 - lib/servus/extensions/async/ext.rb

data/lib/generators/servus/event_handler/event_handler_generator.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module Servus
-  module Generators
-    # Rails generator for creating Servus event handlers.
-    #
-    # Generates an event handler class and spec file.
-    #
-    # @example Generate an event handler
-    #   rails g servus:event_handler user_created
-    #
-    # @example Generated files
-    #   app/events/user_created_handler.rb
-    #   spec/app/events/user_created_handler_spec.rb
-    #
-    # @see https://guides.rubyonrails.org/generators.html
-    class EventHandlerGenerator < Rails::Generators::NamedBase
-      source_root File.expand_path('templates', __dir__)
-
-      class_option :no_docs, type: :boolean,
-                             default: false,
-                             desc: 'Skip documentation comments in generated files'
-
-      # Creates the event handler and spec files.
-      #
-      # @return [void]
-      def create_handler_file
-        template 'handler.rb.erb', handler_path
-        template 'handler_spec.rb.erb', handler_spec_path
-      end
-
-      private
-
-      # Returns the path for the handler file.
-      #
-      # @return [String] handler file path
-      # @api private
-      def handler_path
-        File.join(Servus.config.events_dir, "#{file_name}_handler.rb")
-      end
-
-      # Returns the path for the handler spec file.
-      #
-      # @return [String] spec file path
-      # @api private
-      def handler_spec_path
-        File.join(Servus.config.tests_dir, Servus.config.events_dir, "#{file_name}_handler_spec.rb")
-      end
-
-      # Returns the handler class name.
-      #
-      # @return [String] handler class name
-      # @api private
-      def handler_class_name
-        "#{class_name}Handler"
-      end
-    end
-  end
-end

data/lib/generators/servus/event_handler/templates/handler.rb.erb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-<%- unless options[:no_docs] -%>
-# Handles the :<%= file_name %> event by invoking configured services.
-#
-# EventHandlers subscribe to a single event and declaratively map it to one or
-# more service invocations. This provides clean separation between event emission
-# (what happened) and event handling (what to do about it).
-#
-# @example Basic usage
-#   class <%= handler_class_name %> < Servus::EventHandler
-#     handles :<%= file_name %>
-#
-#     # Invoke a service when this event fires
-#     invoke SendEmail::Service, async: true do |payload|
-#       { user_id: payload[:user_id], email: payload[:email] }
-#     end
-#   end
-#
-# @example Multiple service invocations
-#   invoke SendWelcomeEmail::Service, async: true, queue: :mailers do |payload|
-#     { user_id: payload[:user_id] }
-#   end
-#
-#   invoke TrackAnalytics::Service, async: true do |payload|
-#     { event: '<%= file_name %>', user_id: payload[:user_id] }
-#   end
-#
-# @example Conditional invocation
-#   invoke GrantRewards::Service, if: ->(payload) { payload[:premium] } do |payload|
-#     { user_id: payload[:user_id] }
-#   end
-#
-# @example With payload schema validation
-#   schema payload: {
-#     type: 'object',
-#     required: ['user_id'],
-#     properties: {
-#       user_id: { type: 'integer' },
-#       email: { type: 'string', format: 'email' }
-#     }
-#   }
-#
-# @example Emit this event from anywhere
-#   # From controllers, jobs, rake tasks, etc.
-#   <%= handler_class_name %>.emit({ user_id: 123, email: 'user@example.com' })
-#
-# Available options for `invoke`:
-# - async: true          - Invoke service asynchronously via ActiveJob
-# - queue: :queue_name   - Specify ActiveJob queue (requires async: true)
-# - if: ->(payload) {}   - Condition that must be true to invoke
-# - unless: ->(payload) {} - Condition that must be false to invoke
-#
-# @see Servus::EventHandler
-# @see Servus::Events::Bus
-<%- end -%>
-class <%= handler_class_name %> < Servus::EventHandler
-  handles :<%= file_name %>
-
-<%- unless options[:no_docs] -%>
-  # TODO: Define payload schema (optional but recommended)
-  # schema payload: {
-  #   type: 'object',
-  #   required: ['required_field'],
-  #   properties: {
-  #     required_field: { type: 'string' }
-  #   }
-  # }
-
-  # TODO: Add service invocations
-  # invoke YourService, async: true do |payload|
-  #   {
-  #     # Map event payload to service arguments
-  #     argument_name: payload[:field_name]
-  #   }
-  # end
-<%- end -%>
-  schema payload: {
-    type: 'object',
-    description: 'JSON schema for the <%= handler_class_name %> event payload',
-  }
-
-  # invoke ExampleService, async: true do |payload|
-  #   { example_arg: payload[:example_field] }
-  # end
-end

data/lib/generators/servus/event_handler/templates/handler_spec.rb.erb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-require 'rails_helper'
-
-RSpec.describe <%= handler_class_name %> do
-<%- unless options[:no_docs] -%>
-  # Test that the handler invokes the correct services with properly mapped arguments.
-  #
-  # Example test pattern:
-  #   it 'invokes YourService with correct arguments' do
-  #     expect(YourService).to receive(:call_async).with(user_id: 123)
-  #     described_class.handle({ user_id: 123, email: 'test@example.com' })
-  #   end
-  #
-  # For testing event emission from controllers/jobs:
-  #   include Servus::Testing::EventHelpers
-  #
-  #   it 'emits <%= file_name %> event' do
-  #     servus_expect_event(:<%= file_name %>)
-  #       .with_payload(hash_including(user_id: 123))
-  #       .when { YourController.new.create }
-  #   end
-
-<%- end -%>
-  let(:payload) do
-    {
-      # TODO: Add sample payload fields
-      # user_id: 123,
-      # email: 'test@example.com'
-    }
-  end
-
-<%- unless options[:no_docs] -%>
-  # TODO: Add tests for service invocations
-  # it 'invokes YourService with mapped arguments' do
-  #   expect(YourService).to receive(:call_async).with(user_id: payload[:user_id])
-  #   described_class.handle(payload)
-  # end
-
-  # TODO: Test conditional logic if using :if or :unless
-  # it 'skips invocation when condition is false' do
-  #   expect(YourService).not_to receive(:call_async)
-  #   described_class.handle(payload.merge(premium: false))
-  # end
-<%- else -%>
-  # Add your tests here
-<%- end -%>
-end