servus 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 871333d0568c05b07e86cb1c642d54877cbb33f3a2a1c29267da3ed688389129
-  data.tar.gz: 103f4c7d0662f9511ca2d155d783285184bacabdeb5a15c0b81d346ccaba3b41
+  metadata.gz: f63266b1efb1e782745c67d24957ce1126b1031592667bd78fe80f5ed2c93ac7
+  data.tar.gz: 64d263185dc9214707aafc7eaaf740343e5c24311eec49db6bbccff25fa413a9
 SHA512:
-  metadata.gz: bd690d583dbe42aacd6b87f84a1dedbec2313c74e409f6d03b2da34807e6512c660c8b5e7d2d87c1baa7a2837531e52b7b72b325fe94b62a926497d0af26dfb1
-  data.tar.gz: 204699451cdf2f8b2974a8194f62ba83866180cbb3edf221d704356fdc706f53ae3ae859df4bd5e43b009cbb8c01967e052aecdb8582cd3ca5e8676a2b467b3b
+  metadata.gz: a6d3ff24ec58b33b926acca83447ede76c1feb54daab1ade3b4a744f66e70a87785b68d6e235934b6b20f6477e7518441486bb6d405f34cd8bfb2334c095122e
+  data.tar.gz: 5f562d3cac4a258387fab0936d8fecb41e9e42803556014d91c5802f0b27f6b5cd2a085f76b4d0d486c609f2589c286d5fe13fbd4be34270f4ecc104d2b478a1

data/.claude/settings.json

