servus 0.1.3 → 0.1.5

data/docs/guides/2_migration_guide.md

@@ -0,0 +1,175 @@
+# @title Guides / 2. Migration Guide
+
+# Migration Guide
+
+Strategies for adopting Servus in existing Rails applications.
+
+## Incremental Adoption
+
+Servus coexists with existing code - no need to rewrite your entire application. Start with one complex use case, validate the pattern works for your team, then expand gradually.
+
+## Extracting from Fat Controllers
+
+Identify controller actions with complex business logic and extract to services:
+
+**Before**:
+```ruby
+class OrdersController < ApplicationController
+  def create
+    # 50 lines of business logic
+    # Multiple model operations
+    # External API calls
+    # Email sending
+  end
+end
+```
+
+**After**:
+```ruby
+class OrdersController < ApplicationController
+  def create
+    result = Orders::Create::Service.call(order_params)
+    if result.success?
+      render json: { order: result.data[:order] }, status: :created
+    else
+      render json: { error: result.error.api_error }, status: :unprocessable_entity
+    end
+  end
+end
+
+# Or use the helper
+class OrdersController < ApplicationController
+  include Servus::Helpers::ControllerHelpers
+
+  def create
+    run_service(Orders::Create::Service, order_params) do |result|
+      render json: { order: result.data[:order] }, status: :created
+    end
+  end
+end
+```
+
+## Extracting from Fat Models
+
+Move orchestration logic from models to services. Keep data-related methods in models:
+
+**Before**:
+```ruby
+class Order < ApplicationRecord
+  def complete_purchase
+    charge_payment
+    update_inventory
+    send_confirmation_email
+    create_invoice
+  end
+end
+```
+
+**After**:
+```ruby
+class Order < ApplicationRecord
+  # Model focuses on data
+  validates :total, presence: true
+  belongs_to :user
+end
+
+class Orders::CompletePurchase::Service < Servus::Base
+  # Service handles orchestration
+  def initialize(order_id:)
+    @order_id = order_id
+  end
+
+  def call
+    order = Order.find(@order_id)
+    Payments::Charge::Service.call(order_id: order.id)
+    Inventory::Update::Service.call(order_id: order.id)
+    Mailers::SendConfirmation::Service.call(order_id: order.id)
+    success(order: order)
+  end
+end
+```
+
+## Replacing Callbacks
+
+Extract callback logic to explicit service calls:
+
+**Before**:
+```ruby
+class User < ApplicationRecord
+  after_create :send_welcome_email
+  after_create :create_default_account
+  after_update :notify_changes, if: :email_changed?
+end
+```
+
+**After**:
+```ruby
+class User < ApplicationRecord
+  # Minimal or no callbacks
+end
+
+class Users::Create::Service < Servus::Base
+  def call
+    user = User.create!(params)
+    send_welcome_email(user)
+    create_default_account(user)
+    success(user: user)
+  end
+end
+```
+
+## Migrating Background Jobs
+
+Extract job logic to services, call via `.call_async`:
+
+**Before**:
+```ruby
+class ProcessOrderJob < ApplicationJob
+  def perform(order_id)
+    # 50 lines of business logic
+  end
+end
+
+ProcessOrderJob.perform_later(order.id)
+```
+
+**After**:
+```ruby
+class Orders::Process::Service < Servus::Base
+  def initialize(order_id:)
+    @order_id = order_id
+  end
+
+  def call
+    # Business logic
+  end
+end
+
+Orders::Process::Service.call_async(order_id: order.id)
+```
+
+Now the service can be called synchronously (from console, tests) or asynchronously (from controllers, jobs).
+
+## Testing During Migration
+
+Keep existing tests working while adding service tests:
+
+```ruby
+# Keep existing controller test
+describe OrdersController do
+  it "creates order" do
+    post :create, params: params
+    expect(response).to be_successful
+  end
+end
+
+# Add service test
+describe Orders::Create::Service do
+  it "creates order" do
+    result = described_class.call(params)
+    expect(result.success?).to be true
+  end
+end
+```
+
+Remove legacy tests after service tests prove comprehensive.

data/docs/integration/1_configuration.md

