Servus

https://github.com/zarpay/servus
Admin
Servus is a Ruby gem that provides a disciplined service-object pattern with validation, error...
Tokens:35,865
Snippets:417
Trust Score:7
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Generate Service Arguments from Schema Examples

Source: https://context7.com/zarpay/servus/llms.txt

Utilize `servus_arguments_example` to generate arguments for service calls based on schema examples, allowing for custom values.

```ruby
it 'processes with schema example arguments' do
  args = servus_arguments_example(described_class, email: 'custom@example.com')
  result = described_class.call(**args)

  expect(result).to be_success
end
```

--------------------------------

### Define Schema for Servus Examples

Source: https://github.com/zarpay/servus/blob/main/site/testing/services.md

Define schema properties with `example` or `examples` to generate sample arguments and results. This is useful for services handling scalar values.

```ruby
schema(
  arguments: {
    type: "object",
    properties: {
      from_account: { type: "integer", example: 1 },
      to_account: { type: "integer", example: 2 },
      gold_dragons: { type: "integer", example: 50 }
    }
  },
  result: {
    type: "object",
    properties: {
      transferred: { type: "number", example: 50 },
      from_balance: { type: "number", example: 950 },
      to_balance: { type: "number", example: 550 }
    }
  }
)
```

--------------------------------

### Generate Service Arguments Example

Source: https://github.com/zarpay/servus/blob/main/site/features/schema-validation.md

Use `servus_arguments_example` to generate a hash of valid arguments for a service, optionally overriding specific values.

```ruby
# In a controller spec — need to call the service with valid args
args = servus_arguments_example(Treasury::TransferGold::Service, gold_dragons: 100)
# => { from_account: 1, to_account: 2, gold_dragons: 100 }
```

--------------------------------

### Install Servus Gem

Source: https://github.com/zarpay/servus/blob/main/site/getting-started/index.md

Install the Servus gem after adding it to your Gemfile.

```bash
bundle install
```

--------------------------------

### Extract Result Examples with Servus

Source: https://github.com/zarpay/servus/blob/main/site/testing/services.md

Use `servus_result_example` to get a successful `Response` object populated with example data from the schema. Useful for mocking.

```ruby
expected = servus_result_example(Treasury::TransferGold::Service)
# => Response(success: true, data: { transferred: 50, from_balance: 950, to_balance: 550 })

allow(Treasury::TransferGold::Service).to receive(:call).and_return(expected)
```

--------------------------------

### Extract Argument Examples with Servus

Source: https://github.com/zarpay/servus/blob/main/site/testing/services.md

Use `servus_arguments_example` to extract sample arguments from a service's schema. You can override specific values.

```ruby
args = servus_arguments_example(Treasury::TransferGold::Service)
# => { from_account: 1, to_account: 2, gold_dragons: 50 }

args = servus_arguments_example(Treasury::TransferGold::Service, gold_dragons: 100)
# => { from_account: 1, to_account: 2, gold_dragons: 100 }
```

```ruby
args = servus_arguments_example(
  Ravens::DispatchMessage::Service,
  destination: { castle: "Winterfell", urgency: :critical }
)
# => { rookery: 1, destination: { castle: "Winterfell", region: "North", urgency: :critical } }
#    ↑ region came from the schema example, urgency was overridden
```

--------------------------------

### Generated Service with Parameters

Source: https://github.com/zarpay/servus/blob/main/site/reference/generators.md

This is an example of a generated service class that includes parameters for its initialization method. Ensure all required parameters are passed during instantiation.

```ruby
# app/services/treasury/transfer_gold/service.rb
module Treasury::TransferGold
  class Service < Servus::Base
    def initialize(from_account:, to_account:, gold_dragons:)
      @from_account = from_account
      @to_account = to_account
      @gold_dragons = gold_dragons
    end

    def call
      # TODO: Implement service logic here
      success({})
    end

    private

    attr_reader :from_account, :to_account, :gold_dragons
  end
end
```

--------------------------------

### Verify Service Result Structure with Schema Examples

Source: https://context7.com/zarpay/servus/llms.txt

Use `servus_result_example` to obtain the expected structure of a service's successful result based on its schema.

```ruby
it 'returns expected result structure' do
  result = described_class.call(email: 'test@example.com', name: 'Test')
  expected = servus_result_example(described_class)

  expect(result.data.keys).to match_array(expected.data.keys)
end
```

--------------------------------

### Servus Configuration

Source: https://github.com/zarpay/servus/blob/main/site/features/guards.md

Example of configuring Servus, including options to disable built-in guards and specify the directory for custom guards.

```ruby
Servus.configure do |config|
  config.include_default_guards = false  # disable built-in guards (default: true)
  config.guards_dir = 'app/guards'       # where custom guards live (default: 'app/guards')
end
```

--------------------------------

### Service Composition Example in Ruby

Source: https://github.com/zarpay/servus/blob/main/site/core/service-objects.md

Demonstrates how one service can call another, handling success and failure responses. It's recommended to return failed downstream responses unchanged unless there's a specific reason to translate them.

```ruby
def call
  reserve = Treasury::ReserveFunds::Service.call(account: @account, amount: @amount)
  return reserve unless reserve.success?

  dispatch = Ravens::DispatchReceipt::Service.call(transfer: reserve.data.transfer_id)
  return dispatch unless dispatch.success?

  success(transfer: reserve.data, receipt: dispatch.data)
end
```

--------------------------------

### Setup Servus Testing in RSpec

Source: https://github.com/zarpay/servus/blob/main/site/testing/services.md

Include Servus testing helpers and RSpec matchers for service testing. This setup is required for all service tests.

