servus 0.2.1 → 0.4.0

data/Rakefile

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require 'fileutils'
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-
-# Constants
-GEM_NAME   = 'servus'
-BUILDS_DIR = 'builds'
-
-RSpec::Core::RakeTask.new(:spec)
-
-require 'rubocop/rake_task'
-
-RuboCop::RakeTask.new
-
-# Build gem
-task :build do
-  FileUtils.mkdir_p(BUILDS_DIR)
-
-  # Build gem in current directory
-  sh "gem build #{GEM_NAME}.gemspec"
-
-  # Move to builds directory
-  gem_file = Dir["#{GEM_NAME}-*.gem"].first
-  if gem_file
-    FileUtils.mv(gem_file, BUILDS_DIR)
-    puts "Moved #{gem_file} to #{BUILDS_DIR}/"
-  end
-end
-
-# Install gem locally
-task install: :build do
-  gem_file = Dir["#{BUILDS_DIR}/#{GEM_NAME}-*.gem"].max_by { |f| File.mtime(f) }
-  sh "gem install #{gem_file}"
-end
-
-# Publish gem to RubyGems.org
-task publish: :build do
-  gem_file = Dir["#{BUILDS_DIR}/#{GEM_NAME}-*.gem"].max_by { |f| File.mtime(f) }
-  puts "Publishing #{gem_file} to RubyGems.org..."
-  sh "gem push #{gem_file}"
-end
-
-task default: %i[spec rubocop]

data/docs/core/1_overview.md

@@ -1,77 +0,0 @@
-# @title Core / 1. Overview
-
-# Servus Overview
-
-Servus is a lightweight framework for implementing service objects in Ruby applications. It extracts business logic from controllers and models into testable, single-purpose classes with built-in validation, error handling, and logging.
-
-## Core Concepts
-
-### The Service Pattern
-
-Services encapsulate one business operation. Each service inherits from `Servus::Base`, implements `initialize` and `call`, and returns a `Response` object indicating success or failure.
-
-```ruby
-class ProcessPayment::Service < Servus::Base
-  def initialize(user_id:, amount:)
-    @user_id = user_id
-    @amount = amount
-  end
-
-  def call
-    user = User.find(@user_id)
-    return failure("Insufficient funds") unless user.balance >= @amount
-
-    user.update!(balance: user.balance - @amount)
-    success(user: user, new_balance: user.balance)
-  end
-end
-
-# Usage
-result = ProcessPayment::Service.call(user_id: 1, amount: 50)
-result.success? # => true
-result.data     # => { user: #<User>, new_balance: 950 }
-```
-
-### Response Objects
-
-Services return `Response` objects instead of raising exceptions for business failures. This makes success and failure paths explicit and enables service composition without exception handling.
-
-```ruby
-result = SomeService.call(params)
-if result.success?
-  result.data  # Hash or object returned by success()
-else
-  result.error # ServiceError instance
-  result.error.message
-  result.error.api_error # { code: :symbol, message: "string" }
-end
-```
-
-### Optional Schema Validation
-
-Services can define JSON schemas for arguments and results. Validation happens automatically before/after execution but is entirely optional.
-
-```ruby
-class Service < Servus::Base
-  schema(
-    arguments: {
-      type: "object",
-      required: ["user_id", "amount"],
-      properties: {
-        user_id: { type: "integer" },
-        amount: { type: "number", minimum: 0.01 }
-      }
-    }
-  )
-end
-```
-
-## When to Use Servus
-
-**Good fits**: Multi-step workflows, operations spanning multiple models, external API calls, background jobs, complex business logic.
-
-**Poor fits**: Simple CRUD, single-model operations, operations tightly coupled to one model.
-
-## Framework Integration
-
-Servus core works in any Ruby application. Rails-specific features (async via ActiveJob, controller helpers, generators) are optional additions. Services work without any configuration - just inherit from `Servus::Base` and implement your logic.

data/docs/core/2_architecture.md

