light-services 2.2.1 → 3.0.0

data/docs/callbacks.md

@@ -0,0 +1,476 @@
+# Callbacks
+
+Callbacks are hooks that allow you to run custom code at specific points during service and step execution. They're perfect for logging, benchmarking, auditing, and other cross-cutting concerns.
+
+## TL;DR
+
+- Define callbacks using DSL methods like `before_service_run`, `after_step_run`, etc.
+- Use symbols (method names) or procs/lambdas
+- Callbacks are inherited from parent classes
+- Around callbacks wrap execution and must yield
+
+```ruby
+class User::Charge < ApplicationService
+  before_service_run :log_start
+  after_service_run :log_end
+  on_service_failure :notify_admin
+
+  around_step_run :benchmark_step
+
+  step :authorize
+  step :charge
+
+  private
+
+  def log_start(service)
+    Rails.logger.info "Starting #{service.class.name}"
+  end
+
+  def log_end(service)
+    Rails.logger.info "Finished #{service.class.name}"
+  end
+
+  def notify_admin(service)
+    AdminMailer.service_failed(service).deliver_later
+  end
+
+  def benchmark_step(service, step_name)
+    start = Time.current
+    yield
+    duration = Time.current - start
+    Rails.logger.info "Step #{step_name} took #{duration}s"
+  end
+end
+```
+
+## Available Callbacks
+
+### Service Callbacks
+
+| Callback | When it runs | Arguments |
+|----------|--------------|-----------|
+| `before_service_run` | Before the service starts executing steps | `(service)` |
+| `after_service_run` | After the service completes (success or failure) | `(service)` |
+| `around_service_run` | Wraps the entire service execution | `(service, &block)` |
+| `on_service_success` | After service completes without errors | `(service)` |
+| `on_service_failure` | After service completes with errors | `(service)` |
+
+### Step Callbacks
+
+| Callback | When it runs | Arguments |
+|----------|--------------|-----------|
+| `before_step_run` | Before each step executes | `(service, step_name)` |
+| `after_step_run` | After each step completes (success or failure) | `(service, step_name)` |
+| `around_step_run` | Wraps each step execution | `(service, step_name, &block)` |
+| `on_step_success` | After step completes without errors | `(service, step_name)` |
+| `on_step_failure` | When step produces errors | `(service, step_name)` |
+| `on_step_crash` | When step raises an exception | `(service, step_name, exception)` |
+
+{% hint style="info" %}
+Note the difference between `on_step_failure` and `on_step_crash`:
+- `on_step_failure` is called when a step adds errors (similar to `on_service_failure`)
+- `on_step_crash` is called when a step raises an exception
+
+When a step crashes (raises an exception), `after_step_run` is NOT called.
+{% endhint %}
+
+## Defining Callbacks
+
+### Using Symbols (Method Names)
+
+The most common way to define callbacks is using symbols that reference instance methods:
+
+```ruby
+class Order::Process < ApplicationService
+  before_service_run :log_start
+  after_service_run :log_end
+
+  step :validate
+  step :process
+  step :notify
+
+  private
+
+  def log_start(service)
+    Rails.logger.info "Processing order started"
+  end
+
+  def log_end(service)
+    Rails.logger.info "Processing order finished, success: #{service.success?}"
+  end
+end
+```
+
+### Using Procs/Lambdas
+
+For simple callbacks, you can use inline procs:
+
+```ruby
+class Order::Process < ApplicationService
+  before_service_run do |service|
+    Rails.logger.info "Starting #{service.class.name}"
+  end
+
+  after_service_run do |service|
+    Rails.logger.info "Completed with #{service.errors.count} errors"
+  end
+
+  on_step_failure do |service, step_name|
+    Rails.logger.warn "Step #{step_name} produced errors"
+  end
+
+  on_step_crash do |service, step_name, exception|
+    Bugsnag.notify(exception, step: step_name)
+  end
+
+  step :validate
+  step :process
+end
+```
+
+## Around Callbacks
+
+Around callbacks wrap execution and must call `yield` to continue:
+
+```ruby
+class Order::Process < ApplicationService
+  around_service_run :with_logging
+  around_step_run :with_timing
+
+  step :validate
+  step :process
+
+  private
+
+  def with_logging(service)
+    Rails.logger.info "=== Starting #{service.class.name} ==="
+    yield
+    Rails.logger.info "=== Finished #{service.class.name} ==="
+  end
+
+  def with_timing(service, step_name)
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    yield
+    duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+    Rails.logger.info "Step :#{step_name} completed in #{duration.round(3)}s"
+  end
+end
+```
+
+### Around Callbacks with Procs
+
+When using procs for around callbacks, the block is passed as the last argument:
+
+```ruby
+class Order::Process < ApplicationService
+  around_service_run do |service, block|
+    Rails.logger.info "Starting..."
+    block.call
+    Rails.logger.info "Finished!"
+  end
+
+  around_step_run do |service, step_name, block|
+    Rails.logger.info "Running step :#{step_name}"
+    block.call
+    Rails.logger.info "Completed step :#{step_name}"
+  end
+
+  step :process
+end
+```
+
+{% hint style="warning" %}
+Forgetting to call `yield` (or `block.call` for procs) in around callbacks will prevent the service/step from executing!
+{% endhint %}
+
+## Multiple Callbacks
+
+You can define multiple callbacks of the same type. They execute in the order they're defined:
+
+```ruby
+class Order::Process < ApplicationService
+  before_service_run :log_start
+  before_service_run :validate_environment
+  before_service_run :check_permissions
+
+  step :process
+
+  private
+
+  def log_start(service)
+    # Runs first
+  end
+
+  def validate_environment(service)
+    # Runs second
+  end
+
+  def check_permissions(service)
+    # Runs third
+  end
+end
+```
+
+### Multiple Around Callbacks
+
+Multiple around callbacks are nested, with the first one wrapping the second:
+
+```ruby
+class Order::Process < ApplicationService
+  around_service_run :outer_wrapper
+  around_service_run :inner_wrapper
+
+  step :process
+
+  private
+
+  def outer_wrapper(service)
+    puts "outer before"
+    yield
+    puts "outer after"
+  end
+
+  def inner_wrapper(service)
+    puts "inner before"
+    yield
+    puts "inner after"
+  end
+
+  # Output:
+  # outer before
+  # inner before
+  # (service executes)
+  # inner after
+  # outer after
+end
+```
+
+## Callback Inheritance
+
+Callbacks are inherited from parent classes. Child class callbacks run after parent callbacks:
+
+```ruby
+class ApplicationService < Light::Services::Base
+  before_service_run :log_service_start
+
+  private
+
+  def log_service_start(service)
+    Rails.logger.info "[#{service.class.name}] Starting"
+  end
+end
+
+class Order::Process < ApplicationService
+  before_service_run :validate_order
+
+  step :process
+
+  private
+
+  def validate_order(service)
+    # Runs after log_service_start
+  end
+end
+```
+
+### Deep Inheritance
+
+Callbacks accumulate through the inheritance chain:
+
+```ruby
+class BaseService < Light::Services::Base
+  before_service_run :base_callback
+end
+
+class MiddleService < BaseService
+  before_service_run :middle_callback
+end
+
+class ConcreteService < MiddleService
+  before_service_run :concrete_callback
+
+  # Execution order:
+  # 1. base_callback
+  # 2. middle_callback
+  # 3. concrete_callback
+end
+```
+
+## Execution Order
+
+### Service Callbacks Order
+
+```
+before_service_run
+  └── around_service_run (before yield)
+        └── [steps execute]
+      around_service_run (after yield)
+after_service_run
+on_service_success OR on_service_failure
+```
+
+### Step Callbacks Order (for each step)
+
+**Normal execution (no exception):**
+```
+before_step_run
+  └── around_step_run (before yield)
+        └── [step executes]
+      around_step_run (after yield)
+after_step_run
+on_step_success OR on_step_failure (if errors were added)
+```
+
+**Exception during step:**
+```
+before_step_run
+  └── around_step_run (before yield)
+        └── [step raises exception]
+on_step_crash
+[exception propagates]
+```
+
+## Use Cases
+
+### Logging
+
+```ruby
+class ApplicationService < Light::Services::Base
+  before_service_run :log_start
+  after_service_run :log_finish
+
+  private
+
+  def log_start(service)
+    Rails.logger.tagged(service.class.name) do
+      Rails.logger.info "Started with arguments: #{service.arguments.to_h}"
+    end
+  end
+
+  def log_finish(service)
+    Rails.logger.tagged(service.class.name) do
+      if service.success?
+        Rails.logger.info "Completed successfully"
+      else
+        Rails.logger.warn "Failed with errors: #{service.errors.full_messages}"
+      end
+    end
+  end
+end
+```
+
+### Benchmarking
+
+```ruby
+class ApplicationService < Light::Services::Base
+  around_service_run :benchmark
+
+  private
+
+  def benchmark(service)
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    yield
+    duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+    if duration > 1.0
+      Rails.logger.warn "#{service.class.name} took #{duration.round(2)}s"
+    end
+  end
+end
+```
+
+### Error Tracking
+
+```ruby
+class ApplicationService < Light::Services::Base
+  on_service_failure :track_failure
+  on_step_failure :track_step_error
+  on_step_crash :track_step_crash
+
+  private
+
+  def track_failure(service)
+    Bugsnag.notify("Service failed") do |report|
+      report.add_metadata(:service, {
+        class: service.class.name,
+        errors: service.errors.full_messages,
+        arguments: service.arguments.to_h
+      })
+    end
+  end
+
+  def track_step_error(service, step_name)
+    Rails.logger.warn "Step :#{step_name} produced errors in #{service.class.name}"
+  end
+
+  def track_step_crash(service, step_name, exception)
+    Bugsnag.notify(exception) do |report|
+      report.add_metadata(:service, {
+        class: service.class.name,
+        step: step_name
+      })
+    end
+  end
+end
+```
+
+### Audit Trail
+
+```ruby
+class Order::Process < ApplicationService
+  after_service_run :create_audit_log
+
+  arg :order, type: Order
+  arg :current_user, type: User
+
+  step :process
+
+  private
+
+  def create_audit_log(service)
+    AuditLog.create!(
+      user: current_user,
+      action: "order.process",
+      resource: order,
+      success: service.success?,
+      metadata: {
+        errors: service.errors.full_messages
+      }
+    )
+  end
+end
+```
+
+### Database Instrumentation
+
+```ruby
+class ApplicationService < Light::Services::Base
+  around_step_run :track_queries
+
+  private
+
+  def track_queries(service, step_name)
+    query_count = 0
+    
+    subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do
+      query_count += 1
+    end
+
+    yield
+
+    ActiveSupport::Notifications.unsubscribe(subscriber)
+    
+    if query_count > 10
+      Rails.logger.warn "Step :#{step_name} executed #{query_count} queries"
+    end
+  end
+end
+```
+
+## What's Next?
+
+Learn about testing your services, including how to test callbacks.
+
+[Next: Testing](testing.md)
+
+

