servus 0.1.3 → 0.1.4

data/docs/features/1_schema_validation.md

@@ -0,0 +1,119 @@
+# @title Features / 1. Schema Validation
+
+# Schema Validation
+
+Servus provides optional JSON Schema validation for service arguments and results. Validation is opt-in - services work fine without schemas.
+
+## How It Works
+
+Define schemas using the `schema` DSL method (recommended) or as constants. The framework validates arguments before execution and results after execution. Invalid data raises `ValidationError`.
+
+### Preferred: Schema DSL Method
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  schema(
+    arguments: {
+      type: "object",
+      required: ["user_id", "amount"],
+      properties: {
+        user_id: { type: "integer", example: 123 },
+        amount: { type: "number", minimum: 0.01, example: 100.0 }
+      }
+    },
+    result: {
+      type: "object",
+      required: ["transaction_id", "new_balance"],
+      properties: {
+        transaction_id: { type: "string", example: "txn_abc123" },
+        new_balance: { type: "number", example: 950.0 }
+      }
+    }
+  )
+end
+```
+
+**Pro tip:** Add `example` or `examples` keywords to your schemas. These values can be automatically extracted in tests using `servus_arguments_example()` and `servus_result_example()` helpers. See the [Testing documentation](../integration/testing.md#schema-example-helpers) for details.
+
+You can define just one schema if needed:
+
+```ruby
+class SendEmail::Service < Servus::Base
+  schema arguments: {
+    type: "object",
+    required: ["email", "subject"],
+    properties: {
+      email: { type: "string", format: "email" },
+      subject: { type: "string" }
+    }
+  }
+end
+```
+
+### Alternative: Inline Constants
+
+Constants are still supported for backwards compatibility:
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  ARGUMENTS_SCHEMA = {
+    type: "object",
+    required: ["user_id", "amount"],
+    properties: {
+      user_id: { type: "integer" },
+      amount: { type: "number", minimum: 0.01 }
+    }
+  }.freeze
+
+  RESULT_SCHEMA = {
+    type: "object",
+    required: ["transaction_id", "new_balance"],
+    properties: {
+      transaction_id: { type: "string" },
+      new_balance: { type: "number" }
+    }
+  }.freeze
+end
+```
+
+## File-Based Schemas
+
+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`
+
+### Schema Lookup Precedence
+
+Servus checks for schemas in this order:
+1. **schema DSL method** (if defined)
+2. **Inline constants** (ARGUMENTS_SCHEMA, RESULT_SCHEMA)
+3. **JSON files** (in schema_root directory)
+
+Schemas are cached after first load for performance.
+
+## Three Layers of Validation
+
+**Schema Validation** (Servus): Type safety and structure at service boundaries
+
+**Business Rules** (Service Logic): Domain-specific constraints during execution
+
+**Model Validation** (ActiveRecord): Database constraints before persistence
+
+Each layer has a different purpose - don't duplicate validation across layers.
+
+## Configuration
+
+Change the schema file location if needed:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  config.schema_root = Rails.root.join('config/schemas')
+end
+```
+
+Clear the schema cache during development when schemas change:
+
+```ruby
+Servus::Support::Validator.clear_cache!
+```

data/docs/features/2_error_handling.md

