servus 0.3.0 → 0.5.0

data/lib/servus/events/bus.rb

@@ -2,96 +2,140 @@
 
 module Servus
   module Events
-    # Thread-safe event bus for registering and dispatching event handlers.
+    # Central event bus for registering Event classes and dispatching
+    # events through configured routers.
     #
-    # 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.
+    # The Bus maintains a registry mapping event names to their Event
+    # class definitions (one-to-one). On +emit+, it delegates to the
+    # configured routers to resolve invocations, deduplicates by key,
+    # and executes. ActiveSupport::Notifications wraps the dispatch
+    # cycle for the +subscribe_all+ hook (e.g. forwarding to Eventus).
     #
-    # 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
+    # @example Registering an event class
+    #   class UserCreated < Servus::Event
+    #     event_name :user_created
     #   end
+    #   # Registration happens automatically via the event_name DSL
     #
-    #   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 Emitting an event
+    #   Bus.emit(:user_created, { user_id: 123 })
     #
-    # @example Instrumentation in logs
-    #   Bus.emit(:user_created, user_id: 123)
-    #   # Rails log: servus.events.user_created (1.2ms) {:user_id=>123}
+    # @example Forwarding all events to an external system
+    #   Bus.subscribe_all do |event_name, payload, started_at:, **|
+    #     ExternalForwarder.perform_later(event: event_name, payload:)
+    #   end
     #
-    # @see Servus::EventHandler
+    # @see Servus::Event
+    # @see Servus::Events::Router
+    # @see Servus::Events::ClassRouter
     class Bus
       class << self
-        # Registers a handler class for a specific event.
+        # Registers an Event class for a specific event name.
         #
-        # 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.
+        # Each event name maps to exactly one Event class. Attempting to
+        # register a second class for the same name raises an error.
         #
-        # Handlers are typically registered automatically when EventHandler
-        # classes are loaded at boot time via the `handles` DSL method.
+        # Event classes are typically registered automatically at boot time
+        # via the +event_name+ DSL method or +ensure_registered!+.
         #
-        # @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
+        # @param name [Symbol] the event name
+        # @param event_class [Class] the Event subclass to register
+        # @return [void]
+        # @raise [RuntimeError] if the event name is already registered
         #
         # @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)
+        #   Bus.register_event(:user_created, UserCreated)
+        def register_event(name, event_class)
+          if events.key?(name)
+            raise "Event :#{name} is already registered to #{events[name]}. Cannot register #{event_class}"
           end
 
-          # Store subscription for cleanup
-          subscriptions[event_name] ||= []
-          subscriptions[event_name] << subscription
+          events[name] = event_class
         end
 
-        # Retrieves all registered handlers for a specific event.
-        #
-        # Returns a duplicate array to prevent external modification of the
-        # internal handler registry.
+        # Returns the Event class registered for the given name.
         #
-        # @param event_name [Symbol] the name of the event
-        # @return [Array<Class>] array of handler classes registered for this event
+        # @param name [Symbol] the event name
+        # @return [Class, nil] the Event class or nil if not registered
         #
         # @example
-        #   handlers = Bus.handlers_for(:user_created)
-        #   handlers.each { |handler| handler.handle(payload) }
-        def handlers_for(event_name)
-          (handlers[event_name] || []).dup
+        #   event_class = Bus.event_for(:user_created)
+        #   event_class.invocations_for(payload)
+        def event_for(name)
+          events[name]
         end
 
-        # Emits an event to all registered handlers with instrumentation.
+        # Emits an event through the configured routers.
         #
-        # Uses ActiveSupport::Notifications to instrument the event, providing
-        # automatic timing and logging. The event will appear in Rails logs
-        # with duration and payload information.
+        # Collects invocations from all routers (in config array order),
+        # deduplicates by key (first wins), and executes each. The entire
+        # dispatch is wrapped in ActiveSupport::Notifications so that
+        # +subscribe_all+ listeners receive timing information.
         #
         # @param event_name [Symbol] the name of the event to emit
-        # @param payload [Hash] the event payload to pass to handlers
+        # @param payload [Hash] the event payload
         # @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)