```ruby
# spec/spec_helper.rb
require 'servus/testing'

RSpec.configure do |config|
  config.include Servus::Testing::ExampleBuilders
end
```

--------------------------------

### Call a Servus Service and Handle Responses

Source: https://github.com/zarpay/servus/blob/main/site/index.md

This example shows how to invoke a Servus service using `.call` and how to interpret the `Response` object. It demonstrates checking for success and accessing data on success, or accessing error information on failure.

```ruby
result = Treasury::TransferGold::Service.call(from_account: 1, to_account: 2, gold_dragons: 50)

puts result.success?          # => true
puts result.data.transferred  # => 50
puts result.data.from_balance # => 950
puts result.data.to_balance   # => 550

# Business failure
result = Treasury::TransferGold::Service.call(from_account: 1, to_account: 1, gold_dragons: 50)

puts result.success?       # => false
puts result.error.message  # => "Cannot transfer to the same account"
```

--------------------------------

### Servus Failure Example

Source: https://github.com/zarpay/servus/blob/main/site/testing/services.md

Returns a failure Response with a failure schema. Use this to mock service failures.

```ruby
expected = servus_failure_example(Treasury::TransferGold::Service)
# => Response(success: false, data: { reason: "insufficient_funds" })

allow(Treasury::TransferGold::Service).to receive(:call).and_return(expected)
```

--------------------------------

### Generated Service without Parameters

Source: https://github.com/zarpay/servus/blob/main/site/reference/generators.md

This is an example of a generated service class that does not require any parameters during initialization. The `initialize` method should be updated to set up necessary instance variables.

```ruby
# app/services/treasury/transfer_gold/service.rb
module Treasury::TransferGold
  class Service < Servus::Base
    def initialize
      # TODO: Initialize instance variables
    end

    def call
      # TODO: Implement service logic here
      success({})
    end

    private

    # TODO: Add attr_readers for instance variables
  end
end
```

--------------------------------

### Generated Event Handler

Source: https://github.com/zarpay/servus/blob/main/site/reference/generators.md

This is an example of a generated event handler class. It specifies the event it handles using `handles` and includes a placeholder for defining the event payload schema. You can uncomment and adapt the `invoke` example to call other services.

```ruby
# app/events/gold_transferred_handler.rb
class GoldTransferredHandler < Servus::EventHandler
  handles :gold_transferred

  schema payload: {
    type: 'object',
    description: 'JSON schema for the GoldTransferredHandler event payload',
  }

  # invoke ExampleService, async: true do |payload|
  #   { example_arg: payload[:example_field] }
  # end
end
```

--------------------------------

### Custom Column Lookup Example

Source: https://github.com/zarpay/servus/blob/main/site/features/lazy-resolvers.md

Demonstrates using the `by:` option to specify a custom column (e.g., `:uuid`) for resolving records, applicable for both ID and instance inputs.

```ruby
lazily :account, finds: Account, by: :uuid

# Resolves via Account.find_by!(uuid: "abc-def-123")
Treasury::TransferGold::Service.call(account: "abc-def-123")

# Passes through an Account instance directly
Treasury::TransferGold::Service.call(account: loaded_account)
```

--------------------------------

### Define Service Schema with Arguments and Result

Source: https://github.com/zarpay/servus/blob/main/site/features/schema-validation.md

Define the schema for a service, including expected arguments and the structure of the result. Use 'description' and 'example' for documentation and test fixture generation.

```ruby
schema(
  arguments: {
    type: "object",
    properties: {
      from_account: {
        type: "integer",
        description: "The account ID to withdraw from",
        example: 1
      },
      to_account: {
        type: "integer",
        description: "The account ID to deposit into",
        example: 2
      },
      gold_dragons: {
        type: "integer",
        description: "The number of gold dragons to transfer",
        minimum: 1,
        examples: [50, 75, 100]
      }
    }
  },
  result: {
    type: "object",
    properties: {
      transferred: {
        type: "number",
        description: "The amount that was transferred",
        example: 50
      },
      from_balance: {
        type: "number",
        description: "The sender's balance after the transfer",
        example: 950
      },
      to_balance: {
        type: "number",
        description: "The receiver's balance after the transfer",
        example: 550
      }
    }
  }
)
```

--------------------------------

### Define a Servus Service Object

Source: https://github.com/zarpay/servus/blob/main/site/index.md

This example demonstrates the structure of a Servus service, including schema validation, lazy resolvers, event emission, guards, and the use of `success` and `failure` for responses. It requires inheriting from `Servus::Base` and defining `initialize` and `call` methods.

```ruby
module Treasury
  module TransferGold
    class Service < Servus::Base
      # Validate arguments before call, results after
      schema(
        arguments: {
          type: "object",
          required: ["from_account", "to_account", "gold_dragons"],
          properties: {
            from_account: { type: ["integer", "object"] },
            to_account: { type: ["integer", "object"] },
            gold_dragons: { type: "integer", minimum: 1 }
          }
        },
        result: {
          type: "object",
          required: ["transferred", "from_balance", "to_balance"],
          properties: {
            transferred: { type: "number" },
            from_balance: { type: "number" },
            to_balance: { type: "number" }
          }
        }
      )

      # Fire an event for handlers to pick up
      emits :gold_transferred, on: :success

      # Accept an Account instance or an ID — resolve lazily
      lazily :from_account, finds: Account
      lazily :to_account, finds: Account

      def initialize(from_account:, to_account:, gold_dragons:)
        @from_account = from_account
        @to_account = to_account
        @gold_dragons = gold_dragons
      end

      def call
        # Business failure — returns a Response the caller can handle
        return failure("Cannot transfer to the same account") if transferring_to_self?

        # Guard — halts with a structured error if the precondition fails
        enforce_eligible_transfer!(
          from: from_account,
          to: to_account,
          amount: @gold_dragons
        )

        from_account.withdraw!(@gold_dragons)
        to_account.deposit!(@gold_dragons)

        # Success — wrapped in a DataObject with accessor methods
        success(
          transferred: @gold_dragons,
          from_balance: from_account.balance,
          to_balance: to_account.balance
        )
      end

      private

      def transferring_to_self?
        from_account == to_account
      end
    end
  end
end
```

