servus 0.6.0 → 1.0.0

data/lib/servus/event.rb

@@ -20,7 +20,7 @@ module Servus
   #
   #     schema payload: { type: 'object', required: ['user_id'] }
   #
-  #     invoke SendWelcomeEmail::Service, async: true do |payload|
+  #     enqueue SendWelcomeEmail::Service do |payload|
   #       { user_id: payload[:user_id] }
   #     end
   #   end
@@ -34,13 +34,49 @@ module Servus
   #   class AuditLogCreated < Servus::Event
   #     event_name :audit_log_created
   #
-  #     invoke AuditLogger::Service, async: true
+  #     enqueue AuditLogger::Service
   #   end
   #
   # @see Servus::Events::Bus
   # @see Servus::Events::Router
   # @see Servus::Base
   class Event
+    extend Servus::Schema::Declaration
+
+    # @!method self.schema(payload: nil)
+    #   Declares the JSON schema for this event's payload.
+    #
+    #   The payload is validated on every {Servus::Event.emit}. Schemas may
+    #   reference shared fragments registered with {Servus::Schema.register};
+    #   refs are resolved on first read.
+    #
+    #   Omitting the keyword leaves any schema declared earlier — or by a
+    #   superclass — in place. Passing it explicitly as +nil+ raises.
+    #
+    #   @param payload [Hash] JSON schema for the event payload
+    #   @return [void]
+    #   @raise [ArgumentError] on an unknown keyword or an explicit nil
+    #
+    #   @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
+    #
+    #   @see Servus::Schema
+    #
+    # @!method self.payload_schema
+    #   @return [Hash, nil] the compiled payload schema
+    declare_schemas :payload
+
     class << self
       # Declares or returns the event name.
       #
@@ -89,37 +125,50 @@ module Servus
         event_name(name.demodulize.underscore.to_sym)
       end
 
-      # Declares a service invocation in response to the event.
+      # Declares a service to enqueue 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.
+      # An event can declare as many services as it needs; each is enqueued
+      # independently when the event fires. The block maps the event payload to
+      # the service's keyword arguments — without one, the full payload is passed
+      # through.
       #
-      # @param service_class [Class] the service class to invoke (must inherit from Servus::Base)
+      # Invocation is always asynchronous. A reaction that ran inline would put
+      # its latency and its failures back into the emitting service, which is
+      # what events exist to avoid. This requires ActiveJob; see
+      # {Servus::Events::Errors::AsyncBackendMissingError}.
+      #
+      # @param service_class [Class] the service to enqueue (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
+      # @option options [Symbol] :queue the queue to route the job to
+      # @option options [ActiveSupport::Duration] :wait delay before the job runs
+      # @option options [Time] :wait_until absolute time to run the job
+      # @option options [Integer] :priority job priority (adapter-dependent)
+      # @option options [Hash] :job_options additional ActiveJob options
+      # @option options [Proc] :if condition that must return true to enqueue
+      # @option options [Proc] :unless condition that must return false to enqueue
       # @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]
+      # @raise [ArgumentError] if the removed +async:+ option is passed
       #
-      # @example Basic invocation
-      #   invoke SendEmail::Service do |payload|
+      # @example Enqueue a service
+      #   enqueue 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|
+      # @example Route to a queue
+      #   enqueue SendEmail::Service, queue: :mailers do |payload|
       #     { user_id: payload[:user_id] }
       #   end
       #
-      # @example Conditional invocation
-      #   invoke GrantRewards::Service, if: ->(p) { p[:premium] } do |payload|
+      # @example Conditional
+      #   enqueue GrantRewards::Service, if: ->(p) { p[:premium] } do |payload|
       #     { user_id: payload[:user_id] }
       #   end
-      def invoke(service_class, options = {}, &block)
+      def enqueue(service_class, options = {}, &block)
+        reject_async_option!(options)
+
         @invocations ||= []
         @invocations << {
           service_class: service_class,
@@ -128,6 +177,20 @@ module Servus
         }
       end
 
+      # Explains that +invoke+ was renamed, rather than failing as a typo.
+      #
+      # Event classes load at boot, so a bare NoMethodError here would read like
+      # a misspelling instead of a rename. This covers both changes at once,
+      # since the overwhelmingly common declaration was +invoke Foo, async: true+.
+      #
+      # @raise [NoMethodError] always
+      # @deprecated Use {#enqueue}.
+      def invoke(*_args, **_options, &)
+        raise NoMethodError,
+              '`invoke` was renamed to `enqueue` in 1.0.0 — event invocation is always ' \
+              'asynchronous. Replace `invoke` with `enqueue`, and drop `async:` if present.'
+      end
+
       # Returns all service invocations declared for this event.
       #
       # @return [Array<Hash>] array of invocation configurations