data/docs/concepts.md

@@ -0,0 +1,80 @@
+# Concepts
+
+This section covers the core concepts of Light Services: **Arguments**, **Steps**, **Outputs**, **Context**, **Errors**, and **Callbacks**.
+
+## Service Execution Flow
+
+When you call `MyService.run(args)`, the following happens:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Service.run(args)                       │
+├─────────────────────────────────────────────────────────────┤
+│  1. Load default values for arguments and outputs            │
+│  2. Validate argument types                                  │
+│  3. Run before_service_run callbacks                         │
+├─────────────────────────────────────────────────────────────┤
+│  4. Begin around_service_run callback                        │
+│  5. Begin database transaction (if use_transactions: true)   │
+│     ┌─────────────────────────────────────────────────────┐ │
+│     │  6. Execute steps in order                          │ │
+│     │     - Run before_step_run / around_step_run         │ │
+│     │     - Execute step method                           │ │
+│     │     - Run after_step_run / on_step_success          │ │
+│     │     - Skip if condition (if:/unless:) not met       │ │
+│     │     - Stop if errors.break? is true                 │ │
+│     │     - Stop if done! was called                      │ │
+│     ├─────────────────────────────────────────────────────┤ │
+│     │  7. On error → Rollback transaction                 │ │
+│     │     On success → Commit transaction                 │ │
+│     └─────────────────────────────────────────────────────┘ │
+│  8. End around_service_run callback                          │
+├─────────────────────────────────────────────────────────────┤
+│  9. Run steps marked with always: true (unless done! called) │
+│ 10. Validate output types (if success)                       │
+│ 11. Copy errors/warnings to parent service (if in context)   │
+│ 12. Run after_service_run callback                           │
+│ 13. Run on_service_success or on_service_failure callback    │
+├─────────────────────────────────────────────────────────────┤
+│ 14. Return service instance                                  │
+│     - service.success? / service.failed?                     │
+│     - service.outputs / service.errors                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Arguments
+
+Arguments are the inputs provided to a service when it is invoked. They can be validated by type, assigned default values, and be designated as optional or required.
+
+[Read more about arguments](arguments.md)
+
+## Steps
+
+Steps are the fundamental units of work within a service, representing each individual task a service performs. They can be executed conditionally or skipped.
+
+[Read more about steps](steps.md)
+
+## Outputs
+
+Outputs are the results produced by a service upon its completion. They can have default values and be validated by type.
+
+[Read more about outputs](outputs.md)
+
+## Context
+
+Context refers to the shared state that passes between services in a service chain, enabling the transfer of arguments and error states from one service to another.
+
+[Read more about context](context.md)
+
+## Errors
+
+Errors occur during service execution and cause execution to halt. When an error occurs, all services in the same context chain stop, and database transactions are rolled back (configurable).
+
+[Read more about errors](errors.md)
+
+## Callbacks
+
+Callbacks allow you to run custom code at specific points during service and step execution. They're perfect for logging, benchmarking, auditing, and other cross-cutting concerns.
+
+[Read more about callbacks](callbacks.md)
+

