servus 0.2.1 → 0.4.0

data/lib/servus/helpers/controller_helpers.rb

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

data/lib/servus/railtie.rb

@@ -14,11 +14,17 @@ module Servus
     initializer 'servus.job_async' do
       ActiveSupport.on_load(:active_job) do
         require 'servus/extensions/async/ext'
-        # Extend the base service with the async call method
         Servus::Base.extend Servus::Extensions::Async::Call
       end
     end
 
+    initializer 'servus.lazily' do
+      ActiveSupport.on_load(:active_record) do
+        require 'servus/extensions/lazily/ext'
+        Servus::Base.extend Servus::Extensions::Lazily::Call
+      end
+    end
+
     # Load guards and event handlers, clear caches on reload
     config.to_prepare do
       # Load custom guards from guards_dir

data/lib/servus/support/data_object.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module Servus
+  module Support
+    # A read-only wrapper around Hash data that provides accessor-style access.
+    #
+    # When service results contain Hash data, +DataObject+ wraps it so keys can be
+    # accessed as methods in addition to the standard bracket syntax. Nested Hashes
+    # are recursively wrapped, enabling chained access like +data.user.address.city+.
+    #
+    # Non-Hash values (nil, String, Integer, Array, model instances) pass through
+    # unwrapped. This means +data.user+ returns the original object when +user+ is
+    # an ActiveRecord model, allowing natural method chaining (+data.user.email+).
+    #
+    # +DataObject+ inherits from +SimpleDelegator+, so all standard Hash methods
+    # (+[]+, +keys+, +each+, +as_json+, +==+, etc.) are delegated transparently.
+    #
+    # @example Accessor-style access
+    #   data = DataObject.wrap({ user: { email: "alice@example.com" } })
+    #   data.user.email   # => "alice@example.com"
+    #   data[:user]        # => { email: "alice@example.com" } (plain Hash)
+    #
+    # @example Mixed values
+    #   data = DataObject.wrap({ user: user_model, metadata: { source: "api" } })
+    #   data.user.email       # => delegates to model's #email method
+    #   data.metadata.source  # => "api" (wrapped Hash accessor)
+    #
+    # @see Servus::Support::Response
+    class DataObject < SimpleDelegator
+      # Wraps a value in a DataObject if it is a Hash.
+      #
+      # Non-Hash values are returned unchanged. This is the preferred way to
+      # create DataObject instances, as it handles nil and non-Hash types safely.
+      #
+      # @param data [Object] the value to potentially wrap
+      # @return [DataObject] if data is a Hash
+      # @return [Array] with Hash elements wrapped if data is an Array
+      # @return [Object] the original value otherwise
+      def self.wrap(data)
+        case data
+        when Hash  then new(data)
+        when Array then data.map { |item| wrap(item) }
+        else data
+        end
+      end
+
+      private
+
+      # Provides accessor-style access to Hash keys.
+      #
+      # Only zero-argument, no-block calls trigger key lookup. Methods with
+      # arguments (e.g., +fetch+, +dig+) delegate to Hash normally.
+      # When the value is a Hash, it is recursively wrapped in a DataObject.
+      #
+      # @param method_name [Symbol] the method name to look up as a key
+      # @return [Object] the value for the key, wrapped if it is a Hash
+      # @raise [NoMethodError] if the key does not exist
+      def method_missing(method_name, *args, &block)
+        return super if args.any? || block
+
+        hash = __getobj__
+        if hash.key?(method_name.to_sym)
+          self.class.wrap(hash[method_name.to_sym])
+        elsif hash.key?(method_name.to_s)
+          self.class.wrap(hash[method_name.to_s])
+        else
+          super
+        end
+      end
+
+      # @api private
+      def respond_to_missing?(method_name, include_private = false)
+        hash = __getobj__
+        hash.key?(method_name.to_sym) || hash.key?(method_name.to_s) || super
+      end
+    end
+  end
+end

data/lib/servus/support/errors.rb

@@ -267,6 +267,22 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # Raised when a service or event handler is invoked without a required schema.
+      #
+      # Triggered by the +require_service_arguments_schema+,
+      # +require_service_result_schema+, or +require_event_payload_schema+
+      # configuration flags.
+      #
+      # @see Servus::Config#require_service_arguments_schema
+      # @see Servus::Config#require_service_result_schema
+      # @see Servus::Config#require_event_payload_schema
+      class SchemaRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Schema is required but not defined'
+
+        def http_status = :unprocessable_entity
+        def api_error = { code: :schema_required, message: message }
+      end
+
       # 423 Locked - resource is locked.
       class LockedError < ServiceError
         DEFAULT_MESSAGE = 'Locked'