@@ -135,34 +198,6 @@ module Servus
         @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
@@ -218,11 +253,31 @@ module Servus
       # @param payload [Hash] the event payload
       # @return [Array] results from all invoked services
       def handle(payload)
-        invocations_for(payload).map(&:execute)
+        invocations_for(payload).map(&:enqueue)
       end
 
       private
 
+      # Rejects the removed +async:+ option at declaration time.
+      #
+      # Declaration time matters here: an Event class loads at boot, so this
+      # fails on deploy rather than on the first emit in production. Rejecting
+      # +async: false+ is the point — that declaration asks for synchronous
+      # invocation, which no longer exists, and quietly giving it the opposite
+      # would be worse than refusing.
+      #
+      # @param options [Hash]
+      # @return [void]
+      # @raise [ArgumentError] if +:async+ is present, whatever its value
+      # @api private
+      def reject_async_option!(options)
+        return unless options.key?(:async)
+
+        raise ArgumentError,
+              '`async:` is no longer a valid option — event invocation is always ' \
+              'asynchronous. Remove it from the declaration.'
+      end
+
       # @api private
       def should_invoke?(payload, options)
         return false if options[:if] && !options[:if].call(payload)

data/lib/servus/events/bus.rb

@@ -83,7 +83,7 @@ module Servus
           ActiveSupport::Notifications.instrument(notification_name(event_name), payload) do
             resolve_invocations(event_name, payload)
               .uniq(&:key)
-              .each(&:execute)
+              .each(&:enqueue)
           end
         end
 

data/lib/servus/events/emitter.rb

@@ -15,6 +15,15 @@ module Servus
     module Emitter
       extend ActiveSupport::Concern
 
+      # Triggers accepted by the +emits+ DSL.
+      #
+      # +:success+ and +:failure+ are selected from the service's result after
+      # +call+ returns. +:error!+ is fired by {Servus::Base#error!} immediately
+      # before it raises, so it never coincides with +:failure+.
+      #
+      # Note the bang on +:error!+ — it mirrors the method that triggers it.
+      EMISSION_TRIGGERS = %i[success failure error!].freeze
+
       # Emits events for a service result.
       #
       # Called automatically after service execution completes. Determines the
@@ -33,7 +42,7 @@ module Servus
         # 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 or a
+        # trigger condition (:success, :failure, or :error!). Use the `with` option or a
         # block to provide a custom payload builder. Use `if` or `unless` to gate emission
         # on a runtime condition.
         #
@@ -86,34 +95,21 @@ module Servus
         #     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 Event classes, not by emitting multiple events
-        #   from the service. This maintains separation of concerns.
-        #
-        # @example Recommended pattern (one event, multiple reactions)
-        #   # Service emits one event
+        # @example Multiple events on one trigger, each with its own payload
         #   class CreateUser < Servus::Base
         #     emits :user_created, on: :success
-        #   end
-        #
-        #   # Event coordinates multiple reactions
-        #   class UserCreated < Servus::Event
-        #     event_name :user_created
-        #     invoke SendWelcomeEmail::Service, async: true
-        #     invoke TrackAnalytics::Service, async: true
+        #     emits :welcome_queued, on: :success, with: :welcome_payload
         #   end
         #
         # @see Servus::Events::Bus
         # @see Servus::Event
         def emits(event_name, on:, **options, &block)
-          valid_triggers = %i[success failure error!]
-
-          unless valid_triggers.include?(on)
-            raise ArgumentError, "Invalid trigger: #{on}. Must be one of: #{valid_triggers.join(', ')}"
+          unless EMISSION_TRIGGERS.include?(on)
+            raise ArgumentError,
+                  "Invalid trigger: #{on}. Must be one of: #{EMISSION_TRIGGERS.join(', ')}"
           end
 
-          @event_emissions ||= { success: [], failure: [], error!: [] }
+          @event_emissions ||= empty_emissions
           @event_emissions[on] << build_emission(event_name, options, block)
         end
 
@@ -121,20 +117,25 @@ module Servus
         #
         # @return [Hash] hash of event emissions grouped by trigger
         #   { success: [...], failure: [...], error!: [...] }
-        def event_emissions
-          @event_emissions || { success: [], failure: [], error!: [] }
-        end
+        def event_emissions = @event_emissions || empty_emissions
 
         # 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
+        def emissions_for(trigger) = event_emissions[trigger] || []
 
         private
 