--------------------------------

### Mock Service Result Example

Source: https://github.com/zarpay/servus/blob/main/site/features/schema-validation.md

Use `servus_result_example` to generate a mock result object that conforms to the service's schema, useful for stubbing service calls in tests.

```ruby
# In an integration test — need to mock a service result
expected = servus_result_example(Treasury::TransferGold::Service)
allow(Treasury::TransferGold::Service).to receive(:call).and_return(expected)
```

--------------------------------

### Access Servus Configuration Values

Source: https://context7.com/zarpay/servus/llms.txt

Retrieve the configured directory paths for schemas, services, events, and guards. Get the specific schema path for a given service and argument type.

```ruby
Servus.config.schemas_dir  # => 'app/schemas'
```

```ruby
Servus.config.schema_path_for('treasury/transfer_gold', 'arguments')
# => '/app/app/schemas/treasury/transfer_gold/arguments.json'
```

--------------------------------

### Test Conditional Service Dispatch

Source: https://github.com/zarpay/servus/blob/main/site/testing/events.md

This example shows how to test conditional logic within event handlers. It verifies that a service is dispatched only when a specific condition (transfer amount > 100) is met, and not dispatched otherwise.

```ruby
RSpec.describe GoldTransferredHandler do
  context "when transfer exceeds 100 gold dragons" do
    let(:payload) { { transferred: 150, from_balance: 850, to_balance: 650 } }

    it "dispatches a raven" do
      expect {
        described_class.handle(payload)
      }.to call_service(Ravens::DispatchMessage::Service).async
    end
  end

  context "when transfer is 100 or less" do
    let(:payload) { { transferred: 50, from_balance: 950, to_balance: 550 } }

    it "does not dispatch a raven" do
      expect {
        described_class.handle(payload)
      }.not_to call_service(Ravens::DispatchMessage::Service)
    end
  end
end
```

--------------------------------

### Create ApplicationService base class

Source: https://github.com/zarpay/servus/blob/main/site/reference/dry-initializer.md

Set up a base class for your Servus services that includes dry-initializer. This promotes consistency across your service objects.

```ruby
# app/services/application_service.rb
class ApplicationService < Servus::Base
  extend Dry::Initializer
end
```

--------------------------------

### Create a Basic Servus Service

Source: https://context7.com/zarpay/servus/llms.txt

Define a service by inheriting from `Servus::Base`, implementing `initialize` for arguments and `call` for business logic. Use `success` to return data or `failure` to return an error. The service returns a `Response` object.

```ruby
module Treasury
  module TransferGold
    class Service < Servus::Base
      def initialize(from_account:, to_account:, gold_dragons:)
        @from_account = from_account
        @to_account = to_account
        @gold_dragons = gold_dragons
      end

      def call
        return failure("Cannot transfer to the same account") if @from_account == @to_account
        return failure("Insufficient balance") if @from_account.balance < @gold_dragons

        @from_account.withdraw!(@gold_dragons)
        @to_account.deposit!(@gold_dragons)

        success(
          transferred: @gold_dragons,
          from_balance: @from_account.balance,
          to_balance: @to_account.balance
        )
      end
    end
  end
end
```

```ruby
# Calling the service
result = Treasury::TransferGold::Service.call(
  from_account: crown_account,
  to_account: night_watch_account,
  gold_dragons: 50
)

if result.success?
  puts "Transferred: #{result.data.transferred}"      # => 50
  puts "From balance: #{result.data.from_balance}"    # => 950
  puts "To balance: #{result.data.to_balance}"        # => 550
else
  puts "Error: #{result.error.message}"
end
```

--------------------------------

### Automatic JSON Error Response Example

Source: https://github.com/zarpay/servus/blob/main/site/rails/controllers.md

On failure, `run_service` automatically renders a JSON error response based on the error type's `http_status` and `api_error`. For example, `NotFoundError` results in a 404 status.

```json
// failure("Account not found", type: NotFoundError)
// renders with status 404:
{
  "error": {
    "code": "not_found",
    "message": "Account not found"
  }
}
```

--------------------------------

### Add Servus to Gemfile

Source: https://github.com/zarpay/servus/blob/main/site/getting-started/index.md

Add the Servus gem to your application's Gemfile for installation.

```ruby
gem 'servus'
```

--------------------------------

### Inherit from ApplicationService

Source: https://github.com/zarpay/servus/blob/main/site/reference/dry-initializer.md

Demonstrates how to inherit from the ApplicationService base class, applying dry-initializer to a specific service.

```ruby
module Treasury
  module TransferGold
    class Service < ApplicationService
      option :from_account
      option :to_account
      option :gold_dragons

      lazily :from_account, finds: Account
      lazily :to_account, finds: Account

      def call
        # ...
      end
    end
  end
end
```

--------------------------------

### Direct Service Instantiation (Bypasses Lifecycle)

Source: https://github.com/zarpay/servus/blob/main/site/core/call-chain.md