data/lib/servus/support/lockdown.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Servus
+  module Support
+    # Enforces that services are invoked through {Servus::Base.call} rather
+    # than by instantiating a service and calling its instance `#call`
+    # directly. The class-level `.call` runs argument validation, logging,
+    # benchmarking, guard handling, result validation, and event emission;
+    # calling the instance method directly would silently skip all of that.
+    #
+    # When included in {Servus::Base}, this module:
+    # - Privatizes `.new` on the base class (and, by inheritance, on every
+    #   descendant) so `MyService.new` from outside the class raises
+    #   `NoMethodError`.
+    # - Installs a `method_added` hook on every descendant that privatizes
+    #   any instance-level `#call` at definition time.
+    #
+    # Controlled by {Servus::Config#lockdown_enabled} (default `true`). Set
+    # it to `false` to allow direct instantiation and public instance
+    # `#call` — useful if you have existing code that relies on those entry
+    # points, or if you prefer to opt out of this enforcement entirely.
+    #
+    # @example Opting out
+    #   Servus.configure do |config|
+    #     config.lockdown_enabled = false
+    #   end
+    #
+    # @see Servus::Config#lockdown_enabled
+    module Lockdown
+      # Wires the lockdown hooks into the including class.
+      #
+      # Extends the base with {ClassMethods} (for {ClassMethods#apply_lockdown!}),
+      # prepends {Inherited} so subclasses receive the `method_added` hook,
+      # and applies the current config value to `.new`'s visibility.
+      #
+      # @param base [Class] the class including this module (expected to be {Servus::Base})
+      # @return [void]
+      # @api private
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.singleton_class.prepend(Inherited)
+        base.apply_lockdown!
+      end
+
+      # Prepended onto the base class's singleton so that every subclass of
+      # {Servus::Base} is automatically extended with {PrivateCall} at
+      # class-definition time.
+      #
+      # @api private
+      module Inherited
+        # Ensures each subclass has the `method_added` hook installed.
+        #
+        # @param subclass [Class] the newly defined subclass
+        # @return [void]
+        def inherited(subclass)
+          super
+          subclass.extend(PrivateCall)
+        end
+      end
+
+      # Extended onto every {Servus::Base} subclass. Privatizes any
+      # instance-level `#call` as soon as it is defined, provided lockdown
+      # is enabled in config at definition time.
+      #
+      # @api private
+      module PrivateCall
+        # @param name [Symbol] the name of the newly added method
+        # @return [void]
+        def method_added(name)
+          super
+          return unless Servus.config.lockdown_enabled
+
+          private :call if name == :call && public_method_defined?(:call)
+        end
+      end
+
+      # Class-level helpers installed on {Servus::Base}.
+      module ClassMethods
+        # Applies {Servus::Config#lockdown_enabled} to `.new`'s visibility.
+        # Called on include and re-called whenever the config flag changes.
+        #
+        # @return [void]
+        # @api private
+        def apply_lockdown!
+          if Servus.config.lockdown_enabled
+            singleton_class.send(:private, :new)
+          else
+            singleton_class.send(:public, :new)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servus/support/logger.rb

@@ -55,6 +55,22 @@ module Servus
         logger.warn("#{service_class.name} failed in #{duration.round(3)}s with error: #{error}")
       end
 
+      # Logs a guard failure from a service
+      #
+      # @param service_class [Class] The service class
+      # @param error [Servus::Support::Errors::GuardError] The guard error
+      def self.log_guard_failure(service_class, error)
+        logger.warn("#{service_class.name} guard failed: #{error.message}")
+      end
+
+      # Logs an event emission
+      #
+      # @param event_name [Symbol] The event name
+      # @param payload [Hash] The event payload
+      def self.log_event(event_name, payload)
+        logger.info("Event :#{event_name} emitted with payload: #{payload.inspect}")
+      end
+
       # Logs a validation error from a service
       #
       # @param service_class [Class] The service class

data/lib/servus/support/response.rb

@@ -51,7 +51,7 @@ module Servus
       # @api private
       def initialize(success, data, error)
         @success = success
-        @data = data
+        @data = DataObject.wrap(data)
         @error = error
       end
 
@@ -69,6 +69,17 @@ module Servus
       def success?
         @success
       end