@@ -0,0 +1,104 @@
+# @title Integration / 1. Configuration
+
+# Configuration
+
+Servus works without configuration. Optional settings exist for customizing directories and event validation.
+
+## Directory Configuration
+
+Configure where Servus looks for schemas, services, and event handlers:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  # Default: 'app/schemas'
+  config.schemas_dir = 'app/schemas'
+
+  # Default: 'app/services'
+  config.services_dir = 'app/services'
+
+  # Default: 'app/events'
+  config.events_dir = 'app/events'
+end
+```
+
+These affect legacy file-based schemas and handler auto-loading. Schemas defined via the `schema` DSL method do not use files.
+
+## Schema Cache
+
+Schemas are cached after first load for performance. Clear the cache during development when schemas change:
+
+```ruby
+Servus::Support::Validator.clear_cache!
+```
+
+In production, schemas are deployed with code - no need to clear cache.
+
+## Log Level
+
+Servus uses `Rails.logger` (or stdout in non-Rails apps). Control logging via Rails configuration:
+
+```ruby
+# config/environments/production.rb
+config.log_level = :info  # Hides DEBUG argument logs
+```
+
+## ActiveJob Configuration
+
+Async execution uses ActiveJob. Configure your adapter:
+
+```ruby
+# config/application.rb
+config.active_job.queue_adapter = :sidekiq
+config.active_job.default_queue_name = :default
+```
+
+Servus respects ActiveJob queue configuration - no Servus-specific setup needed.
+
+## Event Bus Configuration
+
+### Strict Event Validation
+
+Enable strict validation to catch handlers subscribing to events that aren't emitted by any service:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  # Default: true
+  config.strict_event_validation = true
+end
+```
+
+When enabled, you can validate handlers at boot or in CI:
+
+```ruby
+# In a rake task or initializer
+Servus::EventHandler.validate_all_handlers!
+```
+
+This raises `Servus::Events::OrphanedHandlerError` if any handler subscribes to a non-existent event.
+
+### Handler Auto-Loading
+
+In Rails, handlers in `app/events/` are automatically loaded. The Railtie:
+- Clears the event bus on reload in development
+- Eager-loads all `*_handler.rb` files from `config.events_dir`
+
+```
+app/events/
+├── user_created_handler.rb
+├── payment_processed_handler.rb
+└── order_completed_handler.rb
+```
+
+### Event Instrumentation
+
+Events are instrumented via ActiveSupport::Notifications with the prefix `servus.events.`:
+
+```ruby
+# Subscribe to all Servus events
+ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, *args|
+  event_name = name.sub('servus.events.', '')
+  Rails.logger.info "Event: #{event_name}"
+end
+```

data/docs/integration/2_testing.md