Instantiating a service directly using `.new` bypasses the framework's lifecycle, including validation and logging. Use this only when explicit control is needed and the lifecycle is not required.

```ruby
# Bypasses the lifecycle — no validation, no logging, no events
service = Treasury::TransferGold::Service.new(
  from_account: crown_account,
  to_account: wall_account,
  gold_dragons: 50
)
result = service.call
```

--------------------------------

### Generated Guard Class

Source: https://github.com/zarpay/servus/blob/main/site/reference/generators.md

This is an example of a generated guard class. Implement the `test` method with your validation logic and customize the `message` and `message_data` as needed.

```ruby
# app/guards/eligible_transfer_guard.rb
class EligibleTransferGuard < Servus::Guard
  http_status 422
  error_code 'eligible_transfer'

  message '%<class_name>s eligible transfer validation failed' do
    message_data
  end

  def test(**kwargs)
    # TODO: Implement validation logic
    true
  end

  private

  def message_data
    # TODO: Return hash of values for message interpolation
    { class_name: 'Object' }
  end
end
```

--------------------------------

### Basic Servus Service Implementation

Source: https://github.com/zarpay/servus/blob/main/site/getting-started/index.md

Define a basic Servus service by inheriting from Servus::Base, implementing initialize and call, and using success to return a Response. Ensure keyword arguments are used for initialization.

```ruby
# app/services/treasury/transfer_gold/service.rb
module Treasury
  module TransferGold
    class Service < Servus::Base
      def initialize(from_account:, to_account:, gold_dragons:)
        @from_account = from_account
        @to_account = to_account
        @gold_dragons = gold_dragons
      end

      def call
        @from_account.withdraw!(@gold_dragons)
        @to_account.deposit!(@gold_dragons)

        success(
          transferred: @gold_dragons,
          from_balance: @from_account.balance,
          to_balance: @to_account.balance
        )
      end
    end
  end
end
```

--------------------------------

### Rails Autoloading for Services

Source: https://github.com/zarpay/servus/blob/main/site/rails/autoloading.md

Demonstrates the mapping of file paths to constants for services within the Rails autoloading system. No manual `require` statements are needed.

```ruby
app/services/treasury/transfer_gold/service.rb  →  Treasury::TransferGold::Service
```

```ruby
app/services/ravens/dispatch_message/service.rb  →  Ravens::DispatchMessage::Service
```

```ruby
app/services/treasury/transfer_gold/support/balance_snapshot.rb  →  Treasury::TransferGold::Support::BalanceSnapshot
```

--------------------------------

### Async Service Execution with ActiveJob

Source: https://context7.com/zarpay/servus/llms.txt

Illustrates how to execute Servus services asynchronously using `call_async` with ActiveJob, including options for scheduling like `wait`, `wait_until`, `queue`, and `priority`.

```ruby
class Reports::Generate::Service < Servus::Base
  def initialize(report_type:, user_id:, date_range:)
    @report_type = report_type
    @user_id = user_id
    @date_range = date_range
  end

  def call
    data = compile_report(@report_type, @date_range)
    ReportMailer.deliver(user_id: @user_id, data: data)
    success(report_generated: true)
  end
end
```

```ruby
# Basic async execution
Reports::Generate::Service.call_async(
  report_type: :sales,
  user_id: 123,
  date_range: 1.month.ago..Time.current
)
```

```ruby
# With delay
Reports::Generate::Service.call_async(
  wait: 5.minutes,
  report_type: :inventory,
  user_id: 123,
  date_range: 1.week.ago..Time.current
)
```

--------------------------------

### Using Built-in Guards in Servus Services

Source: https://context7.com/zarpay/servus/llms.txt

Demonstrates the use of PresenceGuard, StateGuard, TruthyGuard, and FalseyGuard for validating service inputs and states. Ensure required parameters are present and attributes match expected conditions.

```ruby
class TransferService::Service < Servus::Base
  def initialize(from_account:, to_account:, amount:)
    @from = from_account
    @to = to_account
    @amount = amount
  end

  def call
    # PresenceGuard: validates values are present (not nil or empty)
    enforce_presence!(from: @from, to: @to, amount: @amount)

    # StateGuard: validates attribute matches expected value(s)
    enforce_state!(on: @from, check: :status, is: :active)
    enforce_state!(on: @to, check: :status, is: [:active, :trial])

    # TruthyGuard: validates attributes are truthy
    enforce_truthy!(on: @from, check: :verified)

    # FalseyGuard: validates attributes are falsey
    enforce_falsey!(on: @from, check: :frozen)

    perform_transfer
    success(transferred: @amount)
  end
end
```

```ruby
# Example guard failures
result = TransferService::Service.call(from_account: nil, to_account: account, amount: 100)
result.error.message  # => "from must be present (got nil)"

result = TransferService::Service.call(from_account: frozen_account, to_account: account, amount: 100)
result.error.message  # => "Account.status must be active (got frozen)"
```

--------------------------------

### Combine Conditions for Service Invocation

Source: https://github.com/zarpay/servus/blob/main/site/features/event-bus.md

Use the `if` option with a lambda to conditionally invoke a service based on payload data. This example invokes a service only if the transferred amount is greater than 100.

```ruby
invoke Ravens::DispatchMessage::Service, if: ->(p) { p[:transferred] > 100 } do |payload|
  {
    message: "Large transfer of #{payload[:transferred]} gold dragons completed",
    destination: :iron_bank
  }
end
```

--------------------------------

### Synchronous vs. Asynchronous Service Execution

Source: https://github.com/zarpay/servus/blob/main/site/features/async-execution.md

