servus 0.1.3 → 0.1.5

data/lib/servus/event_handler.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Servus
+  # Base class for event handlers that map events to service invocations.
+  #
+  # EventHandler classes live in app/events/ and use a declarative DSL to
+  # subscribe to events and invoke services in response. Each handler
+  # subscribes to a single event via the `handles` method.
+  #
+  # @example Basic event handler
+  #   class UserCreatedHandler < Servus::EventHandler
+  #     handles :user_created
+  #
+  #     invoke SendWelcomeEmail::Service, async: true do |payload|
+  #       { user_id: payload[:user_id] }
+  #     end
+  #   end
+  #
+  # @see Servus::Events::Bus
+  # @see Servus::Base
+  class EventHandler
+    class << self
+      # Declares which event this handler subscribes to.
+      #
+      # This method registers the handler with the event bus and stores
+      # the event name for later reference. Each handler can only subscribe
+      # to one event.
+      #
+      # @param event_name [Symbol] the name of the event to handle
+      # @return [void]
+      # @raise [RuntimeError] if handles is called multiple times
+      #
+      # @example
+      #   class UserCreatedHandler < Servus::EventHandler
+      #     handles :user_created
+      #   end
+      def handles(event_name)
+        raise "Handler already subscribed to :#{@event_name}. Cannot subscribe to :#{event_name}" if @event_name
+
+        @event_name = event_name
+        Servus::Events::Bus.register_handler(event_name, self)
+      end
+
+      # Returns the event name this handler is subscribed to.
+      #
+      # @return [Symbol, nil] the event name or nil if not yet configured
+      attr_reader :event_name
+
+      # Declares a service invocation in response to the event.
+      #
+      # Multiple invocations can be declared for a single event. Each invocation
+      # requires a block that maps the event payload to the service's arguments.
+      #
+      # @param service_class [Class] the service class to invoke (must inherit from Servus::Base)
+      # @param options [Hash] invocation options
+      # @option options [Boolean] :async invoke the service asynchronously via call_async
+      # @option options [Symbol] :queue the queue name for async jobs
+      # @option options [Proc] :if condition that must return true for invocation
+      # @option options [Proc] :unless condition that must return false for invocation
+      # @yield [payload] block that maps event payload to service arguments
+      # @yieldparam payload [Hash] the event payload
+      # @yieldreturn [Hash] keyword arguments for the service's initialize method
+      # @return [void]
+      #
+      # @example Basic invocation
+      #   invoke SendEmail::Service do |payload|
+      #     { user_id: payload[:user_id], email: payload[:email] }
+      #   end
+      #
+      # @example Async invocation with queue
+      #   invoke SendEmail::Service, async: true, queue: :mailers do |payload|
+      #     { user_id: payload[:user_id] }
+      #   end
+      #
+      # @example Conditional invocation
+      #   invoke GrantRewards::Service, if: ->(p) { p[:premium] } do |payload|
+      #     { user_id: payload[:user_id] }
+      #   end
+      def invoke(service_class, options = {}, &block)
+        raise ArgumentError, 'Block required for payload mapping' unless block
+
+        @invocations ||= []
+        @invocations << {
+          service_class: service_class,
+          options: options,
+          mapper: block
+        }
+      end
+
+      # Returns all service invocations declared for this handler.
+      #
+      # @return [Array<Hash>] array of invocation configurations
+      def invocations
+        @invocations || []
+      end
+
+      # Defines the JSON schema for validating event payloads.
+      #
+      # @param payload [Hash, nil] JSON schema for validating event payloads
+      # @return [void]
+      #
+      # @example
+      #   class UserCreatedHandler < Servus::EventHandler
+      #     handles :user_created
+      #
+      #     schema payload: {
+      #       type: 'object',
+      #       required: ['user_id', 'email'],
+      #       properties: {
+      #         user_id: { type: 'integer' },
+      #         email: { type: 'string', format: 'email' }
+      #       }
+      #     }
+      #   end
+      def schema(payload: nil)
+        @payload_schema = payload.with_indifferent_access if payload
+      end
+
+      # Returns the payload schema.
+      #
+      # @return [Hash, nil] the payload schema or nil if not defined
+      # @api private
+      attr_reader :payload_schema
+
+      # Emits the event this handler is subscribed to.
+      #
+      # Provides a type-safe, discoverable way to emit events from anywhere in
+      # the application (controllers, jobs, rake tasks) without creating a service.
+      #
+      # @param payload [Hash] the event payload
+      # @return [void]
+      # @raise [RuntimeError] if no event configured via `handles`
+      #
+      # @example Emit from controller
+      #   class UsersController
+      #     def create
+      #       user = User.create!(params)
+      #       UserCreatedHandler.emit({ user_id: user.id, email: user.email })
+      #       redirect_to user
+      #     end
+      #   end
+      #
+      # @example Emit from background job
+      #   class ProcessDataJob
+      #     def perform(data_id)
+      #       result = process_data(data_id)
+      #       DataProcessedHandler.emit({ data_id: data_id, status: result })
+      #     end
+      #   end
+      def emit(payload)
+        raise 'No event configured. Call handles :event_name first.' unless @event_name
+
+        Servus::Support::Validator.validate_event_payload!(self, payload)
+
+        Servus::Events::Bus.emit(@event_name, payload)
+      end
+
+      # Handles an event by invoking all configured services.
+      #
+      # Iterates through all declared invocations, evaluates conditions,
+      # maps the payload to service arguments, and invokes each service.
+      #
+      # @param payload [Hash] the event payload
+      # @return [Array<Servus::Support::Response>] results from all invoked services
+      #
+      # @example
+      #   UserCreatedHandler.handle({ user_id: 123, email: 'user@example.com' })
+      def handle(payload)
+        invocations.map do |invocation|
+          next unless should_invoke?(payload, invocation[:options])
+
+          invoke_service(invocation, payload)
+        end.compact
+      end
+
+      # Validates that all registered handlers subscribe to events that are actually emitted by services.
+      #
+      # Checks all handlers against all service emissions and raises an error if any
+      # handler subscribes to a non-existent event. Helps catch typos and orphaned handlers.
+      #
+      # Respects the `Servus.config.strict_event_validation` setting - skips validation if false.
+      #
+      # @return [void]
+      # @raise [Servus::Events::OrphanedHandlerError] if a handler subscribes to a non-existent event
+      #
+      # @example
+      #   Servus::EventHandler.validate_all_handlers!
+      def validate_all_handlers!
+        return unless Servus.config.strict_event_validation
+
+        emitted_events = collect_emitted_events
+        orphaned       = find_orphaned_handlers(emitted_events)
+
+        return if orphaned.empty?
+
+        raise Servus::Events::OrphanedHandlerError,
+              "Handler(s) subscribe to non-existent events:\n" \
+              "#{orphaned.map { |h| "  - #{h[:handler]} subscribes to :#{h[:event]}" }.join("\n")}"
+      end
+
+      private
+
+      # Collects all event names that are emitted by services.
+      #
+      # @return [Set<Symbol>] set of all emitted event names
+      # @api private
+      def collect_emitted_events
+        events = Set.new
+
+        ObjectSpace.each_object(Class)
+                   .select { |klass| klass < Servus::Base }
+                   .each do |service_class|
+          service_class.event_emissions.each_value do |emissions|
+            emissions.each { |emission| events << emission[:event_name] }
+          end
+        end
+
+        events
+      end
+
+      # Finds handlers that subscribe to events not emitted by any service.
+      #
+      # @param emitted_events [Set<Symbol>] set of all emitted event names
+      # @return [Array<Hash>] array of orphaned handler info
+      # @api private
+      def find_orphaned_handlers(emitted_events)
+        orphaned = []
+
+        ObjectSpace.each_object(Class)
+                   .select { |klass| klass < Servus::EventHandler && klass != Servus::EventHandler }
+                   .each do |handler_class|
+          next unless handler_class.event_name
+          next if emitted_events.include?(handler_class.event_name)
+
+          orphaned << { handler: handler_class.name, event: handler_class.event_name }
+        end
+
+        orphaned
+      end
+
+      # Invokes a single service with the mapped payload.
+      #
+      # @param invocation [Hash] the invocation configuration
+      # @param payload [Hash] the event payload
+      # @return [Servus::Support::Response] the service result
+      # @api private
+      def invoke_service(invocation, payload)
+        service_kwargs = invocation[:mapper].call(payload)
+
+        async = invocation.dig(:options, :async) || false
+        queue = invocation.dig(:options, :queue) || nil
+
+        if async
+          service_kwargs = service_kwargs.merge(queue: queue) if queue
+          invocation[:service_class].call_async(**service_kwargs)
+        else
+          invocation[:service_class].call(**service_kwargs)
+        end
+      end
+
+      # Checks if a service should be invoked based on conditions.
+      #
+      # @param payload [Hash] the event payload
+      # @param options [Hash] the invocation options
+      # @return [Boolean] true if the service should be invoked
+      # @api private
+      def should_invoke?(payload, options)
+        return false if options[:if] && !options[:if].call(payload)
+        return false if options[:unless]&.call(payload)
+
+        true
+      end
+    end
+  end
+end

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
+
+      # Instance methods for emitting events during service execution
+      private
+
+      # 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
+
+      # 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/extensions/async/call.rb