+
+      # Checks if the service execution failed.
+      #
+      # @return [Boolean] true if the service failed, false if it succeeded
+      #
+      # @example
+      #   result = MyService.call(params)
+      #   return render_error(result.error.message) if result.failure?
+      def failure?
+        !@success
+      end
     end
   end
 end

data/lib/servus/support/validator.rb

@@ -45,24 +45,23 @@ module Servus
       # @api private
       def self.validate_arguments!(service_class, args)
         schema = load_schema(service_class, 'arguments')
-        return true unless schema # Skip validation if no schema exists
-
-        serialized_result = args.as_json
-        validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
+        enforce_schema_presence!(schema, service_class, :require_service_arguments_schema)
+        return true unless schema
 
-        if validation_errors.any?
-          error_message = "Invalid arguments for #{service_class.name}: #{validation_errors.join(', ')}"
-          raise Servus::Base::ValidationError, error_message
-        end
+        validate_data_against_schema!(
+          args,
+          schema,
+          "Invalid arguments for #{service_class.name}"
+        )
 
         true
       end
 
-      # Validates service result data against the RESULT_SCHEMA.
+      # Validates service result data against the appropriate schema.
       #
-      # Checks the result.data against either an inline RESULT_SCHEMA constant or
-      # a file-based schema at app/schemas/services/namespace/result.json.
-      # Only validates successful responses; failures are skipped.
+      # For successful responses, validates against the +result+ schema.
+      # For failure responses with data, validates against the +failure+ schema.
+      # Failure responses without data are skipped.
       #
       # @param service_class [Class] the service class being validated
       # @param result [Servus::Support::Response] the response object to validate
@@ -74,20 +73,33 @@ module Servus
       #
       # @api private
       def self.validate_result!(service_class, result)
-        return result unless result.success?
+        schema, schema_type = result_schema_for(service_class, result)
+        return result unless schema
 
-        schema = load_schema(service_class, 'result')
-        return result unless schema # Skip validation if no schema exists
+        validate_data_against_schema!(
+          result.data,
+          schema,
+          "Invalid #{schema_type} structure from #{service_class.name}"
+        )
 
-        serialized_result = result.data.as_json
-        validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
+        result
+      end
 
-        if validation_errors.any?
-          error_message = "Invalid result structure from #{service_class.name}: #{validation_errors.join(', ')}"
-          raise Servus::Base::ValidationError, error_message
+      # Resolves the schema and type label for a service result.
+      #
+      # @param service_class [Class] the service class
+      # @param result [Servus::Support::Response] the response object
+      # @return [Array(Hash, String), Array(nil, nil)] the schema and type label
+      #
+      # @api private
+      def self.result_schema_for(service_class, result)
+        if result.success?
+          schema = load_schema(service_class, 'result')
+          enforce_schema_presence!(schema, service_class, :require_service_result_schema)
+          [schema, 'result']
+        elsif result.data
+          [load_schema(service_class, 'failure'), 'failure']
         end
-
-        result
       end
 
       # Validates event payload against the handler's payload schema.
@@ -104,15 +116,14 @@ module Servus
       # @api private
       def self.validate_event_payload!(handler_class, payload)
         schema = handler_class.payload_schema
+        enforce_schema_presence!(schema, handler_class, :require_event_payload_schema)
         return true unless schema
 
-        serialized_payload = payload.as_json
-        validation_errors = JSON::Validator.fully_validate(schema, serialized_payload)
-
-        if validation_errors.any?
-          raise Servus::Support::Errors::ValidationError,
-                "Invalid payload for event :#{handler_class.event_name}: #{validation_errors.join(', ')}"
-        end
+        validate_data_against_schema!(
+          payload,
+          schema,
+          "Invalid payload for event :#{handler_class.event_name}"
+        )
 
         true
       end
@@ -127,7 +138,7 @@ module Servus
       # Schemas are cached after first load for performance.
       #
       # @param service_class [Class] the service class
-      # @param type [String] schema type ("arguments" or "result")
+      # @param type [String] schema type ("arguments", "result", or "failure")
       # @return [Hash, nil] the schema hash, or nil if no schema found
       #
       # @api private
@@ -141,10 +152,10 @@ module Servus
         return @schema_cache[schema_path] if @schema_cache.key?(schema_path)
 
         # Check for DSL-defined schema first
