servus 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d4674f76ed62ceba7d4bc333e075142debb42060e2e42dbb8e4fdbf807fce9b
-  data.tar.gz: 2bf1707e65e97a088d8a891e1a846ceee50897b50ffbe550cbe81e747a308664
+  metadata.gz: f1094a06fd6195a99ef33f849a6ea30e6ec1a539eeb7ef73e7c27d1d4ac411bf
+  data.tar.gz: f6891749189216f6391396d79a29fd695fc3da5ff7647691318a90929781a90a
 SHA512:
-  metadata.gz: dfd0f3bf8f32a44b394179ff5c5bfa52b6891aaab54388563ea521c1523cc5b9ea60258525e894f984e1997713832d234abb06785c84c0dbfd86544f866fb587
-  data.tar.gz: abb0f1a3b4291d76157e4ac6d1858616f9f4bf569cde3da4c4874bfd2f5d66bc9ac77617ef96cbc2a7eb26aa79349e8eb8bdf8723771e42e49fb9981c142332a
+  metadata.gz: 02e57566af4b419281991b2b0a361010dd7eff9f7d061c226e32153292d60c060e58781099eee1113d8eab678859164a09be26b1ad790dea47ba0e7f2bfe4275
+  data.tar.gz: 2cfd4e9ae6f71bb051b61f2ea7b4315fef58289ffaf610f21669d6f6c98cd635479502a22af3819aa0a41eb3aed6b8de9972e74e8311a7e619fa09cf82c66ff9

data/.claude/commands/check-docs.md

@@ -0,0 +1 @@
+Scan the documentation in docs/ then check the current git changeset. If the changeset has modifications that might affect the documentation, then review the related documentation and make any necessary updates.

data/.claude/commands/consistency-check.md

@@ -0,0 +1 @@
+Are the latest changes consistent with the way that similar functionality has been implemented in the rest of the codebase? #$ARGUMENTS

data/.claude/commands/fine-tooth-comb.md

@@ -0,0 +1 @@
+We're going to go over #$ARGUMENTS with a fine-tooth comb. I want detailed explanations and no edits unless I ask for them. Start by identifying the first thing that looks wrong and explain why.

data/.claude/commands/red-green-refactor.md

@@ -0,0 +1,5 @@
+During this session we will be practicing TDD in the red-green-refactor cycle. The first step in the cycle is to write a test for the smallest possible unit of functionality. Once the test is written, run the test and it should fail. This is the red phase. The next step is to write the code to make the test pass. This is the green phase. Once the test passes, the code is refactored to be more readable and maintainable. This is the refactor phase.
+
+If we get into a situation where more than one test fails, we will focus on the test that is most important to fix first. During that fix phase, we will only run the test that is failing until it passes.
+
+While we're in this mode, you will not use your TODO tool to track tasks. You will rely on me (the human user) to tell you what the next step is.

data/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bundle exec rubocop -A"
+          }
+        ]
+      }
+    ]
+  }
+}

data/.rubocop.yml

@@ -1,11 +1,27 @@
 AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
   Include:
     - 'lib/**/*.rb'
     - 'spec/**/*.rb'
+  Exclude:
+    - 'spec/dummy/**/*'
+    - 'vendor/bundle/**/*'
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+Lint/ConstantReassignment:
+  Exclude:
+    - 'spec/**/*'
+
+Lint/MissingSuper:
+  Exclude:
+    - 'spec/**/*'
 
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
 
-Lint/ConstantDefinitionInBlock:
-  Enabled: false
+Naming/PredicateMethod:
+  Enabled: false

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,5 +1,52 @@
 ## [Unreleased]
 
+## [0.1.5] - 2025-12-03
+
+### Added
+
+- **Event Bus Architecture**: Introduced event-driven architecture for decoupling service logic from side effects
+  - `Servus::EventHandler` base class for creating event handlers that subscribe to events and invoke services
+  - `emits` DSL on `Servus::Base` for declaring events that fire on `:success`, `:failure`, or `:error!`
+  - `Servus::Events::Bus` for routing events to handlers via ActiveSupport::Notifications
+  - Rails generator: `rails g servus:event_handler event_name` creates handler and spec files
+  - Event handlers auto-load from `app/events/` directory in Rails applications
+
+- **Event Payload Validation**: JSON Schema validation for event payloads
+  - `schema payload: {...}` DSL on EventHandler for declaring payload schemas
+  - Validation occurs when events are emitted via `EventHandler.emit(payload)`
+
+- **Event Testing Matchers**: RSpec matchers for testing event emission
+  - `emit_event(:event_name)` matcher to assert events are emitted
+  - `emit_event(:event_name).with(payload)` for payload assertions
+  - `call_service(ServiceClass).with(args)` matcher for handler testing
+  - `call_service(ServiceClass).async` for async invocation testing
+
+- **Configuration Options**: New and updated configuration settings
+  - `config.schemas_dir` - Directory for JSON schema files (default: `app/schemas`)
+  - `config.services_dir` - Directory for service files (default: `app/services`)
+  - `config.events_dir` - Directory for event handlers (default: `app/events`)
+  - `config.strict_event_validation` - Validate handlers subscribe to emitted events (default: `true`)
+  - `Servus::EventHandler.validate_all_handlers!` for CI validation of handler-event mappings
+
+- **Generator Improvements**: Enhanced service and event handler generators
+  - Service templates now include comprehensive YARD documentation
+  - Service spec templates include example test patterns
+  - JSON schema templates include proper structure with `$schema` reference
+  - Event handler templates include full documentation and examples
+  - `--no-docs` flag to skip documentation comments in generated files
+
+### Changed
+
+- Updated execution flow to include event emission after result validation
+- Enhanced Railtie to auto-load event handlers and clear the event bus on reload in development
+
+## [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/CLAUDE.md

