servus 0.3.0 → 0.4.0

data/docs/features/3_async_execution.md

@@ -1,81 +0,0 @@
-# @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

@@ -1,64 +0,0 @@
-# @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

@@ -1,244 +0,0 @@
-# @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
-```