+          ActiveSupport::Notifications.instrument(notification_name(event_name), payload) do
+            resolve_invocations(event_name, payload)
+              .uniq(&:key)
+              .each(&:execute)
+          end
+        end
+
+        # Subscribes to all Servus event emissions.
+        #
+        # Yields the clean event name and payload as positional args, plus
+        # +started_at+, +finished_at+, and +id+ as keyword args.
+        # Returns the subscription for manual unsubscribe.
+        #
+        # @yield [event_name, payload, started_at:, finished_at:, id:]
+        # @yieldparam event_name [Symbol] the event name
+        # @yieldparam payload [Hash] the event payload
+        # @yieldparam started_at [Time] when the event was emitted
+        # @yieldparam finished_at [Time] when the instrumented block completed
+        # @yieldparam id [String] unique notification ID
+        # @return [Object] the ActiveSupport::Notifications subscription
+        #
+        # @example Forward all events to an external system
+        #   Servus::Events::Bus.subscribe_all do |event_name, payload, started_at:, **|
+        #     EventusForwardJob.perform_later(
+        #       event: event_name.to_s,
+        #       payload: payload.as_json,
+        #       occurred_at: started_at.utc.iso8601(6)
+        #     )
+        #   end
+        def subscribe_all(&block)
+          ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, started, finished, id, payload|
+            event_name = name.delete_prefix('servus.events.').to_sym
+            block.call(event_name, payload, started_at: started, finished_at: finished, id: id)
+          end
+        end
+
+        # Installs the internal event logger. Called once at boot via
+        # the Railtie. Logs every event emission with its AS::Notifications
+        # correlation ID and dispatch duration.
+        #
+        # Multiple +subscribe_all+ subscriptions coexist — the app can
+        # add its own (e.g. for Eventus forwarding) independently.
+        #
+        # @return [void]
+        def enable_logging!
+          return if @logging_enabled
+
+          subscribe_all do |event_name, payload, **meta|
+            duration_ms = (meta[:finished_at] - meta[:started_at]) * 1000
+            Servus::Support::Logger.log_event(event_name, payload, event_id: meta[:id], duration_ms:)
+          end
+
+          @logging_enabled = true
         end
 
-        # Clears all registered handlers and unsubscribes from notifications.
+        # Clears all registered events.
         #
         # Useful for testing and development mode reloading.
         #
@@ -100,28 +144,23 @@ module Servus
         # @example
         #   Bus.clear
         def clear
-          subscriptions.values.flatten.each do |subscription|
-            ActiveSupport::Notifications.unsubscribe(subscription)
-          end
-
-          @handlers = nil
-          @subscriptions = nil
+          @events = nil
         end
 
         private
 
-        # Hash storing event handlers.
+        # Collects invocations from all configured routers.
         #
-        # @return [Hash] hash mapping event names to handler arrays
-        def handlers
-          @handlers ||= {}
+        # @param event_name [Symbol] the event name
+        # @param payload [Hash] the event payload
+        # @return [Array<Servus::Events::Invocation>]
+        def resolve_invocations(event_name, payload)
+          Servus.config.routers.flat_map { |router| router.resolve(event_name, payload) }
         end
 
-        # Hash storing ActiveSupport::Notifications subscriptions.
-        #
-        # @return [Hash] hash mapping event names to subscription objects
-        def subscriptions
-          @subscriptions ||= {}
+        # @return [Hash{Symbol => Class}] event name to Event class mapping
+        def events
+          @events ||= {}
         end
 
         # Converts an event name to a namespaced notification name.

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!]
 
@@ -127,6 +127,7 @@ module Servus
       def emit_events_for(trigger, result)
         self.class.emissions_for(trigger).each do |emission|
           payload = build_event_payload(emission, result)
+          validate_event_payload!(emission[:event_name], payload)
           Servus::Events::Bus.emit(emission[:event_name], payload)
         end
       end
@@ -134,6 +135,20 @@ module Servus
       # Instance methods for emitting events during service execution
       private
 
+      # 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
+      # @return [void]
+      # @raise [Servus::Support::Errors::ValidationError] if payload fails validation
+      # @api private
+      def validate_event_payload!(event_name, payload)
+        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.
       #
       # @param emission [Hash] the emission configuration

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/guard.rb

@@ -19,7 +19,7 @@ module Servus
   #       }
   #     end
   #
-  #     def test(account:, amount:)
+  #     def test
   #       account.balance >= amount
   #     end
   #   end
@@ -52,7 +52,7 @@ module Servus
       #   Servus::Guard.execute!(EnsurePositive, amount: -10) # throws :guard_failure
       def execute!(guard_class, **)
         guard = guard_class.new(**)
-        return if guard.test(**)
+        return if guard.test
 
         throw(:guard_failure, guard.error)
       end
@@ -69,7 +69,7 @@ module Servus
       #   Servus::Guard.execute?(EnsurePositive, amount: 100) # => true
       #   Servus::Guard.execute?(EnsurePositive, amount: -10) # => false
       def execute?(guard_class, **)
-        guard_class.new(**).test(**)
+        guard_class.new(**).test
       end
 
       # Declares the HTTP status code for API responses.
@@ -218,14 +218,15 @@ module Servus
 
     # Tests whether the guard passes.
     #