@@ -3,28 +3,60 @@
 module Servus
   module Extensions
     module Async
-      # Calls the service asynchronously using AsyncCallerJob.
+      # Provides asynchronous service execution via ActiveJob.
       #
-      # Supports all standard ActiveJob scheduling and routing options:
-      #   - wait:        <ActiveSupport::Duration>   (e.g., 5.minutes)
-      #   - wait_until:  <Time>                      (e.g., 2.hours.from_now)
-      #   - queue:       <Symbol/String>             (e.g., :critical, 'low_priority')
-      #   - priority:    <Integer>                   (depends on adapter support)
-      #   - retry:       <Boolean>                   (custom control for job retry)
-      #   - job_options: <Hash>                      (extra options, merged in)
-      #
-      # Example:
-      #   call_async(
-      #     wait: 10.minutes,
-      #     queue: :low_priority,
-      #     priority: 20,
-      #     job_options: { tags: ['user_graduation'] },
-      #     user_id: current_user.id
-      #   )
+      # This module extends {Servus::Base} with the {#call_async} method, enabling
+      # services to be executed in background jobs. Requires ActiveJob to be loaded.
       #
+      # @see Call#call_async
       module Call
-        # @param args [Hash] The arguments to pass to the service and job options.
+        # Enqueues the service for asynchronous execution via ActiveJob.
+        #
+        # This method schedules the service to run in a background job, supporting
+        # all standard ActiveJob options for scheduling, queue routing, and priority.
+        #
+        # Service arguments are passed as keyword arguments alongside job configuration.
+        # Job-specific options are extracted and the remaining arguments are passed
+        # to the service's initialize method.
+        #
+        # @param args [Hash] combined service arguments and job configuration options
+        # @option args [ActiveSupport::Duration] :wait delay before execution (e.g., 5.minutes)
+        # @option args [Time] :wait_until specific time to execute (e.g., 2.hours.from_now)
+        # @option args [Symbol, String] :queue queue name (e.g., :low_priority)
+        # @option args [Integer] :priority job priority (adapter-dependent)
+        # @option args [Hash] :job_options additional ActiveJob options
+        #
         # @return [void]
+        # @raise [Servus::Extensions::Async::Errors::JobEnqueueError] if job enqueueing fails
+        #
+        # @example Basic async execution
+        #   Services::SendEmail::Service.call_async(
+        #     user_id: 123,
+        #     template: :welcome
+        #   )
+        #
+        # @example With delay
+        #   Services::SendReminder::Service.call_async(
+        #     wait: 1.day,
+        #     user_id: 123
+        #   )
+        #
+        # @example With queue and priority
+        #   Services::ProcessPayment::Service.call_async(
+        #     queue: :critical,
+        #     priority: 10,
+        #     order_id: 456
+        #   )
+        #
+        # @example With custom job options
+        #   Services::GenerateReport::Service.call_async(
+        #     wait_until: Date.tomorrow.beginning_of_day,
+        #     job_options: { tags: ['reports', 'daily'] },
+        #     report_type: :sales
+        #   )
+        #
+        # @note Only available when ActiveJob is loaded (typically in Rails applications)
+        # @see Servus::Base.call
         def call_async(**args)
           # Extract ActiveJob configuration options
           job_options = args.slice(:wait, :wait_until, :queue, :priority)