servus 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e468137fc40c9d2f18214dea55b9c3fc6211e5479e73f5b0917ed168d116a2f
-  data.tar.gz: 5390b065cb3478d837cbd90047a7f8facaaf33273b0e2aa4d459167343354d8d
+  metadata.gz: 2f382ed3d92dd577c93965ae207c00d28cac6dfddf452cf22fb5dafcd69d56eb
+  data.tar.gz: f5a4394a33f5a3061d3c5746fdd058eb457cb29baa2f0adb9cc97c0679f5c158
 SHA512:
-  metadata.gz: 20e5b65a0cd82207a0c494b76e21d0562ce41ca27394b418e7d6921b841c4f47d4f8384f157146195eea713f1af3d28d09b81c210fd7f8a5041b13f8464d66a2
-  data.tar.gz: 52f7ca40905dc890fa6850cf87b8394471a94607749457aaeb4784c4524315fd769e40daa4322aae12b5bd84eb9282524a90836bab8a31ab9abfe01d021211a7
+  metadata.gz: 5ccb1adc1b0bd4b7ff9f8b754571be541bbf7e3b9246746fe73c9e1259ad4b6f6e3a5a4d6c07d3b9f30cb8ddda94dfc2cad7c78fb6dc31fb17440c1d3a19b6be
+  data.tar.gz: 0107e7e4d770913a5e86de5c496791e6311c913dc6b2bdad03417b78a2e66be6d50c2fc5d213f87b51162ac4a15d3c6c9dcb9b323267a9db9d0b222099f60245

data/lib/generators/servus/event/event_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Servus
+  module Generators
+    # Rails generator for creating Servus event classes.
+    #
+    # Generates an event class and spec file. The event name is inferred
+    # from the class name — no explicit +event_name+ call needed.
+    #
+    # @example Generate an event
+    #   rails g servus:event referral_verified
+    #
+    # @example Generated files
+    #   app/events/referral_verified.rb
+    #   spec/app/events/referral_verified_spec.rb
+    #
+    # @see https://guides.rubyonrails.org/generators.html
+    class EventGenerator < 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 class and spec files.
+      #
+      # @return [void]
+      def create_event_file
+        template 'event.rb.erb', event_path
+        template 'event_spec.rb.erb', event_spec_path
+      end
+
+      private
+
+      # @return [String] event file path
+      # @api private
+      def event_path
+        File.join(Servus.config.events_dir, "#{file_name}_event.rb")
+      end
+
+      # @return [String] spec file path
+      # @api private
+      def event_spec_path
+        File.join(Servus.config.tests_dir, Servus.config.events_dir, "#{file_name}_event_spec.rb")
+      end
+
+      # @return [String] event class name (e.g. "ReferralVerifiedEvent")
+      # @api private
+      def event_class_name
+        "#{class_name}Event"
+      end
+    end
+  end
+end

data/lib/generators/servus/event/templates/event.rb.erb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+<%- unless options[:no_docs] -%>
+# Defines the :<%= file_name %> event.
+#
+# Event classes declare the contract (schema) for an event and optionally
+# wire up service invocations that run when the event fires. The event
+# name is inferred from the class name.
+#
+# @example Emit this event from anywhere
+#   <%= event_class_name %>.emit({ user_id: 123 })
+#
+# @example Invoke a service when this event fires
+#   invoke SendEmail::Service, async: true do |payload|
+#     { user_id: payload[:user_id] }
+#   end
+#
+# @example Pass full payload through (no mapper block)
+#   invoke AuditLogger::Service, async: true
+#
+# @example Conditional invocation
+#   invoke GrantRewards::Service, if: ->(payload) { payload[:premium] } do |payload|
+#     { user_id: payload[:user_id] }
+#   end
+#
+# 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::Event
+# @see Servus::Events::Bus
+<%- end -%>
+class <%= event_class_name %> < Servus::Event
+  schema payload: {
+    type: 'object',
+    description: '<%= event_class_name %> event payload',
+  }
+
+  # invoke YourService, async: true do |payload|
+  #   { example_arg: payload[:example_field] }
+  # end
+end

