servus 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f63266b1efb1e782745c67d24957ce1126b1031592667bd78fe80f5ed2c93ac7
-  data.tar.gz: 64d263185dc9214707aafc7eaaf740343e5c24311eec49db6bbccff25fa413a9
+  metadata.gz: 58e6098b9ea316c670b5b8aa6f61828d961cc3c8ad6e72357d71c442dfe75151
+  data.tar.gz: 215f0f790ad36575b0b9de3f956cf585f19051c16d5250ada1ae152a969dd1d7
 SHA512:
-  metadata.gz: a6d3ff24ec58b33b926acca83447ede76c1feb54daab1ade3b4a744f66e70a87785b68d6e235934b6b20f6477e7518441486bb6d405f34cd8bfb2334c095122e
-  data.tar.gz: 5f562d3cac4a258387fab0936d8fecb41e9e42803556014d91c5802f0b27f6b5cd2a085f76b4d0d486c609f2589c286d5fe13fbd4be34270f4ecc104d2b478a1
+  metadata.gz: 48142cd74cbd766846ccd9d8bf4a71a8d67136cbd60bdc948ddda6a0fa99f7e6072351b6ff98958500a6d84e49d1cb7d122e8e435efeb8b1384d39a4be9932ad
+  data.tar.gz: 13899ee4220e2e25b888eae9b6675a77780770628717bc11a2abda9bdd82e49b0798d70c954f91e5649a3bc281d9b3ad0e50dce41374f3c2ebc42125d7321848

data/CHANGELOG.md