Demonstrates that `call` and `call_async` are functionally identical in terms of service execution. The difference lies in when and where the service logic is processed.

```ruby
args = { from_account: 1, to_account: 2, gold_dragons: 50 }

# These two are functionally identical — the second just runs later
Treasury::TransferGold::Service.call(**args)
Treasury::TransferGold::Service.call_async(**args)
```

--------------------------------

### Service without dry-initializer

Source: https://github.com/zarpay/servus/blob/main/site/reference/dry-initializer.md

Demonstrates a typical Servus service object before using dry-initializer, including a manual initialize method and instance variable assignments.

```ruby
module Treasury
  module TransferGold
    class Service < Servus::Base
      lazily :from_account, finds: Account
      lazily :to_account, finds: Account

      def initialize(from_account:, to_account:, gold_dragons:)
        @from_account = from_account
        @to_account = to_account
        @gold_dragons = gold_dragons
      end

      def call
        from_account.withdraw!(@gold_dragons)
        to_account.deposit!(@gold_dragons)

        success(
          transferred: @gold_dragons,
          from_balance: from_account.balance,
          to_balance: to_account.balance
        )
      end
    end
  end
end
```

--------------------------------

### `rescue_from` with Error Type

Source: https://github.com/zarpay/servus/blob/main/site/features/error-handling.md

Declaratively map specific exceptions to failure responses using `rescue_from`. This example maps `ActiveRecord::RecordNotFound` and network timeouts to predefined error types.

```ruby
class Treasury::TransferGold::Service < Servus::Base
  rescue_from ActiveRecord::RecordNotFound, use: NotFoundError
  rescue_from Net::OpenTimeout, Timeout::Error, use: ServiceUnavailableError
end
```

--------------------------------

### Calling a Service with Lazy Resolvers

Source: https://github.com/zarpay/servus/blob/main/site/features/lazy-resolvers.md

Demonstrates how to call a service that uses lazy resolvers, showing flexibility in passing either loaded records or their IDs for synchronous or asynchronous execution.

```ruby
# Sync — pass loaded records, no query
Treasury::TransferGold::Service.call(
  from_account: current_account,
  to_account: recipient_account,
  gold_dragons: 50
)

# Async — pass IDs, resolved by the worker
Treasury::TransferGold::Service.call_async(
  from_account: current_account.id,
  to_account: recipient_account.id,
  gold_dragons: 50
)

# Sync with IDs — also works
Treasury::TransferGold::Service.call(
  from_account: 1,
  to_account: 2,
  gold_dragons: 50
)
```

--------------------------------

### Configure Servus Settings

Source: https://github.com/zarpay/servus/blob/main/site/rails/configuration.md

Create an initializer file to customize Servus settings. These options control where Servus looks for files and how it validates events. All options are accessible via `Servus.config`.

```ruby
# config/initializers/servus.rb
Servus.configure do |config|

  # ── Directory Settings ──────────────────────────────────────────────
  # Controls where Servus looks for file-based schemas, event handlers,
  # guards, and services. These paths are relative to Rails.root.
  # Generators also use these paths when creating new files.

  config.services_dir = "app/services"  # default: "app/services"
  config.schemas_dir  = "app/schemas"   # default: "app/schemas"
  config.events_dir   = "app/events"    # default: "app/events"
  config.guards_dir   = "app/guards"    # default: "app/guards"

  # ── Event Validation ────────────────────────────────────────────────
  # When true, Servus.validate_all_handlers! raises OrphanedHandlerError
  # if any handler subscribes to an event that no service emits.
  # Useful in CI or a boot-time rake task to catch typos and stale handlers.

  config.strict_event_validation = true  # default: true

  # ── Guards ──────────────────────────────────────────────────────────
  # Servus includes four built-in guards: PresenceGuard, TruthyGuard,
  # FalseyGuard, and StateGuard. Set to false if you want to disable
  # them entirely (your custom guards still load from guards_dir).

  config.include_default_guards = true  # default: true
end
```

--------------------------------

### Configure Servus Directories and Settings

Source: https://context7.com/zarpay/servus/llms.txt

Set custom directories for schemas, services, events, and guards. Configure strict event validation and inclusion of default guards.

```ruby
Servus.configure do |config|
  # Directory for JSON schema files (default: 'app/schemas')
  config.schemas_dir = 'app/schemas'

  # Directory for service classes (default: 'app/services')
  config.services_dir = 'app/services'

  # Directory for event handlers (default: 'app/events')
  config.events_dir = 'app/events'

  # Directory for guard classes (default: 'app/guards')
  config.guards_dir = 'app/guards'

  # Validate handlers subscribe to emitted events (default: true)
  config.strict_event_validation = true

  # Include built-in guards (default: true)
  config.include_default_guards = true
end
```

--------------------------------

### Response Composition

Source: https://github.com/zarpay/servus/blob/main/site/core/responses.md

Demonstrates how to compose services by returning a downstream service's response directly if it's a failure, preserving the original error context.

```ruby
def call
  reserve = Treasury::ReserveFunds::Service.call(account: @account, amount: @amount)
  return reserve unless reserve.success?

  # continue with reserved funds...
end
```

--------------------------------

### Chain Async and With Matchers for Service Calls

Source: https://github.com/zarpay/servus/blob/main/site/testing/events.md

Demonstrates chaining the `.async` and `.with` matchers with `call_service`. This allows testing both the arguments passed to a service and whether it's invoked asynchronously.

```ruby
expect {
  described_class.handle(payload)
}.to call_service(Ravens::SendReceipt::Service)
  .with(amount: 50)
  .async
```

--------------------------------

### Dry-initializer option features

