servus 0.1.4 → 0.1.5

data/docs/features/5_event_bus.md

@@ -0,0 +1,244 @@
+# @title Features / 5. Event Bus
+
+# 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.
+
+## Overview
+
+The Event Bus provides:
+- **Emitters**: Services declare events they emit on success/failure
+- **EventHandlers**: Subscribe to events and invoke services in response
+- **Event Bus**: Routes events to registered handlers via ActiveSupport::Notifications
+- **Payload Validation**: Optional JSON Schema validation for event payloads
+
+## Service Event Emission
+
+Services can emit events when they succeed or fail using the `emits` DSL:
+
+```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
+
+By default, success events receive `result.data` and failure events receive `result.error`. Customize with a block or method:
+
+```ruby
+class CreateUser::Service < Servus::Base
+  # Block-based payload
+  emits :user_created, on: :success do |result|
+    { user_id: result.data[:user].id, email: result.data[:user].email }
+  end
+
+  # Method-based payload
+  emits :user_stats_updated, on: :success, with: :stats_payload
+
+  private
+
+  def stats_payload(result)
+    { user_count: User.count, latest_user_id: result.data[:user].id }
+  end
+end
+```
+
+### Trigger Types
+
+- `:success` - Fires when service returns `success(...)`
+- `:failure` - Fires when service returns `failure(...)`
+- `:error!` - Fires when service calls `error!(...)` (before exception is raised)
+
+## Event Handlers
+
+EventHandlers live in `app/events/` and subscribe to events using a declarative DSL:
+
+```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
+```
+
+### Generator
+
+Generate handlers with the Rails generator:
+
+```bash
+rails g servus:event_handler user_created
+# Creates:
+#   app/events/user_created_handler.rb
+#   spec/events/user_created_handler_spec.rb
+```
+
+### Invocation Options
+
+```ruby
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  # Synchronous invocation (default)
+  invoke NotifyAdmin::Service do |payload|
+    { message: "New user: #{payload[:email]}" }
+  end
+
+  # Async via ActiveJob
+  invoke SendWelcomeEmail::Service, async: true do |payload|
+    { user_id: payload[:user_id] }
+  end
+
+  # Async with specific queue
+  invoke SendWelcomeEmail::Service, async: true, queue: :mailers do |payload|
+    { user_id: payload[:user_id] }
+  end
+
+  # Conditional invocation
+  invoke GrantPremiumRewards::Service, if: ->(p) { p[:premium] } do |payload|
+    { user_id: payload[:user_id] }
+  end
+
+  invoke SkipForPremium::Service, unless: ->(p) { p[:premium] } do |payload|
+    { user_id: payload[:user_id] }
+  end
+end
+```
+
+## Emitting Events Directly
+
+EventHandlers provide an `emit` class method for emitting events from controllers, jobs, or other code without a service:
+
+```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
+```
+
+This is useful when the event source isn't a Servus service.
+
+## 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
+```
+
+When `emit` is called, the payload is validated against the schema before the event is dispatched.
+
+## Handler Validation
+
+Enable strict validation to catch handlers subscribing to non-existent events:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  config.strict_event_validation = true  # Default: true
+end
+
+# Then manually validate (typically in a rake task or CI)
+Servus::EventHandler.validate_all_handlers!
+```
+
+This helps catch typos and orphaned handlers during development and CI.
+
+## Best Practices
+
+### Single Event Per Service
+
+Services should emit one event per trigger representing their core concern:
+
+```ruby
+# Good - one event, handler coordinates reactions
+class CreateUser::Service < Servus::Base
+  emits :user_created, on: :success
+end
+
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  invoke SendWelcomeEmail::Service, async: true
+  invoke TrackAnalytics::Service, async: true
+  invoke NotifySlack::Service, async: true
+end
+
+# Avoid - service doing too much coordination
+class CreateUser::Service < Servus::Base
+  emits :send_welcome_email, on: :success
+  emits :track_user_analytics, on: :success
+  emits :notify_slack, on: :success
+end
+```
+
+### Naming Conventions
+
+- Events: Past tense describing what happened (`user_created`, `payment_processed`)
+- Handlers: Event name + "Handler" suffix (`UserCreatedHandler`)
+
+### Handler Location
+
+Handlers live in `app/events/` and are auto-loaded by the Railtie:
+
+```
+app/events/
+├── user_created_handler.rb
+├── payment_processed_handler.rb
+└── order_completed_handler.rb
+```
+
+## Instrumentation
+
+Events are instrumented via ActiveSupport::Notifications and appear in Rails logs:
+
+```
+servus.events.user_created (1.2ms) {:user_id=>123, :email=>"user@example.com"}
+```
+
+Subscribe to events programmatically:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, *args|
+  event_name = name.sub('servus.events.', '')
+  Rails.logger.info "Event emitted: #{event_name}"
+end
+```