@@ -0,0 +1,287 @@
+# @title Integration / 2. Testing
+
+# Testing
+
+Services are designed for easy testing with explicit inputs (arguments) and outputs (Response objects). No special test infrastructure needed.
+
+## Schema Example Helpers
+
+Servus provides test helpers that extract `example` values from your JSON schemas, making it easy to generate test fixtures without maintaining separate factories.
+
+### Setup
+
+Include the helpers in your test suite:
+
+```ruby
+# spec/spec_helper.rb
+require 'servus/testing'
+
+RSpec.configure do |config|
+  config.include Servus::Testing::ExampleBuilders
+end
+```
+
+### Using Schema Examples
+
+Add `example` or `examples` keywords to your schemas:
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  schema(
+    arguments: {
+      type: "object",
+      properties: {
+        user_id: { type: "integer", example: 123 },
+        amount: { type: "number", example: 100.0 },
+        currency: { type: "string", examples: ["USD", "EUR", "GBP"] }
+      }
+    },
+    result: {
+      type: "object",
+      properties: {
+        transaction_id: { type: "string", example: "txn_abc123" },
+        status: { type: "string", example: "approved" }
+      }
+    }
+  )
+end
+```
+
+Then use the helpers in your tests:
+
+```ruby
+RSpec.describe ProcessPayment::Service do
+  it "processes payment successfully" do
+    # Extract examples from schema and override specific values
+    args = servus_arguments_example(ProcessPayment::Service, amount: 50.0)
+    # => { user_id: 123, amount: 50.0, currency: "USD" }
+
+    result = ProcessPayment::Service.call(**args)
+
+    expect(result).to be_success
+    expect(result.data.keys).to match_array(
+      servus_result_example(ProcessPayment::Service).data.keys
+    )
+  end
+
+  it "handles different currencies" do
+    %w[USD EUR GBP].each do |currency|
+      result = ProcessPayment::Service.call(
+        **servus_arguments_example(ProcessPayment::Service, currency: currency)
+      )
+      expect(result).to be_success
+    end
+  end
+end
+```
+
+### Deep Merging
+
+Overrides are deep-merged with schema examples, allowing you to override nested values:
+
+```ruby
+# Schema has nested structure
+args = servus_arguments_example(
+  CreateUser::Service,
+  user: { profile: { age: 35 } }
+)
+# => { user: { id: 1, profile: { name: 'Alice', age: 35 } } }
+```
+
+### Available Helpers
+
+- `servus_arguments_example(ServiceClass, **overrides)` - Returns hash of argument examples
+- `servus_result_example(ServiceClass, **overrides)` - Returns Response object with result examples
+
+## Basic Testing Pattern
+
+```ruby
+RSpec.describe ProcessPayment::Service do
+  describe ".call" do
+    let(:user) { create(:user, balance: 1000) }
+
+    subject(:result) { described_class.call(user_id: user.id, amount: amount) }
+
+    context "with sufficient balance" do
+      let(:amount) { 50 }
+
+      it "processes payment" do
+        expect(result.success?).to be true
+        expect(result.data[:new_balance]).to eq(950)
+        expect(result.reload.balance).to eq(950)
+      end
+    end
+
+    context "with insufficient balance" do
+      let(:amount) { 2000 }
+
+      it "returns failure" do
+        expect(result.success?).to be false
+        expect(result.error.message).to eq("Insufficient funds")
+        expect(result.error).to be_a(Servus::Support::Errors::ServiceError)
+      end
+    end
+  end
+end
+```
+
+## Testing Service Composition
+
+When testing services that call other services, mock the child services:
+
+```ruby
+describe Users::CreateWithAccount::Service do
+  # Make local or global helpers to clean up tests
+  def servus_success_result(data)
+    Servus::Support::Response.new(success: true, data: data, error: nil)
+  end
+
+  it "calls both create services" do
+    # Mock child services
+    allow(Users::Create::Service).to receive(:call).and_return(servus_success_result{ user: user })
+    allow(Accounts::Create::Service).to receive(:call).and_return(servus_success_result{ account: account })
+
+    result = described_class.call(email: "test@example.com", plan: "premium")
+
+    expect(Users::Create::Service).to have_received(:call)
+    expect(Accounts::Create::Service).to have_received(:call)
+
+    expect(result.success?).to be true
+  end
+end
+```
+
+## Testing Schema Validation
+
+Don't test that valid arguments pass validation - that's testing the framework. Do test that your schema catches invalid inputs:
+
+```ruby
+it "validates required fields" do
+  expect {
+    Service.call(invalid: "params")
+  }.to raise_error(Servus::Support::Errors::ValidationError, /required/)
+end
+```
+
+## Testing Event Emission
+
+Servus provides RSpec matchers for testing that services emit events.
+
+### Setup
+
+Include the matchers in your test suite:
+
+```ruby
+# spec/spec_helper.rb
+require 'servus/testing'
+```
+
+### emit_event Matcher
+
+Assert that a block emits an event:
+
+```ruby
+RSpec.describe CreateUser::Service do
+  it 'emits user_created event on success' do
+    expect {
+      described_class.call(email: 'test@example.com', name: 'Test')
+    }.to emit_event(:user_created)
+  end
+
+  it 'emits event with expected payload' do
+    expect {
+      described_class.call(email: 'test@example.com', name: 'Test')
+    }.to emit_event(:user_created).with(hash_including(email: 'test@example.com'))
+  end
+
+  # Using handler class instead of symbol
+  it 'emits to UserCreatedHandler' do
+    expect {
+      described_class.call(email: 'test@example.com', name: 'Test')
+    }.to emit_event(UserCreatedHandler)
+  end
+end
+```
+
+### call_service Matcher
+
+Assert that a handler invokes a service:
+
+```ruby
+RSpec.describe UserCreatedHandler do
+  let(:payload) { { user_id: 123, email: 'test@example.com' } }
+
+  it 'invokes SendWelcomeEmail::Service' do
+    expect {
+      described_class.handle(payload)
+    }.to call_service(SendWelcomeEmail::Service).with(user_id: 123)
+  end
+
+  it 'invokes service asynchronously' do
+    expect {
+      described_class.handle(payload)
+    }.to call_service(SendWelcomeEmail::Service).async
+  end
+end
+```
+
+### Testing EventHandler Directly
+
+Test handlers by calling their `handle` class method:
+
+```ruby
+RSpec.describe UserCreatedHandler do
+  let(:payload) { { user_id: 123, email: 'test@example.com' } }
+
+  before do
+    allow(SendWelcomeEmail::Service).to receive(:call_async)
+    allow(TrackAnalytics::Service).to receive(:call_async)
+  end
+
+  it 'invokes SendWelcomeEmail with mapped arguments' do
+    described_class.handle(payload)
+
+    expect(SendWelcomeEmail::Service)
+      .to have_received(:call_async)
+      .with(user_id: 123, email: 'test@example.com')
+  end
+
+  it 'invokes TrackAnalytics with event data' do
+    described_class.handle(payload)
+
+    expect(TrackAnalytics::Service)
+      .to have_received(:call_async)
+      .with(event: 'user_created', user_id: 123)
+  end
+
+  context 'with conditional invocation' do
+    it 'skips premium rewards for non-premium users' do
+      allow(GrantPremiumRewards::Service).to receive(:call)
+
+      described_class.handle(payload.merge(premium: false))
+
+      expect(GrantPremiumRewards::Service).not_to have_received(:call)
+    end
+  end
+end
+```
+
+### Testing Event Emission from Handler
+
+Test the `emit` class method:
+
+```ruby
+RSpec.describe UserCreatedHandler do
+  it 'emits the user_created event' do
+    expect {
+      described_class.emit({ user_id: 123, email: 'test@example.com' })
+    }.to emit_event(:user_created)
+  end
+
+  it 'validates payload against schema' do
+    expect {
+      described_class.emit({ invalid: 'payload' })
+    }.to raise_error(Servus::Support::Errors::ValidationError)
+  end
+end
+```

data/docs/integration/3_rails_integration.md

@@ -0,0 +1,99 @@
+# @title Integration / 3. Rails Integration
+
+# Rails Integration
+
+Servus core works in any Ruby application. Rails-specific features (async, controller helpers, generators) are optional additions that integrate with Rails conventions.
+
+## Controller Integration
+
+Use the `run_service` helper to call services from controllers with automatic error handling:
+
+```ruby
+class UsersController < ApplicationController
+  include Servus::Helpers::ControllerHelpers
+
+  def create
+    run_service(Users::Create::Service, user_params)
+  end
+
+  # Failures automatically render JSON:
+  # { "error": { "code": "validation_error", "message": "..." } }
+  # with appropriate HTTP status code
+  #
+  # Success will go to view and service result will be available on @result
+end
+```
+
+Without the helper, handle responses manually:
+
+```ruby
+def create
+  result = Users::Create::Service.call(user_params)
+  if result.success?
+    render json: { user: result.data[:user] }, status: :created
+  else
+    render json: { error: result.error.api_error }, status: error_status(result.error)
+  end
+end
+```
+
+## Generator
+
+Generate services with specs and schema files:
+
+```bash
+rails generate servus:service process_payment
+
+# Creates:
+# app/services/process_payment/service.rb
+# spec/services/process_payment/service_spec.rb
+# app/schemas/services/process_payment/arguments.json
+# app/schemas/services/process_payment/result.json
+```
+
+Schema files are optional - delete them if you don't need validation.
+
+## Autoloading
+
+Servus follows Rails autoloading conventions. Services in `app/services/` are automatically loaded by Rails:
+
+```ruby
+# app/services/users/create/service.rb
+module Users
+  module Create
+    class Service < Servus::Base
+      # ...
+    end
+  end
+end
+
+# Rails autoloads this as Users::Create::Service
+```
+
+## Configuration
+
+Configure Servus in an initializer if needed:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  config.schema_root = Rails.root.join('config/schemas')
+end
+```
+
+Most applications don't need any configuration.
+
+## Background Jobs
+
+Async execution requires ActiveJob setup. Configure your adapter:
+
+```ruby
+# config/application.rb
+config.active_job.queue_adapter = :sidekiq
+```
+
+Then use `.call_async`:
+
+```ruby
+Users::SendWelcomeEmail::Service.call_async(user_id: user.id)
+```