-    # Subclasses must implement this method with explicit keyword arguments
-    # that define the guard's contract.
+    # Subclasses must implement this zero-argument method. Arguments passed
+    # to `new` are stored as `@kwargs` and exposed via `method_missing`, so
+    # `test` reads them directly off the instance.
     #
     # @return [Boolean] true if the guard passes, false otherwise
     # @raise [NotImplementedError] if not implemented by subclass
     #
     # @example
-    #   def test(account:, amount:)
+    #   def test
     #     account.balance >= amount
     #   end
     def test

data/lib/servus/guards/falsey_guard.rb

@@ -24,10 +24,10 @@ module Servus
 
       # Tests whether all specified attributes are falsey.
       #
-      # @param on [Object] the object to check
-      # @param check [Symbol, Array<Symbol>] attribute(s) to verify
+      # Reads `on` and `check` from the kwargs stored at initialization.
+      #
       # @return [Boolean] true if all attributes are falsey
-      def test(on:, check:)
+      def test
         Array(check).all? { |attr| !on.public_send(attr) }
       end
 

data/lib/servus/guards/presence_guard.rb

@@ -36,12 +36,12 @@ module Servus
       # Tests whether all provided values are present.
       #
       # A value is considered present if it is not nil and not empty
-      # (for values that respond to empty?).
+      # (for values that respond to empty?). Reads all values from the
+      # kwargs stored at initialization.
       #
-      # @param values [Hash] keyword arguments to validate
       # @return [Boolean] true if all values are present
-      def test(**values)
-        values.all? { |_, value| present?(value) }
+      def test
+        kwargs.all? { |_, value| present?(value) }
       end
 
       private

data/lib/servus/guards/state_guard.rb

@@ -24,12 +24,11 @@ module Servus
 
       # Tests whether the attribute matches the expected value(s).
       #
-      # @param on [Object] the object to check
-      # @param check [Symbol] the attribute to verify
-      # @param is [Object, Array] expected value(s) - passes if attribute matches any
+      # Reads `on`, `check`, and `is` from the kwargs stored at initialization.
+      #
       # @return [Boolean] true if attribute matches expected value(s)
-      def test(on:, check:, is:) # rubocop:disable Naming/MethodParameterName
-        Array(is).include?(on.public_send(check))
+      def test
+        Array(kwargs[:is]).include?(on.public_send(check))
       end
 
       private

data/lib/servus/guards/truthy_guard.rb

@@ -24,10 +24,10 @@ module Servus
 
       # Tests whether all specified attributes are truthy.
       #
-      # @param on [Object] the object to check
-      # @param check [Symbol, Array<Symbol>] attribute(s) to verify
+      # Reads `on` and `check` from the kwargs stored at initialization.
+      #
       # @return [Boolean] true if all attributes are truthy
-      def test(on:, check:)
+      def test
         Array(check).all? { |attr| !!on.public_send(attr) }
       end
 

data/lib/servus/helpers/controller_helpers.rb

@@ -39,6 +39,46 @@ module Servus
         render_service_error(@result.error) unless @result.success?
       end
 
+      # Executes a service and returns its data on success, raising the
+      # failure's error otherwise.
+      #
+      # The bang counterpart to {#run_service}. Use it outside a standard
+      # controller render flow — inside background logic, callbacks, or any
+      # place where a failure should propagate as an exception rather than be
+      # rendered as JSON.
+      #
+      # Inside a service's `#call` method, use {Servus::Base#call!} instead —
+      # it preserves the failure Response for the outer service's caller rather
+      # than raising.
+      #
+      # Mirrors {#run_service}: stores the full Response in @result so views
+      # and downstream helpers can reach for it the same way, then returns the
+      # data on success or raises on failure. The only behavioural difference
+      # between the two is raise-vs-render on failure.
+      #
+      # Sugar over:
+      #
+      #   @result = Service.call(**params)
+      #   raise @result.error unless @result.success?
+      #   data = @result.data
+      #
+      # @example From a rake task
+      #   data = run_service!(Treasury::Reconcile::Service, date: Date.current)
+      #
+      # @param klass [Class<Servus::Base>] service class to execute
+      # @param params [Hash] keyword arguments to pass to the service
+      # @return [Servus::Support::DataObject, Object] the service's data on success
+      # @raise [Servus::Support::Errors::ServiceError] the failure's error otherwise
+      #
+      # @see #run_service
+      # @see Servus::Base#call!
+      def run_service!(klass, **params)
+        @result = klass.call(**params)
+        return @result.data if @result.success?
+
+        raise @result.error
+      end
+
       # Renders a service error as a JSON response.
       #
       # Uses error.http_status for the response status code and