Source: https://github.com/zarpay/servus/blob/main/site/reference/dry-initializer.md

Illustrates the use of `option` with features like default values, optional arguments, and type coercion (implied by usage).

```ruby
class Service < ApplicationService
  option :from_account
  option :to_account
  option :gold_dragons, default: -> { 0 }
  option :currency, default: -> { "gold_dragons" }
  option :note, optional: true
end
```

--------------------------------

### Service with scattered preconditions

Source: https://github.com/zarpay/servus/blob/main/site/features/guards.md

This Ruby code demonstrates a service with multiple early return statements for precondition checks, which can lead to duplicated validation logic.

```ruby
def call
  return failure("Sender account must be open")      unless @from_account.open?
  return failure("Receiver account must be open")    unless @to_account.open?
  return failure("Sender account must not be frozen") unless !@from_account.frozen?
  return failure("Receiver account must not be frozen") unless !@to_account.frozen?
  return failure("Insufficient funds")               unless @from_account.balance >= @gold_dragons

  # finally, the actual business logic...
end
```

--------------------------------

### Generate a Servus Service

Source: https://github.com/zarpay/servus/blob/main/site/rails/generators.md

Use the `servus:service` generator to create a service class, spec, and schema files. Provide a namespaced service name and optional keyword arguments for the `initialize` method.

```bash
rails g servus:service treasury/transfer_gold from_account to_account gold_dragons

=> create  app/services/treasury/transfer_gold/service.rb
=> create  spec/services/treasury/transfer_gold/service_spec.rb
=> create  app/schemas/services/treasury/transfer_gold/result.json
=> create  app/schemas/services/treasury/transfer_gold/arguments.json
```

--------------------------------

### Bang vs. Predicate Guard Methods

Source: https://github.com/zarpay/servus/blob/main/site/features/guards.md

Demonstrates the difference between bang (!) methods that halt execution on failure and predicate (?) methods that return a boolean for conditional logic.

```ruby
enforce_eligible_transfer!(
  from: from_account,
  to: to_account,
  amount: @gold_dragons
)
```

```ruby
eligible = check_eligible_transfer?(
  from: from_account,
  to: to_account,
  amount: @gold_dragons
)

if eligible
  perform_standard_transfer
else
  perform_manual_review_transfer
end
```

--------------------------------

### Configure Servus Globally

Source: https://context7.com/zarpay/servus/llms.txt

Configure Servus globally using `Servus.configure` to set options such as directory paths for services and validation settings.

```ruby
Servus.configure do |config|
  # config.services_path = 'app/my_services'
  # config.validate_schemas = true
end
```

--------------------------------

### Servus Configuration

Source: https://github.com/zarpay/servus/blob/main/site/reference/generators.md

Configure the directory settings for Servus components like services, schemas, events, and guards. These settings are typically placed in `config/initializers/servus.rb`.

```ruby
# config/initializers/servus.rb
Servus.configure do |config|
  config.services_dir = "app/services"  # default: "app/services"
  config.schemas_dir  = "app/schemas"   # default: "app/schemas"
  config.events_dir   = "app/events"    # default: "app/events"
  config.guards_dir   = "app/guards"    # default: "app/guards"
end
```

--------------------------------

### Async Service with Queue and Scheduling Options

Source: https://github.com/zarpay/servus/blob/main/site/features/async-execution.md

Pass ActiveJob options directly to `call_async` to control queue, priority, and scheduling. Servus extracts these options before passing the remaining arguments to the service.

```ruby
Treasury::TransferGold::Service.call_async(
  from_account: 1,
  to_account: 2,
  gold_dragons: 50,
  queue: :critical,
  priority: 10,
  wait: 5.minutes
)
```

```ruby
Treasury::TransferGold::Service.call_async(
  from_account: 1,
  to_account: 2,
  gold_dragons: 50,
  job_options: { queue: :critical, priority: 10, wait: 5.minutes }
)
```

--------------------------------

### Define Argument and Result Schemas with DSL

Source: https://github.com/zarpay/servus/blob/main/site/features/schema-validation.md

Use the `schema` DSL to define both argument and result schemas for a service. This is the recommended approach for schema definition.

```ruby
class Treasury::TransferGold::Service < Servus::Base
  schema(
    arguments: {
      type: "object",
      required: ["from_account", "to_account", "gold_dragons"],
      properties: {
        from_account: { type: ["integer", "object"] },
        to_account: { type: ["integer", "object"] },
        gold_dragons: { type: "integer", minimum: 1 }
      }
    },
    result: {
      type: "object",
      required: ["transferred", "from_balance", "to_balance"],
      properties: {
        transferred: { type: "number" },
        from_balance: { type: "number" },
        to_balance: { type: "number" }
      }
    }
  )
end
```

--------------------------------

### Correct Service Call with Full Lifecycle

Source: https://github.com/zarpay/servus/blob/main/site/core/call-chain.md

Use the `.call` method to ensure the full service lifecycle, including validation and logging, is executed.

```ruby
# Correct — runs the full lifecycle
result = Treasury::TransferGold::Service.call(
  from_account: crown_account,
  to_account: wall_account,
  gold_dragons: 50
)
```

--------------------------------

### Service using a guard

Source: https://github.com/zarpay/servus/blob/main/site/features/guards.md

This Ruby code shows how a service can enforce preconditions using a guard, simplifying the main logic and centralizing validation.

```ruby
def call
  enforce_eligible_transfer!(
    from: from_account,
    to: to_account,
    amount: @gold_dragons
  )

  from_account.withdraw!(@gold_dragons)
  to_account.deposit!(@gold_dragons)

  success(
    transferred: @gold_dragons,
    from_balance: from_account.balance,
    to_balance: to_account.balance
  )
end
```