data/docs/integration/1_configuration.md

@@ -2,22 +2,27 @@
 
 # Configuration
 
-Servus works without configuration. One optional setting exists for schema file location.
+Servus works without configuration. Optional settings exist for customizing directories and event validation.
 
-## Schema Root
+## Directory Configuration
 
-By default, Servus looks for schema JSON files in `Rails.root/app/schemas/services` (or `./app/schemas/services` in non-Rails apps).
-
-Change the location if needed:
+Configure where Servus looks for schemas, services, and event handlers:
 
 ```ruby
 # config/initializers/servus.rb
 Servus.configure do |config|
-  config.schema_root = Rails.root.join('config/schemas')
+  # Default: 'app/schemas'
+  config.schemas_dir = 'app/schemas'
+
+  # Default: 'app/services'
+  config.services_dir = 'app/services'
+
+  # Default: 'app/events'
+  config.events_dir = 'app/events'
 end
 ```
 
-This affects legacy file-based schemas only - schemas defined via the `schema` DSL method do not use files.
+These affect legacy file-based schemas and handler auto-loading. Schemas defined via the `schema` DSL method do not use files.
 
 ## Schema Cache
 
@@ -49,3 +54,51 @@ config.active_job.default_queue_name = :default
 ```
 
 Servus respects ActiveJob queue configuration - no Servus-specific setup needed.
+
+## Event Bus Configuration
+
+### Strict Event Validation
+
+Enable strict validation to catch handlers subscribing to events that aren't emitted by any service:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  # Default: true
+  config.strict_event_validation = true
+end
+```
+
+When enabled, you can validate handlers at boot or in CI:
+
+```ruby
+# In a rake task or initializer
+Servus::EventHandler.validate_all_handlers!
+```
+
+This raises `Servus::Events::OrphanedHandlerError` if any handler subscribes to a non-existent event.
+
+### Handler Auto-Loading
+
+In Rails, handlers in `app/events/` are automatically loaded. The Railtie:
+- Clears the event bus on reload in development
+- Eager-loads all `*_handler.rb` files from `config.events_dir`
+
+```
+app/events/
+├── user_created_handler.rb
+├── payment_processed_handler.rb
+└── order_completed_handler.rb
+```
+
+### Event Instrumentation
+
+Events are instrumented via ActiveSupport::Notifications with the prefix `servus.events.`:
+
+```ruby
+# Subscribe to all Servus events
+ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, *args|
+  event_name = name.sub('servus.events.', '')
+  Rails.logger.info "Event: #{event_name}"
+end
+```

data/docs/integration/2_testing.md

