servus 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bddb5c486e4996dff5183d6a9bd57ef086739d7007a12125479d320464a0018
-  data.tar.gz: 2d948b6202d0888664a75766cf4e9a3c607b4f819e7d9293ac0d0ff8f42c6c32
+  metadata.gz: af1900cb767ad43568bf7e2c8c14a98bebc479a9b3ec0cc5d76d5ed3c13c5289
+  data.tar.gz: d75379a7b744f9ae6d4938c9f21601af02dbedfe7befbd3b748410aff8b6e7d9
 SHA512:
-  metadata.gz: 18a6ffd8d72e5a452bda53b5d91a621d0b963872c08d72b8ee4a533160babfde16ed9690a1f9a0b2c5aa1a4c330f3e6209b9ada2ffdba3635bad9cf0bd351d8e
-  data.tar.gz: 59b87da3ae33ec0a586275892632b6fe84810b44d75759d9c6c2733fdb9224093d1ed9740467438908eb4a5640b41b6468f1c8381c65cc07adf843e23979fb80
+  metadata.gz: 011756b6fc695253bca1cedd31c4f3be14426305ed1d698f1e8963f62734a7ceb19dab0f77c75892b6aef326ce04d2ce6d07b22f97c9622131988ff4c24b9989
+  data.tar.gz: 04d948bd35038d768f0786ec253c771c50abc4e8d95d85b39bb2a573b411ee5e4486daec6b460548562e1a87fc5b7b4b3a47ddf2a27105d3ecb3cedd6f09c779

data/.yardopts

@@ -0,0 +1,6 @@
+--output-dir ./docs/yard
+--readme READme.md
+--files docs/**/*.md
+--markup markdown
+--markup-provider redcarpet
+--title "Servus | Service Object Framework"

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 ## [Unreleased]
 
-## [0.1.2] - 2025-10-10
+## [0.1.4] - 2025-11-21
+- Added: Test helpers (`servus_arguments_example` and `servus_result_example`) to extract example values from schemas for testing
+- Added: YARD documentation configuration with README homepage and markdown file support
+- Added: Added `schema` DSL method for cleaner schema definition. Supports `schema arguments: {...}, result: {...}` syntax. Fully backwards compatible with existing `ARGUMENTS_SCHEMA` and `RESULT_SCHEMA` constants.
+- Added: Added support from blocks on `rescue_from` to override default failure handler.
+- Fixed: YARD link resolution warnings in documentation
+
+## [0.1.3] - 2025-10-10
 - Added: Added `call_async` method to `Servus::Base` to enqueue a job for calling the service asynchronously
 - Added: Added `Async::Job` to handle async enqueing with support for ActiveJob set options
 

data/IDEAS.md

@@ -0,0 +1,5 @@
+1. Make sure Async Jobs don't retry when the job class cant be constantized.
+
+2. Improve error handling with an error registry that can be referenced by codes as opposed to fully qualified class names.
+
+3. Mock result objects from schema defaults

data/READme.md

@@ -171,6 +171,7 @@ Always use the class method `call` instead of manual instantiation. The `call
 2. Calls the instance-level `call` method
 3. Handles schema validation of inputs and outputs
 4. Handles logging of inputs and results
+5. Automatically benchmarks execution time for performance monitoring
 
 ```ruby
 # Good ✅
@@ -246,25 +247,25 @@ class SomeServiceObject::Service < Servus::Base
 	def call
 		# Return default ServiceError with custom message
 		failure("That didn't work for some reason")
-		#=> Response(false, nil, ApplicationService::Support::Errors::ServiceError("That didn't work for some reason"))
+		#=> Response(false, nil, Servus::Support::Errors::ServiceError("That didn't work for some reason"))
 		#
 		# OR
 		#
 		# Specify ServiceError type with custom message
 		failure("Custom message", type: Servus::Support::Errors::NotFoundError)
-		#=> Response(false, nil, ApplicationService::Support::Errors::NotFoundError("Custom message"))
+		#=> Response(false, nil, Servus::Support::Errors::NotFoundError("Custom message"))
 		#
 		# OR
 		#
 		# Specify ServiceError type with default message
 		failure(type: Servus::Support::Errors::NotFoundError)
-		#=> Response(false, nil, ApplicationService::Support::Errors::NotFoundError("Record not found"))
+		#=> Response(false, nil, Servus::Support::Errors::NotFoundError("Not found"))
 		#
 		# OR
 		#
 		# Accept all defaults
 		failure
-		#=> Response(false, nil, ApplicationService::Support::Errors::ServiceError("An error occurred"))
+		#=> Response(false, nil, Servus::Support::Errors::ServiceError("An error occurred"))
 	end
 end
 
@@ -329,6 +330,28 @@ The `rescue_from` method will rescue from the specified errors and use the speci
 the custom error. It helps eliminate the need to manually rescue many errors and create failure responses within the call method of
 a service object.
 
+You can also provide a block for custom error handling:
+
+```ruby
+class SomeServiceObject::Service < Servus::Base
+  # Custom error handling with a block
+  rescue_from ActiveRecord::RecordInvalid do |exception|
+    failure("Validation failed: #{exception.message}", type: ValidationError)
+  end
+
+  rescue_from Net::HTTPError do |exception|
+    # Can even return success to recover from errors
+    success(recovered: true, error_message: exception.message)
+  end
+
+  def call
+    # Service logic
+  end
+end
+```
+
+The block receives the exception and has access to `success` and `failure` methods for creating the response.
+
 ## Controller Helpers
 
 Service objects can be called from controllers using the `run_service` and `render_service_object_error` helpers.
@@ -437,43 +460,59 @@ Example `result.json`:
 
 ### 2. Inline Schema Validation
 