@@ -1,120 +0,0 @@
-# @title Core / 2. Architecture
-
-# Architecture
-
-Servus wraps service execution with automatic validation, logging, and error handling. When you call `Service.call(**args)`, the framework orchestrates these concerns transparently.
-
-## Execution Flow
-
-```
-Arguments → Validation → Service#call → Result Validation → Event Emission → Logging → Response
-                ↓                              ↓                   ↓              ↓
-          ValidationError                ValidationError      EventHandlers   Benchmark
-```
-
-The framework intercepts the `.call` class method to inject cross-cutting concerns before and after your business logic runs. Your `call` instance method contains only business logic - validation, logging, event emission, and timing happen automatically.
-
-## Core Components
-
-**Servus::Base** (`lib/servus/base.rb`): Foundation class providing `.call()` orchestration and response helpers (`success`, `failure`, `error!`)
-
-**Support::Response** (`lib/servus/support/response.rb`): Immutable result object with `success?`, `data`, and `error` attributes
-
-**Support::Validator** (`lib/servus/support/validator.rb`): JSON Schema validation for arguments (before execution) and results (after execution). Schemas are cached after first load.
-
-**Support::Logger** (`lib/servus/support/logger.rb`): Automatic logging at DEBUG (calls with args), INFO (success), WARN (failures), ERROR (exceptions)
-
-**Support::Rescuer** (`lib/servus/support/rescuer.rb`): Declarative exception handling via `rescue_from` class method
-
-**Support::Errors** (`lib/servus/support/errors.rb`): HTTP-aligned error hierarchy (ServiceError, NotFoundError, ValidationError, etc.)
-
-**Events::Emitter** (`lib/servus/events/emitter.rb`): DSL for declaring events that services emit on success/failure
-
-**Events::Bus** (`lib/servus/events/bus.rb`): Central event router using ActiveSupport::Notifications for thread-safe dispatch
-
-**EventHandler** (`lib/servus/event_handler.rb`): Base class for handlers that subscribe to events and invoke services
-
-## Extension Points
-
-### Schema Validation
-
-Use the `schema` DSL method to define JSON Schema validation for arguments and results:
-
-```ruby
-class Service < Servus::Base
-  schema(
-    arguments: { type: "object", required: ["user_id"] },
-    result: { type: "object", required: ["user"] }
-  )
-end
-```
-
-### Declarative Error Handling
-
-Use `rescue_from` to convert exceptions into failures. Provide a custom error type or use a block for custom handling.
-
-```ruby
-class Service < Servus::Base
-  # Default error type
-  rescue_from Net::HTTPError, Timeout::Error, use: ServiceUnavailableError
-
-  # Custom handling with block
-  rescue_from ActiveRecord::RecordInvalid do |exception|
-    failure("Validation failed: #{exception.message}", type: ValidationError)
-  end
-end
-```
-
-### Support Classes
-
-Create helper classes in `app/services/service_name/support/*.rb`. These are namespaced to your service.
-
-```
-app/services/process_payment/
-├── service.rb
-└── support/
-    ├── payment_gateway.rb
-    └── receipt_formatter.rb
-```
-
-## Async Execution
-
-`Service.call_async(**args)` enqueues execution via ActiveJob. The service runs identically whether called sync or async.
-
-```ruby
-ProcessPayment::Service.call_async(
-  user_id: 1,
-  amount: 50,
-  queue: :critical,
-  wait: 5.minutes
-)
-```
-
-## Event-Driven Architecture
-
-Services can emit events that trigger downstream handlers. This decouples services from their side effects.
-
-```ruby
-# Service emits events
-class CreateUser::Service < Servus::Base
-  emits :user_created, on: :success
-end
-
-# Handler reacts to events
-class UserCreatedHandler < Servus::EventHandler
-  handles :user_created
-
-  invoke SendWelcomeEmail::Service, async: true do |payload|
-    { user_id: payload[:user_id] }
-  end
-end
-```
-
-See {file:docs/features/5_event_bus.md Event Bus} for full documentation.
-
-## Performance
-
-- Schema loading: Cached per class after first use
-- Validation overhead: ~1-5ms when schemas defined
-- Logging overhead: ~0.1ms per call
-- Total framework overhead: < 10ms per service call

data/docs/core/3_service_objects.md

@@ -1,121 +0,0 @@
-# @title Core / 3. Service Objects
-
-# Service Objects
-
-Service objects encapsulate one business operation into a testable, reusable class. They sit between controllers and models, handling orchestration logic that doesn't belong in either.
-
-## The Pattern
-
-Services implement two methods: `initialize` (sets up dependencies) and `call` (executes business logic). All services return a `Response` object indicating success or failure.
-
-```ruby
-module Users
-  module Create
-    class Service < Servus::Base
-      def initialize(email:, name:)
-        @email = email
-        @name = name
-      end
-
-      def call
-        return failure("Email taken") if User.exists?(email: @email)
-
-        user = User.create!(email: @email, name: @name)
-        send_welcome_email(user)
-
-        success(user: user)
-      end
-    end
-  end
-end
-
-# Usage
-result = Users::Create::Service.call(email: "user@example.com", name: "John")
-result.success? # => true
-result.data[:user] # => #<User>
-```
-
-## Service Composition
-
-Services can call other services. Use the returned Response to decide whether to continue or propagate the failure.
-
-```ruby
-def call
-  user_result = Users::Create::Service.call(user_params)
-  return user_result unless user_result.success? # propogates result failure
-
-  account_result = Accounts::Create::Service.call(
-    user: user_result.data[:user],
-    plan: @plan
-  )
-  return account_result unless account_result.success? # propogates result failure
-
-  success(
-    user: user_result.data[:user],
-    account: account_result.data[:account]
-  )
-end
-```
-
-## When to Extract to Services
-
-**Extract when**:
-- Logic spans multiple models
-- Complex conditional branching
-- External API calls
-- Background processing needed
-- Testing requires extensive setup
-
-**Don't extract when**:
-- Simple CRUD operations
-- Single-model updates
-- Logic naturally belongs in model
-
-## Directory Structure
-
-Each service lives in its own namespace to avoid naming collisions and allow for support classes.
-
-```
-app/services/
-├── users/
-│   └── create/
-│       ├── service.rb
-│       └── support/
-│           └── welcome_email.rb
-└── orders/
-    └── process/
-        ├── service.rb
-        └── support/
-            ├── payment_gateway.rb
-            └── inventory_updater.rb
-```
-
-Support classes are private to their service - they should never be used by other services.
-
-## Testing
-
-Services are designed for easy testing with explicit inputs and outputs.
-
-```ruby
-RSpec.describe Users::Create::Service do
-  describe ".call" do
-    context "with valid params" do
-      it "creates user" do
-        result = described_class.call(email: "test@example.com", name: "Test")
-        expect(result.success?).to be true
-        expect(result.data[:user]).to be_persisted
-      end
-    end
-
-    context "with duplicate email" do
-      before { create(:user, email: "test@example.com") }
-
-      it "returns failure" do
-        result = described_class.call(email: "test@example.com", name: "Test")
-        expect(result.success?).to be false
-        expect(result.error.message).to eq("Email taken")
-      end
-    end
-  end
-end
-```

data/docs/features/1_schema_validation.md

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

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

@@ -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