@@ -0,0 +1,10 @@
+Before starting a session, always review the latest docs in the following order:
+
+1. `/docs/core/**/*.md`
+2. `/docs/features/**/*.md`
+3. `/docs/guides/**/*.md`
+4. `/docs/integration/**/*.md`
+
+Focus on writing code consistent with the rest of the project. Use existing files as references for conventions and style.
+
+Ensure new code always encludes world class YARD documentation. If documentation looks out of date or incomplete, suggest a relevant edit.

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. Update generators to not make schema files and instead add schemas to schema: method in generators.

data/READme.md

@@ -1,5 +1,6 @@
 ## Servus Gem
 
+
 Servus is a gem for creating and managing service objects. It includes:
 
 - A base class for service objects
@@ -7,8 +8,9 @@ Servus is a gem for creating and managing service objects. It includes:
 - Support for schema validation
 - Support for error handling
 - Support for logging
+- Event-driven architecture with EventHandlers
 
-
+👉🏽 [View the docs](https://zarpay.github.io/servus/)
 
 ## Generators
 
@@ -119,10 +121,6 @@ end
 
 ```
 
-Here’s a section you can add to your README for the new `.call_async` feature, matching the style of your existing `## Inheritance` section:
-
----
-
 ## **Asynchronous Execution**
 
 You can asynchronously execute any service class that inherits from `Servus::Base` using `.call_async`. This uses `ActiveJob` under the hood and supports standard job options (`wait`, `queue`, `priority`, etc.). Only available in environments where `ActiveJob` is loaded (e.g., Rails apps)
@@ -171,6 +169,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 +245,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 +328,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 +458,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 +522,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 +533,219 @@ 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`.
+
+## **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.
+
+### Emitting Events from Services
+
+Services can declare events that are emitted on success or failure:
+
+```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 can be provided via blocks or method references:
+
+```ruby
+emits :user_created, on: :success do |result|
+  { user_id: result.data[:user].id, email: result.data[:user].email }
+end
+```
+
+### Event Handlers
+
+EventHandlers subscribe to events and invoke services in response. They live in `app/events/`:
+
+```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
+```
+
+### Generate Event Handler
+
+```bash
+$ rails g servus:event_handler user_created
+=>    create  app/events/user_created_handler.rb
+      create  spec/events/user_created_handler_spec.rb
+```
+
+### Invocation Options
+
+```ruby
+# Synchronous (default)
+invoke NotifyAdmin::Service do |payload|
+  { message: "New user: #{payload[:email]}" }
+end
+
+# Async via ActiveJob
+invoke SendEmail::Service, async: true do |payload|
+  { user_id: payload[:user_id] }
+end
+
+# Async with specific queue
+invoke SendEmail::Service, async: true, queue: :mailers do |payload|
+  { user_id: payload[:user_id] }
+end
+
+# Conditional invocation
+invoke GrantRewards::Service, if: ->(p) { p[:premium] } do |payload|
+  { user_id: payload[:user_id] }
+end
+```
+
+### Emitting Events Directly
+
+EventHandlers provide an `emit` class method for emitting events from controllers, jobs, or other code:
+
+```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
+```
+
+### 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
+```
+
+### Testing Events
+
+Servus provides RSpec matchers for testing events:
+
+```ruby
+# Test that a service emits an event
+it 'emits user_created event' do
+  expect {
+    CreateUser::Service.call(email: 'test@example.com', name: 'Test')
+  }.to emit_event(:user_created)
+end
+
+# Test payload content
+it 'emits event with expected payload' do
+  expect {
+    CreateUser::Service.call(email: 'test@example.com', name: 'Test')
+  }.to emit_event(:user_created).with(hash_including(email: 'test@example.com'))
+end
+
+# Test handler invokes service
+it 'invokes SendWelcomeEmail' do
+  expect {
+    UserCreatedHandler.handle(payload)
+  }.to call_service(SendWelcomeEmail::Service).with(user_id: 123)
+end
+```

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]