data/docs/configuration.md

@@ -0,0 +1,168 @@
+# Configuration
+
+Light Services provides a flexible configuration system that allows you to customize behavior at three levels: global, per-service, and per-call.
+
+## Global Configuration
+
+Configure Light Services globally using an initializer. For Rails applications, create `config/initializers/light_services.rb`:
+
+```ruby
+Light::Services.configure do |config|
+  # Transaction settings
+  config.use_transactions = true        # Wrap each service in a database transaction
+
+  # Error behavior
+  config.load_errors = true             # Copy errors to parent service in context chain
+  config.break_on_error = true          # Stop step execution when an error is added
+  config.raise_on_error = false         # Raise an exception when an error is added
+  config.rollback_on_error = true       # Rollback transaction when an error is added
+
+  # Warning behavior
+  config.load_warnings = true           # Copy warnings to parent service in context chain
+  config.break_on_warning = false       # Stop step execution when a warning is added
+  config.raise_on_warning = false       # Raise an exception when a warning is added
+  config.rollback_on_warning = false    # Rollback transaction when a warning is added
+end
+```
+
+## Default Values
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `use_transactions` | `true` | Wraps service execution in `ActiveRecord::Base.transaction` |
+| `load_errors` | `true` | Propagates errors to parent service when using `.with(self)` |
+| `break_on_error` | `true` | Stops executing remaining steps when an error is added |
+| `raise_on_error` | `false` | Raises `Light::Services::Error` when an error is added |
+| `rollback_on_error` | `true` | Rolls back the transaction when an error is added |
+| `load_warnings` | `true` | Propagates warnings to parent service when using `.with(self)` |
+| `break_on_warning` | `false` | Stops executing remaining steps when a warning is added |
+| `raise_on_warning` | `false` | Raises `Light::Services::Error` when a warning is added |
+| `rollback_on_warning` | `false` | Rolls back the transaction when a warning is added |
+
+## Per-Service Configuration
+
+Override global configuration for a specific service class using the `config` class method:
+
+```ruby
+class CriticalPaymentService < ApplicationService
+  # This service will raise exceptions instead of collecting errors
+  config raise_on_error: true
+
+  step :process_payment
+  step :send_receipt
+
+  # ...
+end
+```
+
+```ruby
+class NonCriticalNotificationService < ApplicationService
+  # This service doesn't need transactions and shouldn't stop on errors
+  config use_transactions: false, break_on_error: false
+
+  step :send_push_notification
+  step :send_email_notification
+
+  # ...
+end
+```
+
+## Per-Call Configuration
+
+Override configuration for a single service call:
+
+```ruby
+# Pass config as second argument to run
+MyService.run({ name: "John" }, { raise_on_error: true })
+
+# Or use with() for context-based calls
+MyService.with({ raise_on_error: true }).run(name: "John")
+
+# Combine with parent service context
+ChildService
+  .with(self, { use_transactions: false })
+  .run(data: some_data)
+```
+
+## Configuration Precedence
+
+Configuration is merged in this order (later overrides earlier):
+
+1. Global configuration (from initializer)
+2. Per-service configuration (from `config` class method)
+3. Per-call configuration (from `run` or `with` arguments)
+
+```ruby
+# Global: raise_on_error = false
+Light::Services.configure do |config|
+  config.raise_on_error = false
+end
+
+# Per-service: raise_on_error = true (overrides global)
+class MyService < ApplicationService
+  config raise_on_error: true
+end
+
+# Per-call: raise_on_error = false (overrides per-service)
+MyService.run(args, { raise_on_error: false })
+```
+
+## Common Configuration Patterns
+
+### Strict Mode for Critical Services
+
+```ruby
+class Payment::Process < ApplicationService
+  config raise_on_error: true, rollback_on_error: true
+  
+  # Any error will raise an exception and rollback the transaction
+end
+```
+
+### Fire-and-Forget Services
+
+```ruby
+class Analytics::Track < ApplicationService
+  config use_transactions: false, break_on_error: false, load_errors: false
+  
+  # Errors won't stop execution or propagate to parent services
+end
+```
+
+### Background Job Services
+
+```ruby
+class BackgroundTaskService < ApplicationService
+  # Background jobs typically handle their own transactions
+  config use_transactions: false
+end
+```
+
+## Disabling Transactions
+
+If you're not using ActiveRecord or want to manage transactions yourself:
+
+```ruby
+Light::Services.configure do |config|
+  config.use_transactions = false
+end
+```
+
+Or disable for specific services:
+
+```ruby
+class MyService < ApplicationService
+  config use_transactions: false
+end
+```
+
+{% hint style="info" %}
+When `use_transactions` is `true`, Light Services uses `ActiveRecord::Base.transaction(requires_new: true)` to create savepoints, allowing nested services to rollback independently.
+{% endhint %}
+
+## What's Next?
+
+Now that you understand configuration, learn about the core concepts:
+
+[Next: Concepts](concepts.md)
+