servus 0.1.3 → 0.1.5

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/features/5_event_bus.md

@@ -0,0 +1,244 @@
+# @title Features / 5. Event Bus
+
+# Event Bus
+
+Servus includes an event-driven architecture for decoupling service logic from side effects. Services emit events, and EventHandlers subscribe to them and invoke downstream services.
+
+## Overview
+
+The Event Bus provides:
+- **Emitters**: Services declare events they emit on success/failure
+- **EventHandlers**: Subscribe to events and invoke services in response
+- **Event Bus**: Routes events to registered handlers via ActiveSupport::Notifications
+- **Payload Validation**: Optional JSON Schema validation for event payloads
+
+## Service Event Emission
+
+Services can emit events when they succeed or fail using the `emits` DSL:
+
+```ruby
+class CreateUser::Service < Servus::Base
+  emits :user_created, on: :success
+  emits :user_creation_failed, on: :failure
+
+  def initialize(email:, name:)
+    @email = email
+    @name = name
+  end
+
+  def call
+    user = User.create!(email: @email, name: @name)
+    success(user: user)
+  rescue ActiveRecord::RecordInvalid => e
+    failure(e.message)
+  end
+end
+```
+
+### Custom Payloads
+
+By default, success events receive `result.data` and failure events receive `result.error`. Customize with a block or method:
+
+```ruby
+class CreateUser::Service < Servus::Base
+  # Block-based payload
+  emits :user_created, on: :success do |result|
+    { user_id: result.data[:user].id, email: result.data[:user].email }
+  end
+
+  # Method-based payload
+  emits :user_stats_updated, on: :success, with: :stats_payload
+
+  private
+
+  def stats_payload(result)
+    { user_count: User.count, latest_user_id: result.data[:user].id }
+  end
+end
+```
+
+### Trigger Types
+
+- `:success` - Fires when service returns `success(...)`
+- `:failure` - Fires when service returns `failure(...)`
+- `:error!` - Fires when service calls `error!(...)` (before exception is raised)
+
+## Event Handlers
+
+EventHandlers live in `app/events/` and subscribe to events using a declarative DSL:
+
+```ruby
+# app/events/user_created_handler.rb
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  invoke SendWelcomeEmail::Service, async: true do |payload|
+    { user_id: payload[:user_id], email: payload[:email] }
+  end
+
+  invoke TrackAnalytics::Service, async: true do |payload|
+    { event: 'user_created', user_id: payload[:user_id] }
+  end
+end
+```
+
+### Generator
+
+Generate handlers with the Rails generator:
+
+```bash
+rails g servus:event_handler user_created
+# Creates:
+#   app/events/user_created_handler.rb
+#   spec/events/user_created_handler_spec.rb
+```
+
+### Invocation Options
+
+```ruby
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  # Synchronous invocation (default)
+  invoke NotifyAdmin::Service do |payload|
+    { message: "New user: #{payload[:email]}" }
+  end
+
+  # Async via ActiveJob
+  invoke SendWelcomeEmail::Service, async: true do |payload|
+    { user_id: payload[:user_id] }
+  end
+
+  # Async with specific queue
+  invoke SendWelcomeEmail::Service, async: true, queue: :mailers do |payload|
+    { user_id: payload[:user_id] }
+  end
+
+  # Conditional invocation
+  invoke GrantPremiumRewards::Service, if: ->(p) { p[:premium] } do |payload|
+    { user_id: payload[:user_id] }
+  end
+
+  invoke SkipForPremium::Service, unless: ->(p) { p[:premium] } do |payload|
+    { user_id: payload[:user_id] }
+  end
+end
+```
+
+## Emitting Events Directly
+
+EventHandlers provide an `emit` class method for emitting events from controllers, jobs, or other code without a service:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    user = User.create!(user_params)
+    UserCreatedHandler.emit({ user_id: user.id, email: user.email })
+    redirect_to user
+  end
+end
+```
+
+This is useful when the event source isn't a Servus service.
+
+## Payload Schema Validation
+
+Define JSON schemas to validate event payloads:
+
+```ruby
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  schema payload: {
+    type: 'object',
+    required: ['user_id', 'email'],
+    properties: {
+      user_id: { type: 'integer' },
+      email: { type: 'string', format: 'email' }
+    }
+  }
+
+  invoke SendWelcomeEmail::Service, async: true do |payload|
+    { user_id: payload[:user_id], email: payload[:email] }
+  end
+end
+```
+
+When `emit` is called, the payload is validated against the schema before the event is dispatched.
+
+## Handler Validation
+
+Enable strict validation to catch handlers subscribing to non-existent events:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  config.strict_event_validation = true  # Default: true
+end
+
+# Then manually validate (typically in a rake task or CI)
+Servus::EventHandler.validate_all_handlers!
+```
+
+This helps catch typos and orphaned handlers during development and CI.
+
+## Best Practices
+
+### Single Event Per Service
+
+Services should emit one event per trigger representing their core concern:
+
+```ruby
+# Good - one event, handler coordinates reactions
+class CreateUser::Service < Servus::Base
+  emits :user_created, on: :success
+end
+
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  invoke SendWelcomeEmail::Service, async: true
+  invoke TrackAnalytics::Service, async: true
+  invoke NotifySlack::Service, async: true
+end
+
+# Avoid - service doing too much coordination
+class CreateUser::Service < Servus::Base
+  emits :send_welcome_email, on: :success
+  emits :track_user_analytics, on: :success
+  emits :notify_slack, on: :success
+end
+```
+
+### Naming Conventions
+
+- Events: Past tense describing what happened (`user_created`, `payment_processed`)
+- Handlers: Event name + "Handler" suffix (`UserCreatedHandler`)
+
+### Handler Location
+
+Handlers live in `app/events/` and are auto-loaded by the Railtie:
+
+```
+app/events/
+├── user_created_handler.rb
+├── payment_processed_handler.rb
+└── order_completed_handler.rb
+```
+
+## Instrumentation
+
+Events are instrumented via ActiveSupport::Notifications and appear in Rails logs:
+
+```
+servus.events.user_created (1.2ms) {:user_id=>123, :email=>"user@example.com"}
+```
+
+Subscribe to events programmatically:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, *args|
+  event_name = name.sub('servus.events.', '')
+  Rails.logger.info "Event emitted: #{event_name}"
+end
+```

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
+```