+        # An empty emission set, one entry per supported trigger.
+        #
+        # Derived from {Emitter::EMISSION_TRIGGERS} rather than written out, so
+        # the shape cannot drift from the list of triggers actually accepted.
+        #
+        # @return [Hash{Symbol => Array}]
+        # @api private
+        def empty_emissions = EMISSION_TRIGGERS.to_h { |trigger| [trigger, []] }
+
         def build_emission(event_name, options, block)
           {
             event_name: event_name,
@@ -201,11 +202,31 @@ module Servus
       # @api private
       def validate_event_payload!(event_name, payload)
         event_class = Servus::Events::Bus.event_for(event_name)
-        return unless event_class
+        return require_event_schema!(event_name) unless event_class
 
         Servus::Support::Validator.validate_event_payload!(event_class, payload)
       end
 
+      # Enforces {Servus::Config#require_event_payload_schema} for an event that
+      # has no Event class to carry a schema.
+      #
+      # An unregistered event name is the one case where a payload cannot be
+      # validated at all, so it is exactly where the flag matters most. Skipping
+      # it here would mean the setting silently passed over the events furthest
+      # from having a contract.
+      #
+      # @param event_name [Symbol] the event being emitted
+      # @return [void]
+      # @raise [Servus::Support::Errors::SchemaRequiredError] if enforcement is enabled
+      # @api private
+      def require_event_schema!(event_name)
+        return unless Servus.config.require_event_payload_schema
+
+        raise Servus::Support::Errors::SchemaRequiredError,
+              "#{self.class} emits :#{event_name} but no Event class is registered for it — " \
+              'schema missing! require_event_payload_schema is set to true.'
+      end
+
       # Builds the event payload using the configured payload builder or defaults.
       #
       # @param emission [Hash] the emission configuration

data/lib/servus/events/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Servus
+  module Events
+    # Errors raised while resolving or enqueueing event invocations.
+    #
+    # These deliberately do *not* inherit from {Servus::Support::Errors::ServiceError}.
+    # Everything in that hierarchy carries an +#http_status+ and an +#api_error+
+    # because it describes a business outcome a caller might render. A missing job
+    # backend, or a service that cannot be enqueued, is a configuration problem —
+    # there is no sensible HTTP status for it.
+    #
+    # @see Servus::Events::Invocation
+    module Errors
+      # Base class for every event invocation error.
+      class Error < StandardError; end
+
+      # Raised when an event invocation cannot be enqueued because ActiveJob is
+      # not loaded.
+      #
+      # Event invocation is always asynchronous, so an event that reacts to
+      # anything needs a job backend. Servus's core — services, schemas, guards,
+      # and the bus itself — works without one; only +enqueue+ declarations
+      # require it.
+      class AsyncBackendMissingError < Error
+        # @param service [Class] the service that could not be enqueued
+        # @return [AsyncBackendMissingError]
+        def self.for(service)
+          new(
+            "Cannot enqueue #{service} from an event: ActiveJob is not loaded. " \
+            'Event invocation is always asynchronous and runs through ActiveJob. ' \
+            'Require active_job, or remove the enqueue declaration.'
+          )
+        end
+      end
+
+      # Raised when a service has no name, so no job class can be generated for it.
+      #
+      # ActiveJob resolves a job on the worker by its serialized class name, so a
+      # service created with +Class.new(Servus::Base)+ has nothing to serialize.
+      # This surfaces almost exclusively in tests — assign the class to a constant,
+      # or use +stub_const+.
+      class AnonymousServiceError < Error
+        # @param service [Class] the anonymous service
+        # @return [AnonymousServiceError]
+        def self.for(service)
+          new(
+            "Cannot generate a job class for #{service.inspect}: it is anonymous. " \
+            'ActiveJob resolves jobs by class name, so a service must be assigned ' \
+            'to a constant before it can be enqueued.'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/servus/events/invocation.rb

@@ -12,61 +12,54 @@ module Servus
     # 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.
+    # *scheduling* (queue, priority, delay). 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: {}
-    #   )
+    # Invocations are always enqueued, never run inline. A reaction that ran
+    # synchronously would put its latency and its failures back into the
+    # emitting service, which is what events exist to avoid.
     #
-    # @example Async invocation with scheduling options
+    # @example
     #   Invocation.new(
     #     service: Notifications::Send::Service,
     #     params:  { user_id: "abc-123" },
-    #     options: { async: true, queue: :mailers, priority: 5 }
+    #     options: { 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+)
+      # @return [Class] the service class to enqueue (must respond to +.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+
+      # @return [Hash] scheduling options — +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
+      # @param options [Hash] scheduling options
       def initialize(service:, params:, options: {})
         @service = service
         @params  = params
         @options = options
       end
 
-      # Executes the invocation.
+      # Enqueues the invocation via ActiveJob.
       #
-      # 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.
+      # Scheduling options (queue, wait, priority, and so on) are merged into
+      # the +call_async+ keyword arguments.
       #
-      # @return [Servus::Support::Response, void]
-      def execute
-        if options[:async]
-          service.call_async(**params, **async_options)
-        else
-          service.call(**params)
-        end
+      # @return [void]
+      # @raise [Servus::Events::Errors::AsyncBackendMissingError] if ActiveJob is not loaded
+      def enqueue
+        raise Errors::AsyncBackendMissingError.for(service) unless service.respond_to?(:call_async)
+
+        service.call_async(**params, **async_options)
       end
 
       # A deterministic deduplication key derived from the service class
@@ -86,6 +79,7 @@ module Servus
       # Extracts scheduling options for +call_async+.
       #
       # @return [Hash]
+      # @api private
       def async_options
         options.slice(:queue, :wait, :wait_until, :priority, :job_options).compact
       end

data/lib/servus/extensions/async/call.rb

@@ -81,6 +81,11 @@ module Servus
           # The named job class identifies the service — only args are serialized.
           job = job_options.any? ? servus_job_class.set(**job_options) : servus_job_class
           job.perform_later(**args)
+        rescue Servus::Support::Errors::ServiceError, Servus::Events::Errors::Error
+          # With the :inline and :test adapters perform_later runs the service,
+          # so Servus's own errors surface here. Wrapping them as an enqueue
+          # failure would blame the wrong layer.
+          raise
         rescue StandardError => e
           raise Errors::JobEnqueueError, "Failed to enqueue async job for #{self}: #{e.message}"
         end
@@ -164,6 +169,8 @@ module Servus
         # @return [Class<Servus::Extensions::Async::Job>] the generated job class
         # @api private
         def build_servus_job_class
+          raise Servus::Events::Errors::AnonymousServiceError.for(self) if name.nil?
+
           klass = Class.new(Servus::Extensions::Async::Job)
           klass.servus_service = self
 

data/lib/servus/helpers/controller_helpers.rb

@@ -39,46 +39,6 @@ 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

data/lib/servus/railtie.rb

@@ -41,6 +41,9 @@ module Servus
 
       Servus::Events::Bus.clear if Rails.env.development?
 
+      # Schemas are cached per class, and reloading replaces those classes.
+      Servus::Support::Validator.clear_cache!
+
       # Eager load all event classes
       events_path = Rails.root.join(Servus.config.events_dir)
       Dir[File.join(events_path, '**/*_event.rb')].each do |file|

data/lib/servus/schema/cache.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Servus
+  module Schema
+    # Memoized +$ref+ resolutions, plus the generation counter that invalidates
+    # everything derived from them.
+    #
+    # Entries are keyed by ref string and hold the resolved *target* of that
+    # ref, before any sibling properties are merged over it. That is what makes
+    # a single entry safe to share across every site that uses the ref: the
+    # target depends only on the ref string and the registry contents, and
+    # callers apply their own siblings afterwards with +Hash#merge+, which
+    # returns a new hash and never mutates the cached one.
+    #
+    # The generation counter lets consumers that build on compiled schemas —
+    # {Servus::Base}, {Servus::Event} — memoize alongside the generation they
+    # compiled under and rebuild when it moves, with no dependency tracking.
+    #
+    # @see Servus::Schema
+    # @see Servus::Schema::Compiler
+    # @api private
+    class Cache
+      # Monotonic counter, advanced by {#invalidate!}.
+      #
+      # @return [Integer]
+      attr_reader :generation
+
+      def initialize
+        @entries = {}
+        @generation = 0
+        @mutex = Mutex.new
+      end
+
+      # Returns the memoized resolution of +ref+, computing it on a miss.
+      #
+      # A raising block leaves no entry behind, so a ref that failed part way
+      # through resolution is never cached in a half-built state.
+      #
+      # @param ref [String] the ref string
+      # @yieldreturn [Object] the resolved target, computed on a miss
+      # @return [Object] the resolved target
+      def resolve(ref)
+        cached = @entries[ref]
+        return cached unless cached.nil?
+
+        resolved = yield
+        @mutex.synchronize { @entries[ref] = resolved }
+        resolved
+      end
+
+      # Discards every memoized resolution and advances {#generation}.
+      #
+      # @return [void]
+      def invalidate!
+        @mutex.synchronize do
+          @entries = {}
+          @generation += 1
+        end
+      end
+
+      # Number of memoized resolutions. Used by specs to assert that a repeated
+      # ref is expanded once rather than once per occurrence.
+      #
+      # @return [Integer]
+      def size
+        @entries.size
+      end
+    end
+  end
+end