@@ -1,4 +1,13 @@
 {
+  "permissions": {
+    "allow": [
+      "Bash(bundle exec rspec:*)",
+      "Bash(bundle exec rubocop:*)",
+      "Bash(find:*)"
+    ],
+    "deny": [],
+    "ask": []
+  },
   "hooks": {
     "PostToolUse": [
       {

data/CHANGELOG.md

@@ -1,4 +1,42 @@
-## [Unreleased]
+## [0.2.0] - 2025-12-16
+
+### Added
+
+- **Guards System**: Reusable validation rules with rich error responses
+  - `Servus::Guard` base class for creating custom guards
+  - `Servus::Guards` module included in services with `enforce_*!` and `check_*?` methods
+  - Built-in guards:
+    - `PresenceGuard` - validates values are present (not nil or empty)
+    - `TruthyGuard` - validates object attributes are truthy
+    - `FalseyGuard` - validates object attributes are falsey
+    - `StateGuard` - validates object attributes match expected value(s)
+  - Guards auto-define methods when classes inherit from `Servus::Guard`
+  - Guard DSL: `http_status`, `error_code`, `message` with interpolation support
+  - Multiple message template formats: String, I18n Symbol, inline Hash, Proc
+  - Rails auto-loading from `app/guards/*_guard.rb`
+  - Configuration options: `guards_dir`, `include_default_guards`
+
+- **GuardError**: New error class for guard validation failures
+  - Custom `code` and `http_status` per guard
+  - Services catch `:guard_failure` and wrap in failure response automatically
+
+### Changed
+
+- **Error API Refactored**: Cleaner separation of HTTP status and error body
+  - All errors now have `http_status` method returning Rails status symbol
+  - `api_error` returns `{ code:, message: }` for response body only
+  - Follows community conventions (Stripe, JSON:API) where HTTP status is in header
+
+- **Controller Helpers Refactored**:
+  - Renamed `render_service_object_error` to `render_service_error`
+  - Now takes error object directly instead of `api_error` hash
+  - Response format: `{ error: { code:, message: } }` with status from `error.http_status`
+
+### Breaking Changes
+
+- `render_service_object_error` renamed to `render_service_error`
+- `render_service_error` now accepts error object, not hash: `render_service_error(result.error)` instead of `render_service_error(result.error.api_error)`
+- Error response JSON structure changed from `{ code:, message: }` to `{ error: { code:, message: } }`
 
 ## [0.1.6] - 2025-12-06
 

data/READme.md

@@ -350,16 +350,105 @@ end
 
 The block receives the exception and has access to `success` and `failure` methods for creating the response.
 
+## **Guards**
+
+Guards are reusable validation rules that halt service execution when conditions aren't met. They provide declarative precondition checking with rich error responses.
+
+### Built-in Guards
+
+```ruby
+def call
+  # Validate values are present (not nil or empty)
+  enforce_presence!(user: user, account: account)
+
+  # Validate object attributes are truthy
+  enforce_truthy!(on: user, check: :active)
+  enforce_truthy!(on: user, check: [:active, :verified])  # all must be truthy
+
+  # Validate object attributes are falsey
+  enforce_falsey!(on: user, check: :banned)
+  enforce_falsey!(on: post, check: [:deleted, :hidden])  # all must be falsey
+
+  # Validate attribute matches expected value(s)
+  enforce_state!(on: order, check: :status, is: :pending)
+  enforce_state!(on: account, check: :status, is: [:active, :trial])  # any match passes
+
+  # ... business logic ...
+  success(result)
+end
+```
+
+### Predicate Methods
+
+Each guard has a predicate version for conditional logic:
+
+```ruby
+if check_truthy?(on: user, check: :premium)
+  apply_premium_discount
+else
+  apply_standard_rate
+end
+```
+
+### Custom Guards
+
+Create custom guards in `app/guards/`:
+
+```bash
+$ rails g servus:guard open_account
+=>    create  app/guards/open_account_guard.rb
+      create  spec/guards/open_account_guard_spec.rb
+```
+
+```ruby
+# app/guards/open_account_guard.rb
+class OpenAccountGuard < Servus::Guard
+  http_status 422
+  error_code 'open_account_required'
+
+  message 'Invalid account: %<name> does not have an open account' do
+    message_data
+  end
+
+  def test(user:)
+    user.account.present? && user.account.status_open?
+  end
+
+  private
+
+  def message_data
+    {
+      name: kwargs[:user].name
+    }
+  end
+end
+
+# Usage in services:
+# enforce_open_account!(user: user_record)  # throws on failure
+# check_open_account?(user: user_record)    # returns boolean
+```
+
+### Guard Error Responses
+
+When a guard fails, the service returns a failure response with structured error data:
+
+```ruby
+result = TransferService.call(from_account: account, amount: 1000)
+result.success?          # => false
+result.error.message     # => "Invalid account: Bob Jones does not have an open account"
+result.error.code        # => "open_account_required"
+result.error.http_status # => 422
+```
+
 ## Controller Helpers
 
-Service objects can be called from controllers using the `run_service` and `render_service_object_error` helpers.
+Service objects can be called from controllers using the `run_service` and `render_service_error` helpers.
 
 ### run_service
 
-`run_service` calls the service object with the provided parameters and set's an instance variable `@result` to the
-result of the service object if the result is successful. If the result is not successful, it will pass the result
-to error to the `render_service_object_error` helper. This allows for easy error handling in the controller for
-repetetive usecases.
+`run_service` calls the service object with the provided parameters and sets an instance variable `@result` to the
+result of the service object. If the result is not successful, it automatically calls `render_service_error` with
+the error. This provides consistent error handling across controllers.
 
 ```ruby
 class SomeController < AppController
@@ -367,7 +456,7 @@ class SomeController < AppController
   def controller_action
     result = Services::SomeServiceObject::Service.call(my_params)
     return if result.success?
-    render_service_object_error(result.error.api_error)
+    render_service_error(result.error)
   end
 
   # After
@@ -377,26 +466,42 @@ class SomeController < AppController
 end
 ```
 
-### render_service_object_error
+### render_service_error
 
-`render_service_object_error` renders the error of a service object. It expects a hash with a `message` key and a `code` key from
-the api_error method of the service error. This is all setup by default for a JSON API response, thought the method can be
-overridden if needed to handle different usecases.
+`render_service_error` renders a service error as JSON. It takes an error object (not a hash) and uses
+`error.http_status` for the response status and `error.api_error` for the response body.
 
 ```ruby
-# Behind the scenes, render_service_object_error calls the following:
+# Behind the scenes, render_service_error calls the following:
 #
-#  error = result.error.api_error
-#  => { message: "Error message", code: 400 }
+#  render json: { error: error.api_error }, status: error.http_status
 #
-#  render json: { message: error[:message], code: error[:code] }, status: error[:code]
+# Which produces a response like:
+#  { "error": { "code": "not_found", "message": "User not found" } }
+#  with HTTP status 404
 
 class SomeController < AppController
   def controller_action
     result = Services::SomeServiceObject::Service.call(my_params)
     return if result.success?
 
-    render_service_object_error(result.error.api_error)
+    render_service_error(result.error)
+  end
+end
+```
+
+Override `render_service_error` in your controller to customize error response format:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def render_service_error(error)
+    render json: {
+      error: {
+        type: error.api_error[:code],
+        details: error.message,
+        timestamp: Time.current
+      }
+    }, status: error.http_status
   end
 end
 ```

data/docs/features/6_guards.md

@@ -0,0 +1,356 @@
+# @title Features / 6. Guards
+
+# Guards
+
+Guards are reusable validation rules that halt service execution when conditions aren't met. They provide a declarative way to enforce preconditions with rich, API-friendly error responses.
+
+## Why Guards?
+
+Instead of scattering validation logic throughout services:
+
+```ruby
+# Without guards - repetitive and verbose
+def call
+  return failure("User required", type: ValidationError) unless user
+  return failure("User must be active", type: ValidationError) unless user.active?
+  # ... business logic ...
+end
+```
+
+Use guards for clean, declarative validation:
+
+```ruby
+# With guards - clear and reusable
+def call
+  enforce_presence!(user: user)
+  enforce_truthy!(on: user, check: :active)
+  # ... business logic ...
+end
+```
+
+## Built-in Guards
+
+Servus includes four guards by default:
+
+### PresenceGuard
+
+Validates that all values are present (not nil or empty):
+
+```ruby
+# Single value
+enforce_presence!(user: user)
+
+# Multiple values - all must be present
+enforce_presence!(user: user, account: account, device: device)
+
+# Works with strings, arrays, hashes
+enforce_presence!(email: email)           # fails if nil or ""
+enforce_presence!(items: cart.items)      # fails if nil or []
+enforce_presence!(data: response.body)    # fails if nil or {}
+```
+
+Error: `"user must be present (got nil)"` or `"email must be present (got \"\")"`
+
+### TruthyGuard
+
+Validates that attribute(s) on an object are truthy:
+
+```ruby
+# Single attribute
+enforce_truthy!(on: user, check: :active)
+
+# Multiple attributes - all must be truthy
+enforce_truthy!(on: user, check: [:active, :verified, :confirmed])
+
+# Conditional check
+if check_truthy?(on: subscription, check: :valid?)
+  process_subscription
+end
+```
+
+Error: `"User.active must be truthy (got false)"`
+
+### FalseyGuard
+
+Validates that attribute(s) on an object are falsey:
+
+```ruby
+# Single attribute - user must not be banned
+enforce_falsey!(on: user, check: :banned)
+
+# Multiple attributes - all must be falsey
+enforce_falsey!(on: post, check: [:deleted, :hidden, :flagged])
+
+# Conditional check
+if check_falsey?(on: user, check: :suspended)
+  allow_action
+end
+```
+
+Error: `"User.banned must be falsey (got true)"`
+
+### StateGuard
+
+Validates that an attribute matches an expected value or one of several allowed values:
+
+```ruby
+# Single expected value
+enforce_state!(on: order, check: :status, is: :pending)
+
+# Multiple allowed values - any match passes
+enforce_state!(on: account, check: :status, is: [:active, :trial])
+
+# Conditional check
+if check_state?(on: order, check: :status, is: :shipped)
+  send_tracking_email
+end
+```
+
+Errors:
+- Single value: `"Order.status must be pending (got shipped)"`
+- Multiple values: `"Account.status must be one of active, trial (got suspended)"`
+
+## Guard Methods
+
+Each guard defines two methods on `Servus::Guards`:
+
+- **Bang method (`!`)** - Throws on failure, halts execution
+- **Predicate method (`?`)** - Returns boolean, continues execution
+
+```ruby
+# Bang method - use for preconditions that must pass
+enforce_presence!(user: user)  # throws :guard_failure if nil
+
+# Predicate method - use for conditional logic
+if check_truthy?(on: account, check: :premium)
+  apply_premium_discount
+else
+  apply_standard_rate
+end
+```
+
+## Creating Custom Guards
+
+Define guards by inheriting from `Servus::Guard`:
+
+```ruby
+# app/guards/sufficient_balance_guard.rb
+class SufficientBalanceGuard < Servus::Guard
+  http_status 422
+  error_code 'insufficient_balance'
+
+  message 'Insufficient balance: need %<required>s, have %<available>s' do
+    message_data
+  end
+
+  def test(account:, amount:)
+    account.balance >= amount
+  end
+
+  private
+
+  def message_data
+    {
+      required: kwargs[:amount],
+      available: kwargs[:account].balance
+    }
+  end
+end
+```
+
+This automatically defines `enforce_sufficient_balance!` and `check_sufficient_balance?` methods.
+
+### Guard DSL
+
+**`http_status`** - HTTP status code for API responses (default: 422)
+
+```ruby
+http_status 422  # Unprocessable Entity
+http_status 403  # Forbidden
+http_status 400  # Bad Request
+```
+
+**`error_code`** - Machine-readable error code for API clients
+
+```ruby
+error_code 'insufficient_balance'
+error_code 'daily_limit_exceeded'
+error_code 'account_locked'
+```
+
+**`message`** - Human-readable error message with optional interpolation
+
+```ruby
+# Static message
+message 'Amount must be positive'
+
+# With interpolation (uses Ruby's % formatting)
+message 'Balance: %<current>s, Required: %<required>s' do
+  { current: account.balance, required: amount }
+end
+```
+
+The message block has access to all kwargs passed to the guard via `kwargs`.
+
+**`test`** - The validation logic (must return boolean)
+
+```ruby
+def test(account:, amount:)
+  account.balance >= amount
+end
+```
+
+## Message Templates
+
+Guards support multiple message template formats:
+
+### String with Interpolation
+
+```ruby
+message 'Insufficient balance: need %<required>s, have %<available>s' do
+  { required: amount, available: account.balance }
+end
+```
+
+### I18n Symbol
+
+```ruby
+message :insufficient_balance
+# Looks up: I18n.t('guards.insufficient_balance')
+# Falls back to: "Insufficient balance" (humanized)
+```
+
+### Inline Translations
+
+```ruby
+message(
+  en: 'Insufficient balance',
+  es: 'Saldo insuficiente',
+  fr: 'Solde insuffisant'
+)
+```
+
+### Dynamic Proc
+
+```ruby
+message -> { "Limit exceeded for #{limit_type} transfers" }
+```
+
+## Error Handling
+
+When a bang guard fails, it throws `:guard_failure` with a `GuardError`. Services automatically catch this and return a failure response:
+
+```ruby
+class TransferService < Servus::Base
+  def call
+    enforce_state!(on: from_account, check: :status, is: :active)
+    # If guard fails, execution stops here
+    # Service returns: Response(success: false, error: GuardError)
+
+    transfer_funds
+    success(transfer: transfer)
+  end
+end
+```
+
+The `GuardError` includes all metadata:
+
+```ruby
+error = guard.error
+error.message     # "Account.status must be active (got suspended)"
+error.code        # "invalid_state"
+error.http_status # 422
+```
+
+## Naming Convention
+
+Guard class names are converted to method names by stripping the `Guard` suffix and converting to snake_case:
+
+| Class Name | Bang Method | Predicate Method |
+|------------|-------------|------------------|
+| `SufficientBalanceGuard` | `enforce_sufficient_balance!` | `check_sufficient_balance?` |
+| `ValidAmountGuard` | `enforce_valid_amount!` | `check_valid_amount?` |
+| `AuthorizedGuard` | `enforce_authorized!` | `check_authorized?` |
+
+The built-in guards follow this pattern: `TruthyGuard` -> `enforce_truthy!` / `check_truthy?`.
+
+## Rails Auto-Loading
+
+In Rails, guards in `app/guards/` are automatically loaded. Files must follow the `*_guard.rb` naming convention:
+
+```
+app/guards/
+├── sufficient_balance_guard.rb
+├── valid_amount_guard.rb
+└── authorized_guard.rb
+```
+
+## Configuration
+
+Disable built-in guards if you want to define your own (you can have both):
+
+```ruby
+Servus.configure do |config|
+  config.include_default_guards = false        # Default: true
+  config.guards_dir             = 'app/guards' # Default: 'app/guards'
+end
+```
+
+## Testing Guards
+
+Test guards in isolation:
+
+```ruby
+RSpec.describe Servus::Guards::TruthyGuard do
+  let(:user_class) do
+    Struct.new(:active, :verified, keyword_init: true) do
+      def self.name
+        'User'
+      end
+    end
+  end
+
+  describe '#test' do
+    it 'passes when attribute is truthy' do
+      user = user_class.new(active: true)
+      guard = described_class.new(on: user, check: :active)
+      expect(guard.test(on: user, check: :active)).to be true
+    end
+
+    it 'fails when attribute is falsey' do
+      user = user_class.new(active: false)
+      guard = described_class.new(on: user, check: :active)
+      expect(guard.test(on: user, check: :active)).to be false
+    end
+  end
+
+  describe '#error' do
+    it 'returns GuardError with correct metadata' do
+      user = user_class.new(active: false)
+      guard = described_class.new(on: user, check: :active)
+      error = guard.error
+
+      expect(error.code).to eq('must_be_truthy')
+      expect(error.message).to include('User', 'active', 'false')
+      expect(error.http_status).to eq(422)
+    end
+  end
+end
+```
+
+Test guards in service integration:
+
+```ruby
+RSpec.describe TransferService do
+  it 'fails when account is not active' do
+    result = described_class.call(
+      from_account: suspended_account,
+      to_account: recipient,
+      amount: 100
+    )
+
+    expect(result).to be_failure
+    expect(result.error.code).to eq('invalid_state')
+  end
+end
+```