@@ -1,3 +1,50 @@
+## [0.3.0] - 2026-04-03
+
+### Breaking Changes
+
+- **Failure responses can now carry data**: `failure()` accepts an optional `data:` kwarg. Previously,
+  `result.data` was guaranteed to be `nil` on failure. Code that checks `result.data` for truthiness
+  to determine success/failure must switch to `result.success?` or `result.failure?`.
+  See the [Migration Guide](docs/guides/2_migration_guide.md#migrating-to-030) for details.
+- **`Response#with_data` removed**: Replaced by the `data:` kwarg on `failure()`. The `with_data` method
+  allowed arbitrary mutation of responses after creation, bypassing schema validation.
+
+### Added
+
+- **`lazily` resolver DSL**: Declare lazy record resolvers on services with `lazily :user, finds: User`.
+  Accepts either an ID or an already-loaded instance — resolves on first access, memoizes the result.
+  Supports custom columns (`by: :uuid`), array input (via `.where`), and dry-initializer compatibility.
+  Loaded as an extension via Railtie when ActiveRecord is present.
+- **Failure data support**: `failure()` accepts an optional `data:` keyword argument for attaching
+  structured data to failure responses (e.g., `failure("Declined", data: { reason: "insufficient_funds" })`).
+  Defaults to `nil` for backwards compatibility with services that don't use it.
+- **Failure schema validation**: Define a `failure` schema via the `schema` DSL, `FAILURE_SCHEMA` constant,
+  or `failure.json` file. When present, failure response data is validated against it — just like success
+  results are validated against `result` schemas.
+- **`servus_failure_example` test helper**: Extracts example values from a service's `failure` schema,
+  returning a failure `Response` for use in tests.
+- **`failure?` predicate on Response**: Complement to `success?` for cleaner conditional handling.
+- **`DataObject` wrapper for response data**: Hash data returned by services is wrapped in a read-only
+  `DataObject` that supports accessor-style access (`result.data.user.email`) alongside bracket access
+  (`result.data[:user]`). Nested Hashes and Hashes inside Arrays are recursively wrapped. Non-Hash values
+  (models, nil) pass through unwrapped.
+
+## [0.2.1] - 2025-12-20
+
+### Added
+
+- **EventHandler Scheduling Options**: Extended the `invoke` DSL to support ActiveJob scheduling options
+  - `:wait` - delay execution (e.g., `5.minutes`)
+  - `:wait_until` - schedule for specific time
+  - `:priority` - job priority
+  - `:job_options` - additional ActiveJob options
+  - Options are passed through to `call_async`, enabling delayed and scheduled event handling
+
+- **Custom HTTP Error Classes**: Added granular error classes for HTTP status handling
+  - Error classes for common HTTP statuses (400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504)
+  - Each error class has appropriate `http_status` and default `code`/`message`
+  - Enables more precise error handling and cleaner rescue blocks
+
 ## [0.2.0] - 2025-12-16
 
 ### Added
@@ -85,21 +132,37 @@
 - Enhanced Railtie to auto-load event handlers and clear the event bus on reload in development
 
 ## [0.1.4] - 2025-11-21
-- Added: Test helpers (`servus_arguments_example` and `servus_result_example`) to extract example values from schemas for testing
-- Added: YARD documentation configuration with README homepage and markdown file support
-- Added: Added `schema` DSL method for cleaner schema definition. Supports `schema arguments: {...}, result: {...}` syntax. Fully backwards compatible with existing `ARGUMENTS_SCHEMA` and `RESULT_SCHEMA` constants.
-- Added: Added support from blocks on `rescue_from` to override default failure handler.
-- Fixed: YARD link resolution warnings in documentation
+
+### Added
+
+- **Schema DSL method**: `schema arguments: {...}, result: {...}` syntax for cleaner schema definition.
+  Fully backwards compatible with existing `ARGUMENTS_SCHEMA` and `RESULT_SCHEMA` constants.
+- **Test helpers**: `servus_arguments_example` and `servus_result_example` for extracting example values
+  from schemas in tests
+- **`rescue_from` block support**: Override the default failure handler with a custom block
+- **YARD documentation**: Configuration with README homepage and markdown file support
+
+### Fixed
+
+- YARD link resolution warnings in documentation
 
 ## [0.1.3] - 2025-10-10
-- Added: Added `call_async` method to `Servus::Base` to enqueue a job for calling the service asynchronously
-- Added: Added `Async::Job` to handle async enqueing with support for ActiveJob set options
+
+### Added
+
+- **`call_async`**: Enqueue service calls as background jobs via ActiveJob
+- **`Async::Job`**: Job class for async enqueueing with support for ActiveJob `set` options
 
 ## [0.1.1] - 2025-08-20
 
-- Added: Added `rescue_from` method to `Servus::Base` to rescue from standard errors and use custom error types.
-- Added: Added `run_service` and `render_service_object_error` helpers to `Servus::Helpers::ControllerHelpers`.
-- Fixed: All rubocop warnings.
+### Added
+
+- **`rescue_from`**: Rescue from standard errors and convert them to failure responses with custom error types
+- **Controller helpers**: `run_service` and `render_service_object_error` in `Servus::Helpers::ControllerHelpers`
+
+### Fixed
+
+- All rubocop warnings
 
 ## [0.1.0] - 2025-04-28
 

data/docs/core/1_overview.md

@@ -39,11 +39,15 @@ Services return `Response` objects instead of raising exceptions for business fa
 ```ruby
 result = SomeService.call(params)
 if result.success?
-  result.data  # Hash or object returned by success()
+  result.data            # DataObject wrapping the success data
+  result.data[:user]     # bracket access
+  result.data.user       # accessor access
+  result.data.user.email # nested accessor access
 else
-  result.error # ServiceError instance
+  result.error           # ServiceError instance
   result.error.message
   result.error.api_error # { code: :symbol, message: "string" }
+  result.data            # optional failure data (nil unless data: kwarg was used)
 end
 ```
 

data/docs/core/3_service_objects.md

@@ -35,6 +35,39 @@ result.success? # => true
 result.data[:user] # => #<User>
 ```
 
+## Accessing Response Data
+
+Response data can be accessed with bracket syntax or accessor-style methods. Both are fully supported — use whichever reads better in context.
+
+```ruby
+result = Users::Create::Service.call(email: "user@example.com", name: "John")
+
+# Bracket access
+result.data[:user]          # => #<User>
+result.data[:user].email    # => "user@example.com"
+
+# Accessor access
+result.data.user            # => #<User>
+result.data.user.email      # => "user@example.com"
+```
+
+Nested Hashes are wrapped automatically, so accessor chains work at any depth:
+
+```ruby
+result = Orders::Create::Service.call(items: [...])
+
+result.data.order.shipping.address.city  # => "Berlin"
+result.data[:order][:shipping]           # also works
+```
+
+Arrays of Hashes are also wrapped, so you can access elements naturally:
+
+```ruby
+result.data.order.items.first.sku   # => "A1"
+```
+
+Non-Hash values like model instances, strings, and integers pass through unchanged — accessor access on those values uses the object's own methods.
+
 ## Service Composition
 
 Services can call other services. Use the returned Response to decide whether to continue or propagate the failure.

data/docs/features/1_schema_validation.md

@@ -28,6 +28,12 @@ class ProcessPayment::Service < Servus::Base
         transaction_id: { type: "string", example: "txn_abc123" },
         new_balance: { type: "number", example: 950.0 }
       }
+    },
+    failure: {
+      type: "object",
+      properties: {
+        reason: { type: "string", example: "insufficient_funds" }
+      }
     }
   )
 end
@@ -73,6 +79,13 @@ class ProcessPayment::Service < Servus::Base
       new_balance: { type: "number" }
     }
   }.freeze
+
+  FAILURE_SCHEMA = {
+    type: "object",
+    properties: {
+      reason: { type: "string" }
+    }
+  }.freeze
 end
 ```
 
@@ -81,12 +94,13 @@ end
 For complex schemas, use JSON files instead of inline definitions. Create files at:
 - `app/schemas/services/service_name/arguments.json`
 - `app/schemas/services/service_name/result.json`
+- `app/schemas/services/service_name/failure.json`
 
 ### Schema Lookup Precedence
 
 Servus checks for schemas in this order:
 1. **schema DSL method** (if defined)
-2. **Inline constants** (ARGUMENTS_SCHEMA, RESULT_SCHEMA)
+2. **Inline constants** (ARGUMENTS_SCHEMA, RESULT_SCHEMA, FAILURE_SCHEMA)
 3. **JSON files** (in schema_root directory)
 
 Schemas are cached after first load for performance.
@@ -101,6 +115,34 @@ Schemas are cached after first load for performance.
 
 Each layer has a different purpose - don't duplicate validation across layers.
 
+## Failure Data Validation
+
+Services can optionally attach structured data to failure responses using the `data:` keyword argument on `failure()`. When a `failure` schema is defined, this data is validated against it — just like success results are validated against `result` schemas.
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  schema(
+    failure: {
+      type: "object",
+      required: ["reason"],
+      properties: {
+        reason: { type: "string" },
+        decline_code: { type: "string" }
+      }
+    }
+  )
+
+  def call
+    return failure("Card declined", data: { reason: "insufficient_funds", decline_code: "do_not_honor" })
+  end
+end
+```
+
+Failure data validation is skipped when:
+- No `failure` schema is defined
+- The failure response has no data (`data: nil`, the default)
+- The response is a success
+
 ## Configuration
 
 Change the schema file location if needed:

data/docs/features/2_error_handling.md

@@ -29,6 +29,14 @@ def call
 end
 ```
 
+Failures can optionally carry structured data using the `data:` keyword argument. When a `failure` schema is defined on the service, this data is validated against it.
+
+```ruby
+def call
+  return failure("Approval required", data: { requires_human_approval: true, ai_approved: true })
+end
+```
+
 ## Error Classes
 
 All error classes inherit from `ServiceError` and map to HTTP status codes. Use them for API-friendly errors.
@@ -101,7 +109,7 @@ class ProcessPayment::Service < Servus::Base
 end
 ```
 
-The block has access to `success(data)` and `failure(message, type:)` methods. This allows conditional error handling and even recovering from exceptions.
+The block has access to `success(data)` and `failure(message, data:, type:)` methods. This allows conditional error handling and even recovering from exceptions.
 
 ## Custom Errors
 

data/docs/features/7_lazy_resolvers.md

@@ -0,0 +1,238 @@
+# @title Features / 7. Lazy Resolvers
+
+# Lazy Resolvers
+
+Services often accept record IDs as inputs and query for the record inside `call`. This is necessary for async execution — ActiveJob serializes arguments, so you can't pass ActiveRecord objects through a job. But when calling synchronously with an already-loaded record, re-querying is wasteful.
+
+The `lazily` DSL solves this. A service declares what records it needs, and the resolver handles both cases transparently: pass an ID and it queries; pass an instance and it skips the query.
+
+## The Problem
+
+Without `lazily`, you write this pattern repeatedly:
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  def initialize(user_id:, amount:)
+    @user_id = user_id
+    @amount = amount
+  end
+
+  def call
+    user = User.find(@user_id)  # Always queries, even if caller had the record
+    # ...
+  end
+end
+```
+
+The caller can't pass a loaded record — `user_id:` expects an integer. And if you change the param to `user:`, it breaks async execution.
+
+## Basic Usage
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  lazily :user, finds: User
+
+  def initialize(user:, amount:)
+    @user = user
+    @amount = amount
+  end
+
+  def call
+    return failure("Insufficient funds") unless user.balance >= @amount
+
+    user.update!(balance: user.balance - @amount)
+    success(user: user, new_balance: user.balance)
+  end
+end
+```
+
+The param is named `user:` — callers pass whatever they have:
+
+```ruby
+# Sync with a loaded record — no query
+ProcessPayment::Service.call(user: current_user, amount: 50)
+
+# Async with an ID — resolves via User.find(123)
+ProcessPayment::Service.call_async(user: user.id, amount: 50)
+
+# Sync with an ID — also works
+ProcessPayment::Service.call(user: 123, amount: 50)
+```
+
+## DSL Signature
+
+```ruby
+lazily :name, finds: ModelClass              # default: ModelClass.find(value)
+lazily :name, finds: ModelClass, by: :column # ModelClass.find_by!(column: value)
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `:name` | The keyword argument name and the accessor method name |
+| `finds:` | The model class constant (e.g., `User`, `Account`) |
+| `by:` | Lookup column. Defaults to `:id`. When set, uses `.find_by!` instead of `.find` |
+
+## Resolution Behavior
+
+The resolver checks the input type and acts accordingly:
+
+| Input | Behavior |
+|-------|----------|
+| Instance of target class | Returned directly — no query |
+| Integer, String, or other scalar | Resolved via `.find(value)` or `.find_by!(column: value)` |
+| Array | Resolved via `.where(column => values)` |
+| `nil` | Raises `NotFoundError` immediately |
+
+Resolution is **lazy** — it only happens when the accessor method is first called inside `call`, not during `initialize`. If a service never calls the accessor, no query is made.
+
+Resolution is **memoized** — the resolved record is written back to the instance variable. Subsequent calls return the same object without re-querying.
+
+## Custom Column Lookup
+
+Use `by:` to look up by a column other than `:id`:
+
+```ruby
+class FindAccount::Service < Servus::Base
+  lazily :account, finds: Account, by: :uuid
+
+  def initialize(account:)
+    @account = account
+  end
+
+  def call
+    success(account: account)
+  end
+end
+
+# Resolves via Account.find_by!(uuid: "abc-def-123")
+FindAccount::Service.call(account: "abc-def-123")
+
+# Passes through an Account instance directly
+FindAccount::Service.call(account: loaded_account)
+```
+
+The `by:` column accepts any value type — strings, integers, UUIDs — whatever the column expects.
+
+## Array Input
+
+When the input is an Array, the resolver uses `.where` instead of `.find`:
+
+```ruby
+class BulkNotify::Service < Servus::Base
+  lazily :users, finds: User
+
+  def initialize(users:, message:)
+    @users = users
+    @message = message
+  end
+
+  def call
+    users.each { |u| notify(u, @message) }
+    success(notified: users.count)
+  end
+end
+
+# Resolves via User.where(id: [1, 2, 3])
+BulkNotify::Service.call(users: [1, 2, 3], message: "Hello")
+```
+
+Arrays with a custom `by:` column use `.where(column => values)`.
+
+Empty arrays return an empty relation — no error is raised.
+
+## Multiple Resolvers
+
+A service can declare multiple resolvers. Each resolves independently and memoizes separately:
+
+```ruby
+class TransferFunds::Service < Servus::Base
+  lazily :sender, finds: User
+  lazily :receiver, finds: User
+  lazily :account, finds: Account, by: :uuid
+
+  def initialize(sender:, receiver:, account:, amount:)
+    @sender = sender
+    @receiver = receiver
+    @account = account
+    @amount = amount
+  end
+
+  def call
+    # Each resolver triggers independently on first access
+    success(from: sender.name, to: receiver.name, account: account.uuid)
+  end
+end
+```
+
+## Error States
+
+### Nil Input
+
+Raises `Servus::Extensions::Lazily::Errors::NotFoundError` immediately. The error message includes the param name and target class:
+
+```
+Couldn't find User (user was nil)
+```
+
+This is always a bug at the call site — the resolver never silently returns nil.
+
+### Missing Record
+
+`.find` and `.find_by!` raise `ActiveRecord::RecordNotFound` as usual. The resolver does not catch or wrap these errors — they propagate normally.
+
+```ruby
+# Raises ActiveRecord::RecordNotFound: Couldn't find User with 'id'=999
+ProcessPayment::Service.call(user: 999, amount: 50)
+```
+
+Use `rescue_from` if you want to convert these to failure responses:
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  lazily :user, finds: User
+  rescue_from ActiveRecord::RecordNotFound, use: NotFoundError
+
+  # ...
+end
+```
+
+### Empty Array
+
+Returns an empty ActiveRecord relation. No error is raised — this is intentional for batch operations where an empty set is valid.
+
+## Async Compatibility
+
+The `lazily` pattern is designed for services that run both synchronously and asynchronously:
+
+```ruby
+# Controller (sync) — pass the loaded record
+def create
+  run_service(ProcessPayment::Service, user: current_user, amount: params[:amount])
+end
+
+# Background job (async) — pass the ID
+ProcessPayment::Service.call_async(user: user.id, amount: 50)
+```
+
+Both paths use the same service code. The resolver handles the difference.
+
+## dry-initializer Compatibility
+
+`lazily` works alongside dry-initializer. The resolver defines its accessor on a prepended module, which takes priority over dry-initializer's generated method. It reads from the `@name` instance variable that dry-initializer sets:
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  option :user
+  option :amount
+
+  lazily :user, finds: User
+
+  def call
+    success(user: user, charged: amount)
+  end
+end
+```
+
+## Requirements
+
+`lazily` is an ActiveRecord extension. It loads automatically via Railtie when ActiveRecord is present in your application. It is not available in pure Ruby applications without ActiveRecord.

data/docs/guides/2_migration_guide.md

@@ -2,7 +2,57 @@
 
 # Migration Guide
 
-Strategies for adopting Servus in existing Rails applications.
+Strategies for adopting Servus in existing Rails applications, and version-specific migration notes.
+
+## Migrating to 0.3.0
+
+### Breaking: `result.data` is no longer guaranteed nil on failure
+
+In 0.2.x, `failure()` always set `result.data` to `nil`. Some code relied on this to distinguish success from failure:
+
+```ruby
+# ❌ Unsafe in 0.3.0 — result.data can be non-nil on failure
+if result.data
+  # handle success
+else
+  # handle failure
+end
+```
+
+In 0.3.0, `failure()` accepts an optional `data:` kwarg, so failure responses can carry structured data. Use `result.success?` or `result.failure?` instead:
+
+```ruby
+# ✅ Correct — always use success? or failure?
+if result.success?
+  render json: result.data, status: :ok
+else
+  render json: { error: result.error.api_error, details: result.data }, status: result.error.http_status
+end
+```
+
+**How to find affected code**: Search your codebase for patterns like `if result.data`, `result.data.present?`, or `result.data.nil?` used as success/failure checks. Replace them with `result.success?` or `result.failure?`.
+
+### Removed: `Response#with_data`
+
+`with_data` was removed in favor of the `data:` kwarg on `failure()`:
+
+```ruby
+# ❌ 0.2.x — no longer available
+failure("Declined").tap { |r| r.with_data(reason: "insufficient_funds") }
+
+# ✅ 0.3.0
+failure("Declined", data: { reason: "insufficient_funds" })
+```
+
+### New: DataObject wrapping
+
+Response data is now wrapped in a `DataObject` when it is a Hash. This is backwards compatible — `result.data[:key]` still works. You can also use accessor-style access:
+
+```ruby
+result.data[:user]       # still works
+result.data.user         # also works (new)
+result.data.user.email   # nested access (new)
+```
 
 ## Incremental Adoption
 

data/docs/integration/2_testing.md

@@ -42,6 +42,13 @@ class ProcessPayment::Service < Servus::Base
         transaction_id: { type: "string", example: "txn_abc123" },
         status: { type: "string", example: "approved" }
       }
