servus 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58e6098b9ea316c670b5b8aa6f61828d961cc3c8ad6e72357d71c442dfe75151
-  data.tar.gz: 215f0f790ad36575b0b9de3f956cf585f19051c16d5250ada1ae152a969dd1d7
+  metadata.gz: 2f382ed3d92dd577c93965ae207c00d28cac6dfddf452cf22fb5dafcd69d56eb
+  data.tar.gz: f5a4394a33f5a3061d3c5746fdd058eb457cb29baa2f0adb9cc97c0679f5c158
 SHA512:
-  metadata.gz: 48142cd74cbd766846ccd9d8bf4a71a8d67136cbd60bdc948ddda6a0fa99f7e6072351b6ff98958500a6d84e49d1cb7d122e8e435efeb8b1384d39a4be9932ad
-  data.tar.gz: 13899ee4220e2e25b888eae9b6675a77780770628717bc11a2abda9bdd82e49b0798d70c954f91e5649a3bc281d9b3ad0e50dce41374f3c2ebc42125d7321848
+  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/generators/servus/guard/guard_generator.rb

@@ -44,7 +44,7 @@ module Servus
       # @return [String] spec file path
       # @api private
       def guard_spec_path
-        File.join('spec', Servus.config.guards_dir, "#{file_name}_guard_spec.rb")
+        File.join(Servus.config.tests_dir, Servus.config.guards_dir, "#{file_name}_guard_spec.rb")
       end
 
       # Returns the guard class name.

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

@@ -34,14 +34,16 @@ class <%= guard_class_name %> < Servus::Guard
 
   # Tests whether the <%= file_name.humanize.downcase %> condition is met.
   #
-  # @param kwargs [Hash] the arguments to validate
+  # Arguments passed to `enforce_*!` / `check_*?` are stored as `@kwargs`
+  # and exposed via `method_missing`, so read them directly off the instance.
+  #
   # @return [Boolean] true if validation passes
-  def test(**kwargs)
+  def test
     # TODO: Implement validation logic
     # Return true if the condition is met, false otherwise
     #
     # Example:
-    #   def test(account:, amount:)
+    #   def test
     #     account.balance >= amount
     #   end
     true

data/lib/generators/servus/service/service_generator.rb

@@ -57,7 +57,7 @@ module Servus
       # @return [String] spec file path
       # @api private
       def service_path_spec
-        "spec/services/#{file_path}/service_spec.rb"
+        "#{Servus.config.tests_dir}/services/#{file_path}/service_spec.rb"
       end
 
       # Returns the path for the result schema file.

data/lib/servus/base.rb

@@ -48,6 +48,7 @@ module Servus
   class Base
     include Servus::Support::Errors
     include Servus::Support::Rescuer
+    include Servus::Support::Lockdown
     include Servus::Events::Emitter
     include Servus::Guards
 
@@ -157,6 +158,46 @@ module Servus
       raise type, message
     end
 
+    # Invokes another service from within this service's {#call} and returns its
+    # data on success. On failure, halts the outer service with the sub-service's
+    # failure Response — the outer service's caller receives that Response
+    # unchanged (same error object, message, code, http_status).
+    #
+    # Sugar over:
+    #
+    #   result = SubService.call(**params)
+    #   return result unless result.success?
+    #   data = result.data
+    #
+    # Only call from within a service's `#call` (or helpers reachable from
+    # it); the throw is caught by {Servus::Base.call}.
+    #
+    # @example Composing services
+    #   class SendDigitalCash::Service < Servus::Base
+    #     def call
+    #       data1 = call!(Accounts::Lookup::Service, id: account_id)
+    #       data2 = call!(Ledger::RecordTransfer::Service, account:, amount:)
+    #       success(ref: data2.ref)
+    #     end
+    #   end
+    #
+    # For invoking a service from *outside* a service context (controllers,
+    # rake tasks, jobs, consoles), see
+    # {Servus::Helpers::ControllerHelpers#run_service!}.
+    #
+    # @param service_class [Class<Servus::Base>] the sub-service to invoke
+    # @param params [Hash] keyword arguments to pass to the sub-service
+    # @return [Servus::Support::DataObject, Object] the sub-service's data on success
+    # @throw [:guard_failure, Servus::Support::Response] the failure Response, otherwise
+    #
+    # @see Servus::Helpers::ControllerHelpers#run_service!
+    def call!(service_class, **params)
+      result = service_class.call(**params)
+      return result.data if result.success?
+
+      throw(:guard_failure, result)
+    end
+
     class << self
       # Executes the service with automatic validation, logging, and benchmarking.
       #
@@ -196,11 +237,13 @@ module Servus
 
         # Wrap execution in catch block to handle guard failures
         result = catch(:guard_failure) do
-          benchmark(**args) { instance.call }
+          benchmark(**args) { instance.send(:call) }
         end
 
-        # If result is a GuardError, a guard failed - wrap in failure Response
-        result = Response.new(false, nil, result) if result.is_a?(Servus::Support::Errors::GuardError)
+        if result.is_a?(Servus::Support::Errors::GuardError)
+          Logger.log_guard_failure(self, result)
+          result = Response.new(false, nil, result)
+        end
 
         after_call(result, instance)
 

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.
@@ -51,22 +43,103 @@ module Servus
     # @return [String] the guards directory path
     attr_accessor :guards_dir
 
+    # The directory where generated spec/test files are placed.
+    #
+    # Defaults to `"spec"`. Projects using Minitest or a custom test layout
+    # can override this (e.g., `"test"`) so generators write files into the
+    # correct location.
+    #
+    # @return [String] the tests directory path
+    attr_accessor :tests_dir
+
     # Whether to include the default built-in guards (EnsurePresent, EnsurePositive).
     #
     # @return [Boolean] true to include default guards, false to exclude them
     attr_accessor :include_default_guards
 
+    # Whether to require all services to define an arguments schema.
+    #
+    # When enabled, raises {Servus::Support::Errors::SchemaRequiredError} when
+    # a service is called without an arguments schema defined.
+    #
+    # @return [Boolean] true to require arguments schemas, false to allow schema-less services
+    attr_accessor :require_service_arguments_schema
+
+    # Whether to require all services to define a result schema.
+    #
+    # When enabled, raises {Servus::Support::Errors::SchemaRequiredError} when
+    # a service returns a successful response without a result schema defined.
+    # Failure schemas remain optional regardless of this setting.
+    #
+    # @return [Boolean] true to require result schemas, false to allow schema-less services
+    attr_accessor :require_service_result_schema
+
+    # Whether to require all event classes to define a payload schema.
+    #
+    # When enabled, raises {Servus::Support::Errors::SchemaRequiredError} when
+    # an event validates a payload without a payload schema defined.
+    #
+    # @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.
+    #
+    # When enabled (default), callers must invoke services via the class
+    # method {Servus::Base.call}, which runs argument validation, logging,
+    # benchmarking, guards, result validation, and event emission. Calling
+    # `MyService.new` or `instance.call` directly raises `NoMethodError`.
+    #
+    # Disable this if you have existing code that instantiates services
+    # directly or otherwise prefer to opt out of the enforcement.
+    #
+    # @return [Boolean] true to enforce lockdown (default), false to allow
+    #   direct instantiation and public instance `#call`
+    # @see Servus::Support::Lockdown
+    attr_reader :lockdown_enabled
+
+    # Sets whether lockdown is enforced, immediately re-applying the
+    # resulting `.new` visibility to {Servus::Base}.
+    #
+    # @param value [Boolean] the new lockdown setting
+    # @return [Boolean] the new value
+    def lockdown_enabled=(value)
+      @lockdown_enabled = value
+      Servus::Base.apply_lockdown!
+    end
+
     # Initializes a new configuration with default values.
     #
     # @api private
     def initialize
+      set_default_directories
+      @include_default_guards           = true
+      @lockdown_enabled                 = true
+      @require_service_arguments_schema = false
+      @require_service_result_schema    = false
+      @require_event_payload_schema     = false
+    end
+
+    def set_default_directories
       @guards_dir   = 'app/guards'
       @events_dir   = 'app/events'
       @schemas_dir  = 'app/schemas'
       @services_dir = 'app/services'
-
-      @strict_event_validation = true
-      @include_default_guards  = true
+      @tests_dir    = 'spec'
     end
 
     # Returns the full path to a service's schema file.

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