--------------------------------

### Lazy Resolver DSL Options

Source: https://github.com/zarpay/servus/blob/main/site/features/lazy-resolvers.md

Illustrates the DSL for configuring lazy resolvers, specifying the model class to find and optionally a custom column for lookup using the `by:` option.

```ruby
lazily :name, finds: ModelClass              # resolves via ModelClass.find(value)
lazily :name, finds: ModelClass, by: :column # resolves via ModelClass.find_by!(column: value)
```

--------------------------------

### Service with dry-initializer

Source: https://github.com/zarpay/servus/blob/main/site/reference/dry-initializer.md

Shows the same Servus service object refactored to use dry-initializer, eliminating the manual initialize method and instance variable assignments.

```ruby
module Treasury
  module TransferGold
    class Service < Servus::Base
      option :from_account
      option :to_account
      option :gold_dragons, default: -> { 1 }

      lazily :from_account, finds: Account
      lazily :to_account, finds: Account

      def call
        from_account.withdraw!(gold_dragons)
        to_account.deposit!(gold_dragons)

        success(
          transferred: gold_dragons,
          from_balance: from_account.balance,
          to_balance: to_account.balance
        )
      end
    end
  end
end
```

--------------------------------

### Configure Servus Directories

Source: https://github.com/zarpay/servus/blob/main/site/rails/generators.md

Customize the default directories for generated schemas, events, guards, and services by modifying the `Servus.configure` block in an initializer file.

```ruby
# config/initializers/servus.rb
Servus.configure do |config|
  config.schemas_dir  = "config/schemas"     # default: "app/schemas"
  config.events_dir   = "app/event_handlers" # default: "app/events"
  config.guards_dir   = "lib/guards"         # default: "app/guards"
  config.services_dir = "app/services"       # default: "app/services"
end
```

--------------------------------

### Schedule Service Call with Queue and Priority

Source: https://context7.com/zarpay/servus/llms.txt

Schedule a service to run asynchronously with a specified queue and priority. This is useful for managing background job loads.

```ruby
Reports::Generate::Service.call_async(
  queue: :low_priority,
  priority: 5,
  report_type: :analytics,
  user_id: 123,
  date_range: 1.year.ago..Time.current
)
```

--------------------------------

### Test Service Failure Responses

Source: https://context7.com/zarpay/servus/llms.txt

Mock a service to return a failure using `servus_failure_example` and assert the failure structure and reason.

```ruby
# Testing failure examples
RSpec.describe ProcessPayment::Service do
  it 'returns expected failure structure' do
    allow_any_instance_of(described_class).to receive(:call).and_return(
      servus_failure_example(described_class, reason: 'test_decline')
    )

    result = described_class.call(user_id: 1, amount: 100, currency: 'USD')

    expect(result).to be_failure
    expect(result.data.reason).to eq('test_decline')
  end
end
```

--------------------------------

### Configure Schemas Directory

Source: https://github.com/zarpay/servus/blob/main/site/features/schema-validation.md

Customize the directory where Servus looks for JSON schema files using the `schemas_dir` configuration option.

```ruby
# config/initializers/servus.rb
Servus.configure do |config|
  config.schemas_dir = "app/services"  # colocates schemas next to service files
  # or
  config.schemas_dir = "config/schemas" # keeps schemas outside of app/
end
```

--------------------------------

### Implement a Servus Service Object

Source: https://github.com/zarpay/servus/blob/main/README.md

Define a service object by inheriting from Servus::Base, implementing an initialize method for arguments, and a call method for the service's logic. The call method should return a Servus result object.

```ruby
module Treasury
  module TransferGold
    class Service < Servus::Base
      def initialize(from_account:, to_account:, gold_dragons:)
        @from_account = from_account
        @to_account = to_account
        @gold_dragons = gold_dragons
      end

      def call
        @from_account.withdraw!(@gold_dragons)
        @to_account.deposit!(@gold_dragons)

        success(
          transferred: @gold_dragons,
          from_balance: @from_account.balance,
          to_balance: @to_account.balance
        )
      end
    end
  end
end
```

--------------------------------

### Subscribe to All Servus Events

Source: https://github.com/zarpay/servus/blob/main/site/features/event-bus.md

Use `ActiveSupport::Notifications.subscribe` with a regex to listen for all events dispatched by Servus, prefixed with `servus.events.`. This allows for global monitoring, logging, or metrics.

```ruby
ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, start, finish, id, payload|
  event_name = name.sub("servus.events.", "")
  duration = ((finish - start) * 1000).round(1)
  Rails.logger.info "[Servus Event] #{event_name} (#{duration}ms) #{payload}"
end
```

--------------------------------

### Customizing Event Payloads with `with` or Block

Source: https://context7.com/zarpay/servus/llms.txt

Shows how to customize the payload of emitted events using the `with` option to specify a method or an inline block for dynamic payload generation.

```ruby
class Orders::Complete::Service < Servus::Base
  emits :order_completed, on: :success, with: :order_payload

  def initialize(order:)
    @order = order
  end

  def call
    @order.complete!
    success(order_id: @order.id, total: @order.total)
  end

  private

  # Custom payload builder method
  def order_payload(result)
    {
      order_id: @order.id,
      customer_id: @order.customer_id,
      items: @order.items.map(&:sku),
      total: @order.total,
      completed_at: Time.current
    }
  end
end
```