-        dsl_schema = if type == 'arguments'
-                       service_class.arguments_schema
-                     else
-                       service_class.result_schema
+        dsl_schema = case type
+                     when 'arguments' then service_class.arguments_schema
+                     when 'result'    then service_class.result_schema
+                     when 'failure'   then service_class.failure_schema
                      end
 
         inline_schema_constant_name = "#{service_class}::#{type.upcase}_SCHEMA"
@@ -180,6 +191,40 @@ module Servus
         @schema_cache
       end
 
+      # Serializes data and validates it against a JSON schema.
+      #
+      # @param data [Object] the data to validate
+      # @param schema [Hash] the JSON schema to validate against
+      # @param message_prefix [String] prefix for the error message on failure
+      # @return [void]
+      # @raise [Servus::Support::Errors::ValidationError] if data fails validation
+      #
+      # @api private
+      def self.validate_data_against_schema!(data, schema, message_prefix)
+        errors = JSON::Validator.fully_validate(schema, data.as_json)
+        return if errors.empty?
+
+        raise Servus::Base::ValidationError, "#{message_prefix}: #{errors.join(', ')}"
+      end
+
+      # Returns the schema if present. Raises if absent and the config flag is enabled.
+      #
+      # @param schema [Hash, nil] the loaded schema
+      # @param klass [Class] the service or handler class
+      # @param config_flag [Symbol] the config method to check
+      # @return [Hash, nil] the schema
+      # @raise [Servus::Support::Errors::SchemaRequiredError] if schema is nil and enforcement is enabled
+      #
+      # @api private
+      def self.enforce_schema_presence!(schema, klass, config_flag)
+        return schema if schema
+
+        return unless Servus.config.public_send(config_flag)
+
+        raise Servus::Support::Errors::SchemaRequiredError,
+              "#{klass.name} schema missing! #{config_flag} is set to true."
+      end
+
       # Fetches schema from DSL, inline constant, or file.
       #
       # Implements the schema resolution precedence:

data/lib/servus/testing/example_builders.rb

@@ -116,6 +116,80 @@ module Servus
         Servus::Support::Response.new(true, example, nil)
       end
 
+      # Extracts example failure data values from a service's schema.
+      #
+      # Looks for `example` or `examples` keywords in the service's failure schema
+      # and returns them wrapped in a failure Response. Useful for validating failure
+      # response structure in tests.
+      #
+      # @param service_class [Class] The service class to extract examples from
+      # @param overrides [Hash] Optional values to override the schema examples
+      # @return [Servus::Support::Response] Failure response object with example data
+      #
+      # @example Basic usage
+      #   expected = servus_failure_example(ProcessPayment::Service)
+      #   # => Servus::Support::Response with failure? == true, data:
+      #   #    { reason: 'card_declined', decline_code: 'insufficient_funds' }
+      #
+      # @note Override keys can be strings or symbols; they'll be converted to symbols
+      # @note Returns empty hash if service has no failure schema defined
+      def servus_failure_example(service_class, overrides = {})
+        example = extract_example_from(service_class, :failure, overrides)
+        Servus::Support::Response.new(false, example, Servus::Support::Errors::ServiceError.new)
+      end
+
+      # Builds a successful Response object with the given data.
+      #
+      # Convenience method for creating successful responses in tests
+      # without calling +Servus::Support::Response.new+ directly.
+      #
+      # @param data [Hash] the success data to wrap in the response
+      # @return [Servus::Support::Response] a successful response wrapping the data
+      #
+      # @example Basic usage
+      #   response = servus_success_response(transferred: 50)
+      #   response.success?           # => true
+      #   response.data[:transferred] # => 50
+      #
+      # @example Stubbing a service call
+      #   allow(TransferService).to receive(:call).and_return(
+      #     servus_success_response(transferred: 50)
+      #   )
+      #
+      # @see #servus_failure_response
+      def servus_success_response(data = {})
+        Servus::Support::Response.new(true, data, nil)
+      end
+
+      # Builds a failure Response object with the given message and error type.
+      #
+      # Convenience method for creating failure responses in tests.
+      # Mirrors the signature of {Servus::Base#failure}.
+      #
+      # @param message [String, nil] the error message (uses error type's default if nil)
+      # @param data [Hash, nil] optional structured data to include with the failure
+      # @param type [Class] the error class to use (default: ServiceError)
+      # @return [Servus::Support::Response] a failure response with the error
+      #
+      # @example Basic usage
+      #   response = servus_failure_response("Insufficient funds")
+      #   response.failure?      # => true
+      #   response.error.message # => "Insufficient funds"
+      #
+      # @example With custom error type
+      #   response = servus_failure_response("Not found", type: Servus::Support::Errors::NotFoundError)
+      #   response.error.http_status # => :not_found
+      #
+      # @example With structured failure data
+      #   response = servus_failure_response("Failed", data: { reason: "expired" })
+      #   response.data[:reason] # => "expired"
+      #
+      # @see #servus_success_response
+      def servus_failure_response(message = nil, data: nil, type: Servus::Support::Errors::ServiceError)
+        error = type.new(message)
+        Servus::Support::Response.new(false, data, error)
+      end
+
       private
 
       # Helper method to extract and merge examples from schema