@@ -0,0 +1,121 @@
+# @title Features / 2. Error Handling
+
+# Error Handling
+
+Servus distinguishes between expected business failures (return failure) and unexpected system errors (raise exceptions). This separation makes error handling predictable and explicit.
+
+## Failures vs Exceptions
+
+**Use `failure()`** for expected business conditions:
+- User not found
+- Insufficient balance
+- Invalid state transition
+
+**Use `error!()` or raise** for unexpected system errors:
+- Database connection failure
+- Nil reference error
+- External API timeout
+
+Failures return a Response object so callers can handle them. Exceptions halt execution and bubble up.
+
+```ruby
+def call
+  user = User.find_by(id: user_id)
+  return failure("User not found", type: NotFoundError) unless user
+  return failure("Insufficient funds") unless user.balance >= amount
+
+  user.update!(balance: user.balance - amount)  # Raises on system error
+  success(user: user)
+end
+```
+
+## Error Classes
+
+All error classes inherit from `ServiceError` and map to HTTP status codes. Use them for API-friendly errors.
+
+```ruby
+# Built-in errors
+NotFoundError          # 404
+BadRequestError        # 400
+UnauthorizedError      # 401
+ForbiddenError         # 403
+ValidationError        # 422
+InternalServerError    # 500
+ServiceUnavailableError # 503
+
+# Usage
+failure("Resource not found", type: NotFoundError)
+error!("Database corrupted", type: InternalServerError)  # Raises exception
+```
+
+Each error has an `api_error` method returning `{ code: :symbol, message: "string" }` for JSON APIs.
+
+## Declarative Exception Handling
+
+Use `rescue_from` to convert specific exceptions into failures. Original exception details are preserved in error messages.
+
+```ruby
+class CallExternalApi::Service < Servus::Base
+  rescue_from Net::HTTPError, Timeout::Error use: ServiceUnavailableError
+  rescue_from JSON::ParserError, use: BadRequestError
+
+  def call
+    response = http_client.get(url)  # May raise
+    data = JSON.parse(response.body) # May raise
+    success(data: data)
+  end
+end
+
+# If Net::HTTPError is raised, service returns:
+# Response(success: false, error: ServiceUnavailableError("[Net::HTTPError]: original message"))
+```
+
+The `rescue_from` pattern keeps business logic clean while ensuring consistent error handling across services.
+
+### Custom Error Handling with Blocks
+
+For more control over error handling, provide a block to `rescue_from`. The block receives the exception and can return either success or failure:
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  # Custom failure with error details
+  rescue_from ActiveRecord::RecordInvalid do |exception|
+    failure("Payment failed: #{exception.record.errors.full_messages.join(', ')}",
+            type: ValidationError)
+  end
+
+  # Recover from certain errors with success
+  rescue_from Stripe::CardError do |exception|
+    if exception.code == 'card_declined'
+      failure("Card was declined", type: BadRequestError)
+    else
+      # Log and continue for other card errors
+      Rails.logger.warn("Stripe error: #{exception.message}")
+      success(recovered: true, fallback_used: true)
+    end
+  end
+
+  def call
+    # Service logic that may raise exceptions
+  end
+end
+```
+
+The block has access to `success(data)` and `failure(message, type:)` methods. This allows conditional error handling and even recovering from exceptions.
+
+## Custom Errors
+
+Create domain-specific errors by inheriting from `ServiceError`:
+
+```ruby
+class InsufficientFundsError < Servus::Support::Errors::ServiceError
+  DEFAULT_MESSAGE = "Insufficient funds"
+
+  def api_error
+    { code: :insufficient_funds, message: message }
+  end
+end
+
+# Usage
+failure("Account balance too low", type: InsufficientFundsError)
+```

data/docs/features/3_async_execution.md

@@ -0,0 +1,81 @@
+# @title Features / 3. Async Execution
+
+# Async Execution
+
+Servus provides asynchronous execution via ActiveJob. Services run identically whether called sync or async - they're unaware of execution context.
+
+## Usage
+
+Call `.call_async(**args)` instead of `.call(**args)` to execute in the background. The service is enqueued immediately and executed by a worker.
+
+```ruby
+# Synchronous
+result = ProcessReport::Service.call(user_id: user.id, report_type: :monthly)
+result.data[:report] # Available immediately
+
+# Asynchronous
+ProcessReport::Service.call_async(user_id: user.id, report_type: :monthly)
+# Returns true if enqueued successfully
+# Result not available (service hasn't run yet)
+```
+
+Services must accept JSON-serializable arguments for async execution (primitives, hashes, arrays, ActiveRecord objects via GlobalID). Complex objects like Procs won't work.
+
+## Queue and Scheduling Options
+
+Pass ActiveJob options to control execution:
+
+```ruby
+ProcessReport::Service.call_async(
+  user_id: user.id,
+  queue: :critical,      # Specify queue
+  priority: 10,          # Higher priority
+  wait: 5.minutes        # Delay execution
+)
+```
+
+## Result Handling
+
+Async services can't return results to callers (the service hasn't executed yet). If you need results, implement persistence in the service:
+
+```ruby
+class GenerateReport::Service < Servus::Base
+  def call
+    report_data = generate_report
+
+    # Persist result
+    Report.create!(
+      user_id: @user_id,
+      data: report_data,
+      status: 'completed'
+    )
+
+    # Optionally notify user
+    UserMailer.report_ready(@user_id).deliver_now
+
+    success(data: report_data)
+  end
+end
+
+# Controller creates placeholder, service updates it
+report = Report.create!(user_id: user.id, status: 'pending')
+GenerateReport::Service.call_async(user_id: user.id, report_id: report.id)
+```
+
+## Error Handling
+
+Failures (business logic) don't trigger retries - the job completes successfully but returns a failure Response.
+
+Exceptions (system errors) trigger ActiveJob retry logic. Use `rescue_from` to convert transient errors into exceptions:
+
+```ruby
+class Service < Servus::Base
+  rescue_from Net::HTTPError, Timeout::Error use: ServiceUnavailableError
+end
+```
+
+## When to Use Async
+
+**Good candidates**: Email sending, report generation, data imports, long-running API calls, cleanup tasks
+
+**Poor candidates**: Operations requiring immediate feedback, fast operations (<100ms), critical path operations where user waits for result

data/docs/features/4_logging.md

@@ -0,0 +1,64 @@
+# @title Features / 4. Logging
+
+# Logging
+
+Servus automatically logs all service executions with timing information. No instrumentation code needed in services.
+
+## What Gets Logged
+
+**Service calls** (DEBUG): Service class name and arguments
+```
+[Servus] Users::Create::Service called with {:email=>"user@example.com", :name=>"John"}
+```
+
+**Successful completions** (INFO): Service class name and duration
+```
+[Servus] Users::Create::Service completed successfully in 0.0243s
+```
+
+**Failures** (WARN): Service class name, error type, message, and duration
+```
+[Servus] Users::Create::Service failed with NotFoundError: User not found (0.0125s)
+```
+
+**Exceptions** (ERROR): Service class name, exception type, message, and duration
+```
+[Servus] Users::Create::Service raised ArgumentError: Missing required field (0.0089s)
+```
+
+## Log Levels
+
+Servus uses Rails.logger and respects application log level configuration:
+
+- **DEBUG**: Shows arguments (use in development, hide in production to avoid logging sensitive data)
+- **INFO**: Shows completions (normal operations)
+- **WARN**: Shows business failures
+- **ERROR**: Shows system exceptions
+
+Set production log level to INFO to hide argument logging:
+
+```ruby
+# config/environments/production.rb
+config.log_level = :info
+```
+
+## Sensitive Data
+
+Arguments are logged at DEBUG level. In production, either:
+1. Set log level to INFO (recommended)
+2. Use Rails parameter filtering: `config.filter_parameters += [:password, :ssn, :credit_card]`
+3. Pass IDs instead of full objects: `Service.call(user_id: 1)` not `Service.call(user: user_object)`
+
+## Integration with Logging Tools
+
+The `[Servus]` prefix makes service logs easy to grep and filter:
+
+```bash
+# Find all service calls
+grep "\[Servus\]" production.log
+
+# Find slow services
+grep "completed" production.log | grep "Servus" | awk '{print $NF}' | sort -n
+```
+
+Servus logs work with structured logging tools (Lograge, Datadog, Splunk) without modification.

data/docs/guides/1_common_patterns.md

@@ -0,0 +1,90 @@
+# @title Guides / 1. Common Patterns
+
+# Common Patterns
+
+Common architectural patterns for using Servus effectively.
+
+## Parent-Child Services
+
+When one service orchestrates multiple sub-operations, decide on transaction boundaries and error propagation.
+
+```ruby
+class Orders::Checkout::Service < Servus::Base
+  def call
+    ActiveRecord::Base.transaction do
+      # Create order
+      order_result = Orders::Create::Service.call(order_params)
+      return order_result unless order_result.success?
+
+      # Charge payment
+      payment_result = Payments::Charge::Service.call(
+        user_id: @user_id,
+        amount: order_result.data[:order].total
+      )
+      return payment_result unless payment_result.success?
+
+      # Update inventory
+      inventory_result = Inventory::Reserve::Service.call(
+        order_id: order_result.data[:order].id
+      )
+      return inventory_result unless inventory_result.success?
+
+      success(order: order_result.data[:order])
+    end
+  end
+end
+```
+
+**Use parent transaction when**: All children must succeed or all roll back (atomic operation)
+
+**Use child transactions when**: Children can succeed independently (partial success acceptable)
+
+## Async with Result Persistence
+
+Store async results in database for later retrieval:
+
+```ruby
+# Controller creates placeholder
+report = Report.create!(user_id: user.id, status: 'pending')
+GenerateReport::Service.call_async(report_id: report.id)
+
+# Service updates record
+class GenerateReport::Service < Servus::Base
+  def call
+    report = Report.find(@report_id)
+    data = generate_report_data
+
+    report.update!(data: data, status: 'completed')
+    success(report: report)
+  end
+end
+```
+
+## Idempotent Services
+
+Use database constraints to make services idempotent:
+
+```ruby
+class Users::Create::Service < Servus::Base
+  def call
+    # Unique constraint on email prevents duplicates
+    user = User.create!(email: @email, name: @name)
+    success(user: user)
+  rescue ActiveRecord::RecordNotUnique
+    user = User.find_by!(email: @email)
+    success(user: user)  # Return existing user, not error
+  end
+end
+```
+
+Or check for existing resources explicitly:
+
+```ruby
+def call
+  existing = User.find_by(email: @email)
+  return success(user: existing) if existing
+
+  user = User.create!(email: @email, name: @name)
+  success(user: user)
+end
+```

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,51 @@
+# @title Integration / 1. Configuration
+
+# Configuration
+
+Servus works without configuration. One optional setting exists for schema file location.
+
+## Schema Root
+
+By default, Servus looks for schema JSON files in `Rails.root/app/schemas/services` (or `./app/schemas/services` in non-Rails apps).
+
+Change the location if needed:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  config.schema_root = Rails.root.join('config/schemas')
+end
+```
+
+This affects legacy file-based schemas only - 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.