```ruby
# Or use inline block
class Payments::Process::Service < Servus::Base
  emits :payment_processed, on: :success do |result|
    {
      transaction_id: result.data.transaction_id,
      amount: result.data.amount,
      timestamp: Time.current.iso8601
    }
  end
end
```

--------------------------------

### Service Call Without Schema Validation (Defensive)

Source: https://github.com/zarpay/servus/blob/main/site/features/schema-validation.md

Illustrates defensive coding practices required when schema validation is not used, including explicit checks for required fields and types.

```ruby
# Without schemas — defensive code creeps in
def call
  return failure("amount required") unless @gold_dragons
  return failure("amount must be integer") unless @gold_dragons.is_a?(Integer)
  return failure("amount must be positive") unless @gold_dragons > 0

  # finally, the actual business logic...
end
```

--------------------------------

### Calling a Servus Service

Source: https://github.com/zarpay/servus/blob/main/site/getting-started/mental-model.md

Use `Service.call(**args)` to execute a service synchronously. For background execution, use `Service.call_async(**args)` which enqueues the job via ActiveJob.

```ruby
Service.call(**args)
```

```ruby
Service.call_async(**args)
```

--------------------------------

### Generate Servus Service with Arguments

Source: https://context7.com/zarpay/servus/llms.txt

Use the `rails g servus:service` generator to create a new service, including its Ruby file, argument schema, result schema, and spec file. Specify arguments directly on the command line.

```bash
# Generate a service with arguments
rails g servus:service treasury/transfer_gold from_account to_account gold_dragons

# Generated files:
# app/services/treasury/transfer_gold/service.rb
# app/schemas/treasury/transfer_gold/arguments.json
# app/schemas/treasury/transfer_gold/result.json
# spec/services/treasury/transfer_gold/service_spec.rb
```

--------------------------------

### Generate a Servus guard

Source: https://github.com/zarpay/servus/blob/main/site/features/guards.md

Use this bash command to generate a new guard file for your Servus project.

```bash
rails g servus:guard eligible_transfer

=> create app/guards/eligible_transfer_guard.rb
```

--------------------------------

### Generate Servus Service Without Docs

Source: https://context7.com/zarpay/servus/llms.txt

Use the `--no-docs` flag with `rails g servus:service` to generate a service without including documentation comments in the generated files.

```bash
# Skip documentation comments
rails g servus:service payments/process --no-docs
```

--------------------------------

### Rails Autoloading for Guards

Source: https://github.com/zarpay/servus/blob/main/site/rails/autoloading.md

Illustrates how the Servus Railtie eager-loads `*_guard.rb` files from the configured `guards_dir` on every request in development and once at boot in production. Guards must follow the `*_guard.rb` naming convention.

```ruby
app/guards/eligible_transfer_guard.rb  →  EligibleTransferGuard
```

```ruby
app/guards/sufficient_balance_guard.rb →  SufficientBalanceGuard
```

--------------------------------

### Compatibility of `lazily` with `option`

Source: https://github.com/zarpay/servus/blob/main/site/reference/dry-initializer.md

Shows how `lazily` accessor takes precedence over `option`'s generated reader, while `option` still handles initialization. This is useful when you need lazy loading for some attributes and direct initialization for others.

```ruby
class Service < ApplicationService
  option :from_account
  option :to_account
  option :gold_dragons

  lazily :from_account, finds: Account
  lazily :to_account, finds: Account

  def call
    # from_account is resolved by lazily, not dry-initializer's reader
    # gold_dragons uses dry-initializer's reader directly
    success(transferred: gold_dragons)
  end
end
```

--------------------------------

### Handling Guard Failures

Source: https://github.com/zarpay/servus/blob/main/site/features/guards.md

Illustrates how a failed guard, using the bang method, results in a failure Response. The framework catches the guard's thrown error and converts it into a standard Response object.

```ruby
result = Treasury::TransferGold::Service.call(
  from_account: underfunded_account,
  to_account: night_watch_account,
  gold_dragons: 1000
)

result.success?              # => false
result.error.message         # => "Insufficient balance: need 1000, have 50"
result.error.code            # => "insufficient_balance"
result.error.http_status     # => 422
```

--------------------------------

### Servus Failure Response with rescue_from

Source: https://github.com/zarpay/servus/blob/main/site/core/call-chain.md

Demonstrates how an exception, when handled by `rescue_from`, is converted into a failure `Response` object, allowing the caller to check `result.success?` and access the error message.

```ruby
# result.success?       # => false
# result.error.message  # => "[ActiveRecord::RecordNotFound]: Couldn't find Account with 'id'=999"
```

--------------------------------

### Enqueue a Service Asynchronously

Source: https://github.com/zarpay/servus/blob/main/site/features/async-execution.md

Use `call_async` to enqueue a service for background execution via ActiveJob. The service runs its lifecycle, but there is no immediate return value as it hasn't executed yet.

```ruby
Treasury::TransferGold::Service.call_async(
  from_account: crown_account.id,
  to_account: night_watch_account.id,
  gold_dragons: 50
)
```

--------------------------------

### Service Call with Schema Validation (Optimized)

Source: https://github.com/zarpay/servus/blob/main/site/features/schema-validation.md

With schema validation in place, the `call` method can focus solely on business logic, assuming valid inputs. Argument validation runs before `call`, and result validation runs after.

```ruby
# With schemas — call only contains business logic
def call
  enforce_sufficient_balance!(account: from_account, amount: @gold_dragons)

  from_account.withdraw!(@gold_dragons)
  to_account.deposit!(@gold_dragons)

  success(
    transferred: @gold_dragons,
    from_balance: from_account.balance,
    to_balance: to_account.balance
  )
end
```
Tokens:
Raw