data/lib/servus/testing/matchers.rb

@@ -85,4 +85,103 @@ RSpec::Matchers.define :call_service do |service_class|
     "expected #{service_class} to receive #{method}"
   end
 end
+
+# Matcher for asserting schema presence on a service or event handler
+RSpec::Matchers.define :have_schema do |schema_type|
+  match do |klass|
+    if schema_type.to_s == 'payload'
+      !klass.payload_schema.nil?
+    else
+      Servus::Support::Validator.clear_cache!
+      !Servus::Support::Validator.load_schema(klass, schema_type.to_s).nil?
+    end
+  end
+
+  failure_message do |klass|
+    "expected #{klass.name} to have a #{schema_type} schema defined"
+  end
+
+  failure_message_when_negated do |klass|
+    "expected #{klass.name} not to have a #{schema_type} schema defined"
+  end
+end
+
+# Matcher for asserting a successful service response
+RSpec::Matchers.define :be_service_success do
+  match do |result|
+    @result = result
+    result.is_a?(Servus::Support::Response) && result.success?
+  end
+
+  failure_message do
+    if @result.is_a?(Servus::Support::Response)
+      "expected a successful response, but got failure with error: #{@result.error&.message}"
+    else
+      "expected a Servus::Support::Response, got #{@result.class}"
+    end
+  end
+
+  failure_message_when_negated do
+    'expected a failure response, but got success'
+  end
+end
+
+# Matcher for asserting a failed service response with optional error class and message
+RSpec::Matchers.define :be_service_failure do |expected_error_class|
+  chain :with_message do |message|
+    @expected_message = message
+  end
+
+  match do |result|
+    @result = result
+    return false unless result.is_a?(Servus::Support::Response) && result.failure?
+    return false if expected_error_class && !result.error.is_a?(expected_error_class)
+    return false if @expected_message && result.error.message != @expected_message
+
+    true
+  end
+
+  failure_message do
+    if !@result.is_a?(Servus::Support::Response)
+      "expected a Servus::Support::Response, got #{@result.class}"
+    elsif @result.success?
+      'expected a failure response, but got success'
+    elsif expected_error_class && !@result.error.is_a?(expected_error_class)
+      "expected error to be a #{expected_error_class.name}, got #{@result.error.class.name}"
+    elsif @expected_message
+      "expected error message #{@expected_message.inspect}, got #{@result.error.message.inspect}"
+    end
+  end
+end
+
+# Matcher for asserting a guard failure response with optional error code and message
+RSpec::Matchers.define :be_guard_failure do |expected_code|
+  chain :with_message do |message|
+    @expected_message = message
+  end
+
+  match do |result|
+    @result = result
+    return false unless result.is_a?(Servus::Support::Response) && result.failure?
+    return false unless result.error.is_a?(Servus::Support::Errors::GuardError)
+    return false if expected_code && result.error.code != expected_code
+    return false if @expected_message && result.error.message != @expected_message
+
+    true
+  end
+
+  failure_message do
+    if !@result.is_a?(Servus::Support::Response)
+      "expected a Servus::Support::Response, got #{@result.class}"
+    elsif @result.success?
+      'expected a guard failure response, but got success'
+    elsif !@result.error.is_a?(Servus::Support::Errors::GuardError)
+      "expected error to be a GuardError, got #{@result.error.class.name}"
+    elsif expected_code && @result.error.code != expected_code
+      "expected guard error code #{expected_code.inspect}, got #{@result.error.code.inspect}"
+    elsif @expected_message
+      "expected guard error message #{@expected_message.inspect}, got #{@result.error.message.inspect}"
+    end
+  end
+end
 # rubocop:enable Metrics/BlockLength

data/lib/servus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Servus
-  VERSION = '0.2.1'
+  VERSION = '0.4.0'
 end