+    },
+    failure: {
+      type: "object",
+      properties: {
+        reason: { type: "string", example: "card_declined" },
+        decline_code: { type: "string", example: "insufficient_funds" }
+      }
     }
   )
 end
@@ -64,6 +71,15 @@ RSpec.describe ProcessPayment::Service do
     )
   end
 
+  it "returns structured failure data on decline" do
+    args = servus_arguments_example(ProcessPayment::Service, amount: 999_999)
+    result = ProcessPayment::Service.call(**args)
+
+    expected = servus_failure_example(ProcessPayment::Service)
+    expect(result).to be_failure
+    expect(result.data.keys).to match_array(expected.data.keys)
+  end
+
   it "handles different currencies" do
     %w[USD EUR GBP].each do |currency|
       result = ProcessPayment::Service.call(
@@ -91,7 +107,8 @@ args = servus_arguments_example(
 ### Available Helpers
 
 - `servus_arguments_example(ServiceClass, **overrides)` - Returns hash of argument examples
-- `servus_result_example(ServiceClass, **overrides)` - Returns Response object with result examples
+- `servus_result_example(ServiceClass, **overrides)` - Returns successful Response with result examples
+- `servus_failure_example(ServiceClass, **overrides)` - Returns failure Response with failure schema examples
 
 ## Basic Testing Pattern
 

data/lib/servus/base.rb

@@ -88,6 +88,8 @@ module Servus
     # The failure is logged automatically and returns a response containing the error.
     #
     # @param message [String, nil] custom error message (uses error type's default if nil)
+    # @param data [Object, nil] optional structured data to attach to the failure response.
+    #   When a +failure+ schema is defined, this data will be validated against it.
     # @param type [Class] error class to instantiate (must inherit from ServiceError)
     # @return [Servus::Support::Response] response with success: false and the error
     #
@@ -109,12 +111,17 @@ module Servus
     #     # Uses "Not found" as the message
     #   end
     #
+    # @example Attaching structured data to a failure
+    #   def call
+    #     return failure("Approval required", data: { requires_human_approval: true })
+    #   end
+    #
     # @see #success
     # @see #error!
     # @see Servus::Support::Errors
-    def failure(message = nil, type: Servus::Support::Errors::ServiceError)
+    def failure(message = nil, data: nil, type: Servus::Support::Errors::ServiceError)
       error = type.new(message)
-      Response.new(false, nil, error)
+      Response.new(false, data, error)
     end
 
     # Logs an error and raises an exception, halting service execution.
@@ -207,15 +214,16 @@ module Servus
       end
       # rubocop:enable Metrics/MethodLength
 
-      # Defines schema validation rules for the service's arguments and/or result.
+      # Defines schema validation rules for the service's arguments, result, and/or failure data.
       #
       # This method provides a clean DSL for specifying JSON schemas that will be used
       # to validate service inputs and outputs. Schemas defined via this method take
-      # precedence over ARGUMENTS_SCHEMA and RESULT_SCHEMA constants. The next major
-      # version will deprecate those constants in favor of this DSL.
+      # precedence over ARGUMENTS_SCHEMA, RESULT_SCHEMA, and FAILURE_SCHEMA constants.
+      # The next major version will deprecate those constants in favor of this DSL.
       #
       # @param arguments [Hash, nil] JSON schema for validating service arguments
       # @param result [Hash, nil] JSON schema for validating service result data
+      # @param failure [Hash, nil] JSON schema for validating failure response data
       # @return [void]
       #
       # @example Defining both arguments and result schemas
@@ -245,9 +253,10 @@ module Servus
       #   end
       #
       # @see Servus::Support::Validator
-      def schema(arguments: nil, result: nil)
+      def schema(arguments: nil, result: nil, failure: nil)
         @arguments_schema = arguments.with_indifferent_access if arguments
         @result_schema    = result.with_indifferent_access    if result
+        @failure_schema   = failure.with_indifferent_access   if failure
       end
 
       # Returns the arguments schema defined via the schema DSL method.
@@ -262,6 +271,12 @@ module Servus
       # @api private
       attr_reader :result_schema
 
+      # Returns the failure schema defined via the schema DSL method.
+      #
+      # @return [Hash, nil] the failure schema or nil if not defined
+      # @api private
+      attr_reader :failure_schema
+
       # Executes pre-call hooks including logging and argument validation.
       #
       # This method is automatically called before service execution and handles: