servus 0.1.3 → 0.1.5

data/docs/core/1_overview.md

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

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

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