@@ -162,3 +162,126 @@ it "validates required fields" do
   }.to raise_error(Servus::Support::Errors::ValidationError, /required/)
 end
 ```
+
+## Testing Event Emission
+
+Servus provides RSpec matchers for testing that services emit events.
+
+### Setup
+
+Include the matchers in your test suite:
+
+```ruby
+# spec/spec_helper.rb
+require 'servus/testing'
+```
+
+### emit_event Matcher
+
+Assert that a block emits an event:
+
+```ruby
+RSpec.describe CreateUser::Service do
+  it 'emits user_created event on success' do
+    expect {
+      described_class.call(email: 'test@example.com', name: 'Test')
+    }.to emit_event(:user_created)
+  end
+
+  it 'emits event with expected payload' do
+    expect {
+      described_class.call(email: 'test@example.com', name: 'Test')
+    }.to emit_event(:user_created).with(hash_including(email: 'test@example.com'))
+  end
+
+  # Using handler class instead of symbol
+  it 'emits to UserCreatedHandler' do
+    expect {
+      described_class.call(email: 'test@example.com', name: 'Test')
+    }.to emit_event(UserCreatedHandler)
+  end
+end
+```
+
+### call_service Matcher
+
+Assert that a handler invokes a service:
+
+```ruby
+RSpec.describe UserCreatedHandler do
+  let(:payload) { { user_id: 123, email: 'test@example.com' } }
+
+  it 'invokes SendWelcomeEmail::Service' do
+    expect {
+      described_class.handle(payload)
+    }.to call_service(SendWelcomeEmail::Service).with(user_id: 123)
+  end
+
+  it 'invokes service asynchronously' do
+    expect {
+      described_class.handle(payload)
+    }.to call_service(SendWelcomeEmail::Service).async
+  end
+end
+```
+
+### Testing EventHandler Directly
+
+Test handlers by calling their `handle` class method:
+
+```ruby
+RSpec.describe UserCreatedHandler do
+  let(:payload) { { user_id: 123, email: 'test@example.com' } }
+
+  before do
+    allow(SendWelcomeEmail::Service).to receive(:call_async)
+    allow(TrackAnalytics::Service).to receive(:call_async)
+  end
+
+  it 'invokes SendWelcomeEmail with mapped arguments' do
+    described_class.handle(payload)
+
+    expect(SendWelcomeEmail::Service)
+      .to have_received(:call_async)
+      .with(user_id: 123, email: 'test@example.com')
+  end
+
+  it 'invokes TrackAnalytics with event data' do
+    described_class.handle(payload)
+
+    expect(TrackAnalytics::Service)
+      .to have_received(:call_async)
+      .with(event: 'user_created', user_id: 123)
+  end
+
+  context 'with conditional invocation' do
+    it 'skips premium rewards for non-premium users' do
+      allow(GrantPremiumRewards::Service).to receive(:call)
+
+      described_class.handle(payload.merge(premium: false))
+
+      expect(GrantPremiumRewards::Service).not_to have_received(:call)
+    end
+  end
+end
+```
+
+### Testing Event Emission from Handler
+
+Test the `emit` class method:
+
+```ruby
+RSpec.describe UserCreatedHandler do
+  it 'emits the user_created event' do
+    expect {
+      described_class.emit({ user_id: 123, email: 'test@example.com' })
+    }.to emit_event(:user_created)
+  end
+
+  it 'validates payload against schema' do
+    expect {
+      described_class.emit({ invalid: 'payload' })
+    }.to raise_error(Servus::Support::Errors::ValidationError)
+  end
+end
+```

data/lib/generators/servus/event_handler/event_handler_generator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Servus
+  module Generators
+    # Rails generator for creating Servus event handlers.
+    #
+    # Generates an event handler class and spec file.
+    #
+    # @example Generate an event handler
+    #   rails g servus:event_handler user_created
+    #
+    # @example Generated files
+    #   app/events/user_created_handler.rb
+    #   spec/app/events/user_created_handler_spec.rb
+    #
+    # @see https://guides.rubyonrails.org/generators.html
+    class EventHandlerGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :no_docs, type: :boolean,
+                             default: false,
+                             desc: 'Skip documentation comments in generated files'
+
+      # Creates the event handler and spec files.
+      #
+      # @return [void]
+      def create_handler_file
+        template 'handler.rb.erb', handler_path
+        template 'handler_spec.rb.erb', handler_spec_path
+      end
+
+      private
+
+      # Returns the path for the handler file.
+      #
+      # @return [String] handler file path
+      # @api private
+      def handler_path
+        File.join(Servus.config.events_dir, "#{file_name}_handler.rb")
+      end
+
+      # Returns the path for the handler spec file.
+      #
+      # @return [String] spec file path
+      # @api private
+      def handler_spec_path
+        File.join('spec', Servus.config.events_dir, "#{file_name}_handler_spec.rb")
+      end
+
+      # Returns the handler class name.
+      #
+      # @return [String] handler class name
+      # @api private
+      def handler_class_name
+        "#{class_name}Handler"
+      end
+    end
+  end
+end

data/lib/generators/servus/event_handler/templates/handler.rb.erb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+<%- unless options[:no_docs] -%>
+# Handles the :<%= file_name %> event by invoking configured services.
+#
+# EventHandlers subscribe to a single event and declaratively map it to one or
+# more service invocations. This provides clean separation between event emission
+# (what happened) and event handling (what to do about it).
+#
+# @example Basic usage
+#   class <%= handler_class_name %> < Servus::EventHandler
+#     handles :<%= file_name %>
+#
+#     # Invoke a service when this event fires
+#     invoke SendEmail::Service, async: true do |payload|
+#       { user_id: payload[:user_id], email: payload[:email] }
+#     end
+#   end
+#
+# @example Multiple service invocations
+#   invoke SendWelcomeEmail::Service, async: true, queue: :mailers do |payload|
+#     { user_id: payload[:user_id] }
+#   end
+#
+#   invoke TrackAnalytics::Service, async: true do |payload|
+#     { event: '<%= file_name %>', user_id: payload[:user_id] }
+#   end
+#
+# @example Conditional invocation
+#   invoke GrantRewards::Service, if: ->(payload) { payload[:premium] } do |payload|
+#     { user_id: payload[:user_id] }
+#   end
+#
+# @example With payload schema validation
+#   schema payload: {
+#     type: 'object',
+#     required: ['user_id'],
+#     properties: {
+#       user_id: { type: 'integer' },
+#       email: { type: 'string', format: 'email' }
+#     }
+#   }
+#
+# @example Emit this event from anywhere
+#   # From controllers, jobs, rake tasks, etc.
+#   <%= handler_class_name %>.emit({ user_id: 123, email: 'user@example.com' })
+#
+# Available options for `invoke`:
+# - async: true          - Invoke service asynchronously via ActiveJob
+# - queue: :queue_name   - Specify ActiveJob queue (requires async: true)
+# - if: ->(payload) {}   - Condition that must be true to invoke
+# - unless: ->(payload) {} - Condition that must be false to invoke
+#
+# @see Servus::EventHandler
+# @see Servus::Events::Bus
+<%- end -%>
+class <%= handler_class_name %> < Servus::EventHandler
+  handles :<%= file_name %>
+
+<%- unless options[:no_docs] -%>
+  # TODO: Define payload schema (optional but recommended)
+  # schema payload: {
+  #   type: 'object',
+  #   required: ['required_field'],
+  #   properties: {
+  #     required_field: { type: 'string' }
+  #   }
+  # }
+
+  # TODO: Add service invocations
+  # invoke YourService, async: true do |payload|
+  #   {
+  #     # Map event payload to service arguments
+  #     argument_name: payload[:field_name]
+  #   }
+  # end
+<%- end -%>
+  schema payload: {
+    type: 'object',
+    description: 'JSON schema for the <%= handler_class_name %> event payload',
+  }
+
+  # invoke ExampleService, async: true do |payload|
+  #   { example_arg: payload[:example_field] }
+  # end
+end

data/lib/generators/servus/event_handler/templates/handler_spec.rb.erb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= handler_class_name %> do
+<%- unless options[:no_docs] -%>
+  # Test that the handler invokes the correct services with properly mapped arguments.
+  #
+  # Example test pattern:
+  #   it 'invokes YourService with correct arguments' do
+  #     expect(YourService).to receive(:call_async).with(user_id: 123)
+  #     described_class.handle({ user_id: 123, email: 'test@example.com' })
+  #   end
+  #
+  # For testing event emission from controllers/jobs:
+  #   include Servus::Testing::EventHelpers
+  #
+  #   it 'emits <%= file_name %> event' do
+  #     servus_expect_event(:<%= file_name %>)
+  #       .with_payload(hash_including(user_id: 123))
+  #       .when { YourController.new.create }
+  #   end
+
+<%- end -%>
+  let(:payload) do
+    {
+      # TODO: Add sample payload fields
+      # user_id: 123,
+      # email: 'test@example.com'
+    }
+  end
+
+<%- unless options[:no_docs] -%>
+  # TODO: Add tests for service invocations
+  # it 'invokes YourService with mapped arguments' do
+  #   expect(YourService).to receive(:call_async).with(user_id: payload[:user_id])
+  #   described_class.handle(payload)
+  # end
+
+  # TODO: Test conditional logic if using :if or :unless
+  # it 'skips invocation when condition is false' do
+  #   expect(YourService).not_to receive(:call_async)
+  #   described_class.handle(payload.merge(premium: false))
+  # end
+<%- else -%>
+  # Add your tests here
+<%- end -%>
+end

data/lib/generators/servus/service/service_generator.rb

@@ -24,6 +24,10 @@ module Servus
 
       argument :parameters, type: :array, default: [], banner: 'parameter'
 
+      class_option :no_docs, type: :boolean,
+                             default: false,
+                             desc: 'Skip documentation comments in generated files'
+
       # Creates all service-related files.
       #
       # Generates the service class, spec file, and schema files from templates.

data/lib/generators/servus/service/templates/arguments.json.erb

@@ -1,15 +1,24 @@
 {
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "<%= service_class_name %> Arguments",
+  "description": "JSON Schema for validating <%= service_class_name %> input arguments",
   "type": "object",
   "properties": {
-    <%- parameters.each do |param| %>
-      "<%= param %>": {
-        "type": "UNDECLARED_TYPE"
-      }
-    <% end %>
+<%- parameters.each_with_index do |param, index| -%>
+    "<%= param %>": {
+      "type": "string",
+      "description": "TODO: Describe the <%= param %> parameter"
+    }<%= index < parameters.length - 1 ? ',' : '' %>
+<%- end -%>
+<%- if parameters.empty? -%>
   },
+<%- else -%>
+  },
+<%- end -%>
   "required": [
-    <%- parameters.each do |param| %>
-      "<%= param %>",
-    <% end %>
-  ]
-}
+<%- parameters.each_with_index do |param, index| -%>
+    "<%= param %>"<%= index < parameters.length - 1 ? ',' : '' %>
+<%- end -%>
+  ],
+  "additionalProperties": false
+}