servus 0.3.0 → 0.4.0

data/lib/servus/support/validator.rb

@@ -45,15 +45,14 @@ 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
@@ -74,21 +73,35 @@ module Servus
       #
       # @api private
       def self.validate_result!(service_class, result)
-        schema = result_schema_for(service_class, result)
+        schema, schema_type = result_schema_for(service_class, result)
         return result unless schema
 
-        serialized_result = result.data.as_json
-        validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
-
-        if validation_errors.any?
-          schema_type = result.success? ? 'result' : 'failure'
-          error_message = "Invalid #{schema_type} structure from #{service_class.name}: #{validation_errors.join(', ')}"
-          raise Servus::Base::ValidationError, error_message
-        end
+        validate_data_against_schema!(
+          result.data,
+          schema,
+          "Invalid #{schema_type} structure from #{service_class.name}"
+        )
 
         result
       end
 
+      # 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
+      end
+
       # Validates event payload against the handler's payload schema.
       #
       # @param handler_class [Class] the event handler class
@@ -103,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
@@ -179,19 +191,38 @@ module Servus
         @schema_cache
       end
 
-      # Resolves the appropriate schema for a result based on its success/failure state.
+      # Serializes data and validates it against a JSON schema.
       #
-      # @param service_class [Class] the service class
-      # @param result [Servus::Support::Response] the response to resolve schema for
-      # @return [Hash, nil] the schema, or nil if none applies
+      # @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.result_schema_for(service_class, result)
-        if result.success?
-          load_schema(service_class, 'result')
-        elsif result.data
-          load_schema(service_class, 'failure')
-        end
+      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.

data/lib/servus/testing/example_builders.rb

@@ -138,6 +138,58 @@ module Servus
         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.3.0'
+  VERSION = '0.4.0'
 end

data/lib/servus.rb

@@ -25,6 +25,7 @@ require_relative 'servus/support/response'
 require_relative 'servus/support/validator'
 require_relative 'servus/support/errors'
 require_relative 'servus/support/rescuer'
+require_relative 'servus/support/lockdown'
 require_relative 'servus/support/message_resolver'
 
 # Events

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Sebastian Scholl
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_model_serializers
@@ -74,114 +75,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/commands/check-docs.md"
-- ".claude/commands/consistency-check.md"
-- ".claude/commands/fine-tooth-comb.md"
-- ".claude/commands/red-green-refactor.md"
-- ".claude/settings.json"
-- ".rspec"
-- ".rubocop.yml"
-- ".yardopts"
-- CHANGELOG.md
-- CLAUDE.md
-- IDEAS.md
-- LICENSE.txt
-- READme.md
-- Rakefile
-- docs/core/1_overview.md
-- docs/core/2_architecture.md
-- docs/core/3_service_objects.md
-- docs/features/1_schema_validation.md
-- docs/features/2_error_handling.md
-- docs/features/3_async_execution.md
-- docs/features/4_logging.md
-- docs/features/5_event_bus.md
-- docs/features/6_guards.md
-- docs/features/7_lazy_resolvers.md
-- docs/features/guards_naming_convention.md
-- docs/guides/1_common_patterns.md
-- docs/guides/2_migration_guide.md
-- docs/integration/1_configuration.md
-- docs/integration/2_testing.md
-- docs/integration/3_rails_integration.md
-- docs/yard/Servus.html
-- docs/yard/Servus/Base.html
-- docs/yard/Servus/Config.html
-- docs/yard/Servus/Extensions.html
-- docs/yard/Servus/Extensions/Async.html
-- docs/yard/Servus/Extensions/Async/Call.html
-- docs/yard/Servus/Extensions/Async/Errors.html
-- docs/yard/Servus/Extensions/Async/Errors/AsyncError.html
-- docs/yard/Servus/Extensions/Async/Errors/JobEnqueueError.html
-- docs/yard/Servus/Extensions/Async/Errors/ServiceNotFoundError.html
-- docs/yard/Servus/Extensions/Async/Ext.html
-- docs/yard/Servus/Extensions/Async/Job.html
-- docs/yard/Servus/Generators.html
-- docs/yard/Servus/Generators/ServiceGenerator.html
-- docs/yard/Servus/Helpers.html
-- docs/yard/Servus/Helpers/ControllerHelpers.html
-- docs/yard/Servus/Railtie.html
-- docs/yard/Servus/Support.html
-- docs/yard/Servus/Support/Errors.html
-- docs/yard/Servus/Support/Errors/AuthenticationError.html
-- docs/yard/Servus/Support/Errors/BadRequestError.html
-- docs/yard/Servus/Support/Errors/ForbiddenError.html
-- docs/yard/Servus/Support/Errors/InternalServerError.html
-- docs/yard/Servus/Support/Errors/NotFoundError.html
-- docs/yard/Servus/Support/Errors/ServiceError.html
-- docs/yard/Servus/Support/Errors/ServiceUnavailableError.html
-- docs/yard/Servus/Support/Errors/UnauthorizedError.html
-- docs/yard/Servus/Support/Errors/UnprocessableEntityError.html
-- docs/yard/Servus/Support/Errors/ValidationError.html
-- docs/yard/Servus/Support/Logger.html
-- docs/yard/Servus/Support/Rescuer.html
-- docs/yard/Servus/Support/Rescuer/BlockContext.html
-- docs/yard/Servus/Support/Rescuer/CallOverride.html
-- docs/yard/Servus/Support/Rescuer/ClassMethods.html
-- docs/yard/Servus/Support/Response.html
-- docs/yard/Servus/Support/Validator.html
-- docs/yard/Servus/Testing.html
-- docs/yard/Servus/Testing/ExampleBuilders.html
-- docs/yard/Servus/Testing/ExampleExtractor.html
-- docs/yard/_index.html
-- docs/yard/class_list.html
-- docs/yard/css/common.css
-- docs/yard/css/full_list.css
-- docs/yard/css/style.css
-- docs/yard/file.1_common_patterns.html
-- docs/yard/file.1_configuration.html
-- docs/yard/file.1_overview.html
-- docs/yard/file.1_schema_validation.html
-- docs/yard/file.2_architecture.html
-- docs/yard/file.2_error_handling.html
-- docs/yard/file.2_migration_guide.html
-- docs/yard/file.2_testing.html
-- docs/yard/file.3_async_execution.html
-- docs/yard/file.3_rails_integration.html
-- docs/yard/file.3_service_objects.html
-- docs/yard/file.4_logging.html
-- docs/yard/file.ErrorHandling.html
-- docs/yard/file.READme.html
-- docs/yard/file.architecture.html
-- docs/yard/file.async_execution.html
-- docs/yard/file.common_patterns.html
-- docs/yard/file.configuration.html
-- docs/yard/file.error_handling.html
-- docs/yard/file.logging.html
-- docs/yard/file.migration_guide.html
-- docs/yard/file.overview.html
-- docs/yard/file.rails_integration.html
-- docs/yard/file.schema_validation.html
-- docs/yard/file.service_objects.html
-- docs/yard/file.testing.html
-- docs/yard/file_list.html
-- docs/yard/frames.html
-- docs/yard/index.html
-- docs/yard/js/app.js
-- docs/yard/js/full_list.js
-- docs/yard/js/jquery.js
-- docs/yard/method_list.html
-- docs/yard/top-level-namespace.html
 - lib/generators/servus/event_handler/event_handler_generator.rb
 - lib/generators/servus/event_handler/templates/handler.rb.erb
 - lib/generators/servus/event_handler/templates/handler_spec.rb.erb