data/lib/generators/servus/event/templates/event_spec.rb.erb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= event_class_name %> do
+  let(:payload) do
+    {
+      # TODO: Add sample payload fields
+    }
+  end
+
+<%- unless options[:no_docs] -%>
+  # TODO: Add tests for service invocations
+  # it 'invokes YourService with mapped arguments' do
+  #   expect { described_class.emit(payload) }
+  #     .to emit_event(:<%= file_name %>)
+  #     .with(hash_including(expected_field: 'value'))
+  # end
+<%- end -%>
+end

data/lib/servus/config.rb

@@ -22,7 +22,7 @@ module Servus
     # @return [String] the schemas directory path
     attr_accessor :schemas_dir
 
-    # The directory where event handlers are located.
+    # The directory where Event classes are located.
     #
     # Defaults to `Rails.root/app/events` in Rails applications.
     #
@@ -36,14 +36,6 @@ module Servus
     # @return [String] the services directory path
     attr_accessor :services_dir
 
-    # Whether to validate that all event handlers subscribe to events that are actually emitted by services.
-    #
-    # When enabled, raises an error on boot if handlers subscribe to non-existent events.
-    # Helps catch typos and orphaned handlers.
-    #
-    # @return [Boolean] true to validate, false to skip validation
-    attr_accessor :strict_event_validation
-
     # The directory where guard classes are located.
     #
     # Defaults to `Rails.root/app/guards` in Rails applications.
@@ -82,14 +74,28 @@ module Servus
     # @return [Boolean] true to require result schemas, false to allow schema-less services
     attr_accessor :require_service_result_schema
 
-    # Whether to require all event handlers to define a payload schema.
+    # Whether to require all event classes to define a payload schema.
     #
     # When enabled, raises {Servus::Support::Errors::SchemaRequiredError} when
-    # an event handler validates a payload without a payload schema defined.
+    # an event validates a payload without a payload schema defined.
     #
-    # @return [Boolean] true to require payload schemas, false to allow schema-less handlers
+    # @return [Boolean] true to require payload schemas, false to allow schema-less events
     attr_accessor :require_event_payload_schema
 
+    # The ordered list of routers that resolve invocations for events.
+    #
+    # The Bus iterates routers in order, collects invocations, deduplicates
+    # by key (first wins), and executes. Defaults to +[ClassRouter.new]+
+    # which reads +invoke+ declarations from Event classes.
+    #
+    # @return [Array<Servus::Events::Router>]
+    attr_writer :routers
+
+    # @return [Array<Servus::Events::Router>]
+    def routers
+      @routers || [Servus::Events::ClassRouter.new]
+    end
+
     # Whether external instantiation of services is blocked and instance
     # `#call` methods are automatically privatized.
     #
@@ -121,7 +127,6 @@ module Servus
     # @api private
     def initialize
       set_default_directories
-      @strict_event_validation          = true
       @include_default_guards           = true
       @lockdown_enabled                 = true
       @require_service_arguments_schema = false