-Alternatively, schemas can be declared directly within the service class using `ARGUMENTS_SCHEMA` and `RESULT_SCHEMA` constants.
+Schemas can be declared directly within the service class using the `schema` DSL method:
 
 ```ruby
 class Services::ProcessPayment::Service < Servus::Base
-  ARGUMENTS_SCHEMA = {
-	  type: "object",
-	  required: ["user_id", "amount", "payment_method"],
-	  properties: {
-	    user_id: { type: "integer" },
-	    amount: {
-	      type: "integer",
-	      minimum: 1
-	    },
-	    payment_method: {
-	      type: "string",
-	      enum: ["credit_card", "paypal", "bank_transfer"]
-	    },
-	    currency: {
-	      type: "string",
-	      default: "USD"
-	    }
-	  },
-	  additionalProperties: false
-	}
-
-  RESULT_SCHEMA = {
-	  type: "object",
-	  required: ["transaction_id", "status"],
-	  properties: {
-	    transaction_id: { type: "string" },
-	    status: {
-	      type: "string",
-	      enum: ["approved", "pending", "declined"]
-	    },
-	    receipt_url: { type: "string" }
-	  }
-	}
+  schema(
+    arguments: {
+      type: "object",
+      required: ["user_id", "amount", "payment_method"],
+      properties: {
+        user_id: { type: "integer" },
+        amount: {
+          type: "integer",
+          minimum: 1
+        },
+        payment_method: {
+          type: "string",
+          enum: ["credit_card", "paypal", "bank_transfer"]
+        },
+        currency: {
+          type: "string",
+          default: "USD"
+        }
+      },
+      additionalProperties: false
+    },
+    result: {
+      type: "object",
+      required: ["transaction_id", "status"],
+      properties: {
+        transaction_id: { type: "string" },
+        status: {
+          type: "string",
+          enum: ["approved", "pending", "declined"]
+        },
+        receipt_url: { type: "string" }
+      }
+    }
+  )
+
+  def initialize(user_id:, amount:, payment_method:, currency: 'USD')
+    @user_id = user_id
+    @amount = amount
+    @payment_method = payment_method
+    @currency = currency
+  end
+
+  def call
+    # Service logic...
+    success({
+      transaction_id: "txn_1",
+      status: "approved"
+    })
+  end
 end
 ```
 
@@ -485,9 +524,10 @@ These schemas use JSON Schema format to enforce type safety and input/output con
 
 The validation system follows this precedence:
 
-1. Checks for inline schema constants (`ARGUMENTS_SCHEMA` or `RESULT_SCHEMA`)
-2. Falls back to JSON files if no inline schema is found
-3. Returns nil if neither exists
+1. Schemas defined via `schema` DSL method (recommended)
+2. Inline schema constants (`ARGUMENTS_SCHEMA` or `RESULT_SCHEMA`) - legacy support
+3. JSON files in schema_root directory - legacy support
+4. Returns nil if no schema is found (validation is opt-in)
 
 ### Schema Caching
 
@@ -495,4 +535,69 @@ Both file-based and inline schemas are automatically cached:
 
 - First validation request loads and caches the schema
 - Subsequent validations use the cached version
-- Cache can be cleared using `SchemaValidation.clear_cache!`
+- Cache can be cleared using `Servus::Support::Validator.clear_cache!`
+
+## **Logging**
+
+Servus automatically logs service execution details, making it easy to track and debug service calls.
+
+### Automatic Logging
+
+Every service call automatically logs:
+
+- **Service invocation** with input arguments
+- **Success results** with execution duration
+- **Failure results** with error details and duration
+- **Validation errors** for schema violations
+- **Uncaught exceptions** with error messages
+
+### Logger Configuration
+
+The logger automatically adapts to your environment:
+
+- **Rails applications**: Uses `Rails.logger`
+- **Non-Rails applications**: Uses stdout logger
+
+### Log Output Examples
+
+```ruby
+# Success
+INFO -- : Calling Services::ProcessPayment::Service with args: {:user_id=>123, :amount=>50}
+INFO -- : Services::ProcessPayment::Service succeeded in 0.245s
+
+# Failure
+INFO -- : Calling Services::ProcessPayment::Service with args: {:user_id=>123, :amount=>50}
+WARN -- : Services::ProcessPayment::Service failed in 0.156s with error: Insufficient funds
+
+# Validation Error
+ERROR -- : Services::ProcessPayment::Service validation error: The property '#/amount' value -10 was less than minimum value 1
+
+# Exception
+ERROR -- : Services::ProcessPayment::Service uncaught exception: NoMethodError - undefined method 'charge' for nil:NilClass
+```
+
+All logging happens transparently when using the class-level `.call` method. This is one of the reasons why direct instantiation (bypassing `.call`) is discouraged.
+
+## **Configuration**
+
+Servus can be configured to customize behavior for your application needs.
+
+### Schema Root Directory
+
+By default, Servus looks for schema files in `app/schemas/services/`. You can customize this location:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  config.schema_root = Rails.root.join('lib/schemas')
+end
+```
+
+### Default Behavior
+
+Without explicit configuration:
+
+- **Rails applications**: Schema root defaults to `Rails.root/app/schemas/services`
+- **Non-Rails applications**: Schema root defaults to `./app/schemas/services` relative to the gem installation
+
+The configuration is accessed through the singleton `Servus.config` instance and can be modified using `Servus.configure`.

data/Rakefile

@@ -1,12 +1,45 @@
 # 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

@@ -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,92 @@
+# @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 → Logging → Response
+                ↓                              ↓                ↓
+          ValidationError                ValidationError     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, 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.)
+
+## 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
+)
+```
+
+## 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
+```