@@ -218,6 +111,7 @@ files:
 - lib/servus/railtie.rb
 - lib/servus/support/data_object.rb
 - lib/servus/support/errors.rb
+- lib/servus/support/lockdown.rb
 - lib/servus/support/logger.rb
 - lib/servus/support/message_resolver.rb
 - lib/servus/support/rescuer.rb
@@ -237,6 +131,7 @@ metadata:
   source_code_uri: https://github.com/zarpay/servus
   changelog_uri: https://github.com/zarpay/servus/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -251,7 +146,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: A gem for managing service objects.
 test_files: []

data/.claude/commands/check-docs.md

@@ -1 +0,0 @@
-Scan the documentation in docs/ then check the current git changeset. If the changeset has modifications that might affect the documentation, then review the related documentation and make any necessary updates.

data/.claude/commands/consistency-check.md

@@ -1 +0,0 @@
-Are the latest changes consistent with the way that similar functionality has been implemented in the rest of the codebase? #$ARGUMENTS

data/.claude/commands/fine-tooth-comb.md

@@ -1 +0,0 @@
-We're going to go over #$ARGUMENTS with a fine-tooth comb. I want detailed explanations and no edits unless I ask for them. Start by identifying the first thing that looks wrong and explain why.

data/.claude/commands/red-green-refactor.md

@@ -1,5 +0,0 @@
-During this session we will be practicing TDD in the red-green-refactor cycle. The first step in the cycle is to write a test for the smallest possible unit of functionality. Once the test is written, run the test and it should fail. This is the red phase. The next step is to write the code to make the test pass. This is the green phase. Once the test passes, the code is refactored to be more readable and maintainable. This is the refactor phase.
-
-If we get into a situation where more than one test fails, we will focus on the test that is most important to fix first. During that fix phase, we will only run the test that is failing until it passes.
-
-While we're in this mode, you will not use your TODO tool to track tasks. You will rely on me (the human user) to tell you what the next step is.

data/.claude/settings.json

@@ -1,24 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(bundle exec rspec:*)",
-      "Bash(bundle exec rubocop:*)",
-      "Bash(find:*)"
-    ],
-    "deny": [],
-    "ask": []
-  },
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bundle exec rubocop -A"
-          }
-        ]
-      }
-    ]
-  }
-}

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,27 +0,0 @@
-AllCops:
-  NewCops: enable
-  TargetRubyVersion: 3.3
-  Include:
-    - 'lib/**/*.rb'
-    - 'spec/**/*.rb'
-  Exclude:
-    - 'spec/dummy/**/*'
-    - 'vendor/bundle/**/*'
-
-Lint/ConstantDefinitionInBlock:
-  Enabled: false
-
-Lint/ConstantReassignment:
-  Exclude:
-    - 'spec/**/*'
-
-Lint/MissingSuper:
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/BlockLength:
-  Exclude:
-    - 'spec/**/*'
-
-Naming/PredicateMethod:
-  Enabled: false

data/.yardopts

@@ -1,6 +0,0 @@
---output-dir ./docs/yard
---readme READme.md
---files docs/**/*.md
---markup markdown
---markup-provider redcarpet
---title "Servus | Service Object Framework"