data/lib/servus/event.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Servus
+  # Base class for event definitions.
+  #
+  # Event classes live in app/events/ and serve three purposes:
+  #
+  # 1. *Contract* — declares the event exists and defines its name
+  # 2. *Validator* — schema enforcement on any emission
+  # 3. *Declarative routing* — optional +invoke+ declarations
+  #
+  # The event name can be set explicitly via +event_name+ or inferred
+  # from the class name (e.g. +OrderPlaced+ becomes +:order_placed+).
+  # Call +ensure_registered!+ to trigger inference for classes that
+  # don't declare an explicit name.
+  #
+  # @example Event with explicit name and invoke declarations
+  #   class UserCreated < Servus::Event
+  #     event_name :user_created
+  #
+  #     schema payload: { type: 'object', required: ['user_id'] }
+  #
+  #     invoke SendWelcomeEmail::Service, async: true do |payload|
+  #       { user_id: payload[:user_id] }
+  #     end
+  #   end
+  #
+  # @example Event with inferred name (no invoke — schema-only contract)
+  #   class OrderPlaced < Servus::Event
+  #     schema payload: { type: 'object', required: ['order_id'] }
+  #   end
+  #
+  # @example Event that passes full payload through (no mapper block)
+  #   class AuditLogCreated < Servus::Event
+  #     event_name :audit_log_created
+  #
+  #     invoke AuditLogger::Service, async: true
+  #   end
+  #
+  # @see Servus::Events::Bus
+  # @see Servus::Events::Router
+  # @see Servus::Base
+  class Event
+    class << self
+      # Declares or returns the event name.
+      #
+      # When called with an argument, sets the event name and registers
+      # with the Bus. When called without arguments, returns the current
+      # event name.
+      #
+      # If never called explicitly, use +ensure_registered!+ to infer
+      # the name from the class name.
+      #
+      # @overload event_name(name)
+      #   @param name [Symbol] the event name to register
+      #   @return [void]
+      #   @raise [RuntimeError] if called twice with different names
+      #
+      # @overload event_name
+      #   @return [Symbol, nil] the event name or nil if not configured
+      #
+      # @example Explicit name
+      #   class UserCreated < Servus::Event
+      #     event_name :user_created
+      #   end
+      #
+      # @example Inferred name (via ensure_registered!)
+      #   class OrderPlaced < Servus::Event; end
+      #   OrderPlaced.ensure_registered!
+      #   OrderPlaced.event_name # => :order_placed
+      def event_name(name = nil)
+        return @event_name if name.nil?
+
+        raise "Event already subscribed to :#{@event_name}. Cannot subscribe to :#{name}" if @event_name
+
+        @event_name = name
+        Servus::Events::Bus.register_event(name, self)
+      end
+
+      # Infers and registers the event name from the class name if not
+      # already set explicitly. Safe to call multiple times — does
+      # nothing if already registered. Skips anonymous classes.
+      #
+      # @return [void]
+      def ensure_registered!
+        return if @event_name
+        return if name.nil?
+
+        event_name(name.demodulize.underscore.to_sym)
+      end
+
+      # 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)
+        @invocations ||= []
+        @invocations << {
+          service_class: service_class,
+          options: options,
+          mapper: block || ->(payload) { payload }
+        }
+      end
+
+      # Returns all service invocations declared for this event.
+      #
+      # @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 UserCreated < Servus::Event
+      #     event_name :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 this event via the Bus.
+      #
+      # 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 name configured
+      #
+      # @example Emit from controller
+      #   class UsersController
+      #     def create
+      #       user = User.create!(params)
+      #       UserCreated.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)
+      #       DataProcessed.emit({ data_id: data_id, status: result })
+      #     end
+      #   end
+      def emit(payload)
+        raise 'No event configured. Call event_name :name first.' unless @event_name
+
+        Servus::Support::Validator.validate_event_payload!(self, payload)
+
+        Servus::Events::Bus.emit(@event_name, payload)
+      end
+
+      # Returns Invocation objects for the given payload, with conditions
+      # already evaluated. This is what routers call to resolve actions.
+      #
+      # @param payload [Hash] the event payload
+      # @return [Array<Servus::Events::Invocation>] invocations that passed conditions
+      def invocations_for(payload)
+        invocations.filter_map do |inv|
+          next unless should_invoke?(payload, inv[:options])
+
+          Servus::Events::Invocation.new(
+            service: inv[:service_class],
+            params: inv[:mapper].call(payload),
+            options: inv[:options].except(:if, :unless)
+          )
+        end
+      end
+
+      # Handles an event by resolving and executing all invocations.
+      #
+      # @param payload [Hash] the event payload
+      # @return [Array] results from all invoked services
+      def handle(payload)
+        invocations_for(payload).map(&:execute)
+      end
+
+      private
+
+      # @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

@@ -2,93 +2,89 @@
 
 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 the Event class registered for the given name.
         #
-        # 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
+        # @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.
@@ -120,7 +116,26 @@ module Servus
           end
         end
 
-        # Clears all registered handlers and unsubscribes from notifications.
+        # 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 events.
         #
         # Useful for testing and development mode reloading.
         #
@@ -129,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.