servus 0.1.4 → 0.1.6

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

@@ -1,4 +1,10 @@
 {
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "<%= service_class_name %> Result",
+  "description": "JSON Schema for validating <%= service_class_name %> result data",
   "type": "object",
-  "properties": {}
-}
+  "properties": {
+  },
+  "required": [],
+  "additionalProperties": true
+}

data/lib/generators/servus/service/templates/service.rb.erb

@@ -1,12 +1,109 @@
+# frozen_string_literal: true
+
+<%- unless options[:no_docs] -%>
+# Performs <%= file_name.humanize.downcase %> operations.
+#
+# Services encapsulate business logic with automatic validation, logging,
+# benchmarking, and error handling. They return Response objects indicating
+# success or failure.
+#
+# @example Basic usage
+#   result = <%= service_full_class_name %>.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: value" }.join(', ') %>)
+#
+#   if result.success?
+#     result.data # => { ... }
+#   else
+#     result.error.message # => "Error description"
+#   end
+#
+<%- unless parameters.empty? -%>
+# @example With all parameters
+#   result = <%= service_full_class_name %>.call(
+<%- parameters.each do |param| -%>
+#     <%= param %>: <%= param %>_value<%= param == parameters.last ? '' : ',' %>
+<%- end -%>
+#   )
+#
+<%- end -%>
+# @example Async execution (via ActiveJob)
+#   <%= service_full_class_name %>.call_async(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: value" }.join(', ') %>)
+#
+# @example With event emission
+#   class <%= service_class_name %> < Servus::Base
+#     emits :completed, on: :success
+#     emits :failed, on: :failure
+#     # ...
+#   end
+#
+# @see Servus::Base
+# @see Servus::Support::Response
+<%- end -%>
 module <%= class_name %>
   class Service < Servus::Base
+<%- unless options[:no_docs] -%>
+    # TODO: Define argument validation schema (optional but recommended)
+    # schema arguments: {
+    #   type: 'object',
+<%- if parameters.any? -%>
+    #   required: [<%= parameters.map { |p| "'#{p}'" }.join(', ') %>],
+<%- else -%>
+    #   required: [],
+<%- end -%>
+    #   properties: {
+<%- parameters.each do |param| -%>
+    #     <%= param %>: { type: 'string' }<%= param == parameters.last ? '' : ',' %>
+<%- end -%>
+<%- if parameters.empty? -%>
+    #     # property_name: { type: 'string' }
+<%- end -%>
+    #   }
+    # }
+
+    # TODO: Define result validation schema (optional)
+    # schema result: {
+    #   type: 'object',
+    #   required: [],
+    #   properties: {
+    #     # result_field: { type: 'string' }
+    #   }
+    # }
+
+<%- end -%>
+<%- unless options[:no_docs] -%>
+    # Initializes the service with required parameters.
+    #
+<%- parameters.each do |param| -%>
+    # @param <%= param %> [Object] TODO: document this parameter
+<%- end -%>
+<%- if parameters.empty? -%>
+    # @param args [Hash] service arguments
+<%- end -%>
+<%- end -%>
     def initialize<%= parameter_list %>
-      <%= initialize_params %>
+      <%= initialize_params.empty? ? '# TODO: Initialize instance variables' : initialize_params %>
     end
+
+<%- unless options[:no_docs] -%>
+    # Executes the service logic.
+    #
+    # @return [Servus::Support::Response] success or failure response
+    #
+    # @example Returning success
+    #   success({ user_id: 123, status: 'active' })
+    #
+    # @example Returning failure
+    #   failure('Something went wrong')
+    #
+    # @example Returning typed failure
+    #   failure('Not found', type: Servus::Support::Errors::NotFoundError)
+<%- end -%>
     def call
-      # Implement service logic here
+      # TODO: Implement service logic here
       success({})
     end
-    <%= attr_readers %>
+
+    private
+
+    <%= attr_readers.empty? ? '# TODO: Add attr_readers for instance variables' : attr_readers %>
   end
-end
+end

data/lib/generators/servus/service/templates/service_spec.rb.erb

@@ -1,9 +1,70 @@
-require "rails_helper"
+# frozen_string_literal: true
+
+require 'rails_helper'
 
 RSpec.describe <%= service_full_class_name %> do
-  describe "#call" do
-    it "does something" do
-      # Add expectations here
-    end
+<%- unless options[:no_docs] -%>
+  # Test the service by calling it with valid arguments and asserting on the result.
+  #
+  # Example test patterns:
+  #
+  #   it 'returns success with expected data' do
+  #     result = described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: #{p}_value" }.join(', ') %>)
+  #
+  #     expect(result).to be_success
+  #     expect(result.data).to include(expected_key: expected_value)
+  #   end
+  #
+  #   it 'returns failure when validation fails' do
+  #     result = described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: invalid_value" }.join(', ') %>)
+  #
+  #     expect(result).to be_failure
+  #     expect(result.error.message).to eq('Expected error message')
+  #   end
+  #
+  # For testing async execution:
+  #   it 'enqueues the service job' do
+  #     expect {
+  #       described_class.call_async(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: #{p}_value" }.join(', ') %>)
+  #     }.to have_enqueued_job(Servus::ServiceJob)
+  #   end
+  #
+  # For testing event emissions:
+  #   include Servus::Testing::EventHelpers
+  #
+  #   it 'emits expected event on success' do
+  #     servus_expect_event(:event_name)
+  #       .with_payload(hash_including(key: value))
+  #       .when { described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: value" }.join(', ') %>) }
+  #   end
+
+<%- end -%>
+<%- if parameters.any? -%>
+  let(:<%= parameters.first %>) { nil } # TODO: Set valid test value
+<%- parameters[1..-1]&.each do |param| -%>
+  let(:<%= param %>) { nil } # TODO: Set valid test value
+<%- end -%>
+
+<%- end -%>
+  describe '#call' do
+<%- unless options[:no_docs] -%>
+    # TODO: Add success case test
+    # it 'returns success with expected data' do
+    #   result = described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: #{p}" }.join(', ') %>)
+    #
+    #   expect(result).to be_success
+    #   expect(result.data).to include(key: value)
+    # end
+
+    # TODO: Add failure case test
+    # it 'returns failure when conditions are not met' do
+    #   result = described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: invalid_#{p}" }.join(', ') %>)
+    #
+    #   expect(result).to be_failure
+    #   expect(result.error.message).to eq('Expected error')
+    # end
+<%- else -%>
+    # Add your tests here
+<%- end -%>
   end
-end
+end

data/lib/servus/base.rb

@@ -48,9 +48,11 @@ module Servus
   class Base
     include Servus::Support::Errors
     include Servus::Support::Rescuer
+    include Servus::Events::Emitter
 
     # Support class aliases
     Logger = Servus::Support::Logger
+    Emitter = Servus::Events::Emitter
     Response = Servus::Support::Response
     Validator = Servus::Support::Validator
 
@@ -138,7 +140,12 @@ module Servus
     # @note Prefer {#failure} for expected error conditions. Use this for exceptional cases.
     # @see #failure
     def error!(message = nil, type: Servus::Support::Errors::ServiceError)
-      Logger.log_exception(self.class, type.new(message))
+      error = type.new(message)
+      Logger.log_exception(self.class, error)
+
+      # Emit error! events before raising
+      emit_events_for(:error!, Response.new(false, nil, error))
+
       raise type, message
     end
 
@@ -172,10 +179,15 @@ module Servus
       #
       # @see #initialize
       # @see #call
+      #
+      # rubocop:disable Metrics/MethodLength
       def call(**args)
         before_call(args)
-        result = benchmark(**args) { new(**args).call }
-        after_call(result)
+
+        instance = new(**args)
+        result = benchmark(**args) { instance.call }
+
+        after_call(result, instance)
 
         result
       rescue Servus::Support::Errors::ValidationError => e
@@ -185,6 +197,7 @@ module Servus
         Logger.log_exception(self, e)
         raise e
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Defines schema validation rules for the service's arguments and/or result.
       #
@@ -257,18 +270,21 @@ module Servus
         Validator.validate_arguments!(self, args)
       end
 
-      # Executes post-call hooks including result validation.
+      # Executes post-call hooks including result validation and event emission.
       #
       # This method is automatically called after service execution completes and handles:
       # - Validating the result data against RESULT_SCHEMA (if defined)
+      # - Emitting events declared with the emits DSL
       #
       # @param result [Servus::Support::Response] the response returned from the service
+      # @param instance [Servus::Base] the service instance
       # @return [void]
       # @raise [Servus::Support::Errors::ValidationError] if result data fails validation
       #
       # @api private
-      def after_call(result)
+      def after_call(result, instance)
         Validator.validate_result!(self, result)
+        Emitter.emit_result_events!(instance, result)
       end
 
       # Measures service execution time and logs the result.

data/lib/servus/config.rb

@@ -15,36 +15,56 @@ module Servus
   # @see Servus.config
   # @see Servus.configure
   class Config
-    # The root directory where schema files are located.
+    # The directory where JSON schema files are located.
     #
-    # Defaults to `Rails.root/app/schemas/services` in Rails applications,
-    # or a relative path from the gem installation otherwise.
+    # Defaults to `Rails.root/app/schemas/services` in Rails applications.
     #
-    # @return [String] the schema root directory path
-    attr_reader :schema_root
+    # @return [String] the schemas directory path
+    attr_accessor :schemas_dir
+
+    # The directory where event handlers are located.
+    #
+    # Defaults to `Rails.root/app/events` in Rails applications.
+    #
+    # @return [String] the events directory path
+    attr_accessor :events_dir
+
+    # The directory where services are located.
+    #
+    # Defaults to `Rails.root/app/services` in Rails applications.
+    #
+    # @return [String] the services directory path
+    attr_accessor :services_dir
+
+    # Whether to validate that all event handlers subscribe to events that are actually emitted by services.
+    #
+    # When enabled, raises an error on boot if handlers subscribe to non-existent events.
+    # Helps catch typos and orphaned handlers.
+    #
+    # @return [Boolean] true to validate, false to skip validation
+    attr_accessor :strict_event_validation
 
     # Initializes a new configuration with default values.
     #
     # @api private
     def initialize
-      # Default to Rails.root if available, otherwise use current working directory
-      @schema_root = File.join(root_path, 'app/schemas/services')
+      @events_dir = 'app/events'
+      @schemas_dir = 'app/schemas'
+      @services_dir = 'app/services'
+      @strict_event_validation = true
     end
 
     # Returns the full path to a service's schema file.
     #
-    # Constructs the path by combining {#schema_root} with the service namespace
-    # and schema type.
-    #
     # @param service_namespace [String] underscored service namespace (e.g., "process_payment")
     # @param type [String] schema type ("arguments" or "result")
     # @return [String] full path to the schema JSON file
     #
     # @example
     #   config.schema_path_for("process_payment", "arguments")
-    #   # => "/app/app/schemas/services/process_payment/arguments.json"
+    #   # => "/full/path/app/schemas/process_payment/arguments.json"
     def schema_path_for(service_namespace, type)
-      File.join(schema_root.to_s, service_namespace, "#{type}.json")
+      File.join(root_path, schemas_dir, service_namespace, "#{type}.json")
     end
 
     # Returns the directory containing a service's schema files.
@@ -54,9 +74,9 @@ module Servus
     #
     # @example
     #   config.schema_dir_for("process_payment")
-    #   # => "/app/app/schemas/services/process_payment"
+    #   # => "/full/path/app/schemas/process_payment"
     def schema_dir_for(service_namespace)
-      File.join(schema_root.to_s, service_namespace)
+      File.join(root_path, schemas_dir, service_namespace)
     end
 
     private

data/lib/servus/event_handler.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Servus
+  # Base class for event handlers that map events to service invocations.
+  #
+  # EventHandler classes live in app/events/ and use a declarative DSL to
+  # subscribe to events and invoke services in response. Each handler
+  # subscribes to a single event via the `handles` method.
+  #
+  # @example Basic event handler
+  #   class UserCreatedHandler < Servus::EventHandler
+  #     handles :user_created
+  #
+  #     invoke SendWelcomeEmail::Service, async: true do |payload|
+  #       { user_id: payload[:user_id] }
+  #     end
+  #   end
+  #
+  # @see Servus::Events::Bus
+  # @see Servus::Base
+  class EventHandler
+    class << self
+      # Declares which event this handler subscribes to.
+      #
+      # This method registers the handler with the event bus and stores
+      # the event name for later reference. Each handler can only subscribe
+      # to one event.
+      #
+      # @param event_name [Symbol] the name of the event to handle
+      # @return [void]
+      # @raise [RuntimeError] if handles is called multiple times
+      #
+      # @example
+      #   class UserCreatedHandler < Servus::EventHandler
+      #     handles :user_created
+      #   end
+      def handles(event_name)
+        raise "Handler already subscribed to :#{@event_name}. Cannot subscribe to :#{event_name}" if @event_name
+
+        @event_name = event_name
+        Servus::Events::Bus.register_handler(event_name, self)
+      end
+
+      # Returns the event name this handler is subscribed to.
+      #
+      # @return [Symbol, nil] the event name or nil if not yet configured
+      attr_reader :event_name
+
+      # Declares a service invocation in response to the event.
+      #
+      # Multiple invocations can be declared for a single event. Each invocation
+      # requires a block that maps the event payload to the service's arguments.
+      #
+      # @param service_class [Class] the service class to invoke (must inherit from Servus::Base)
+      # @param options [Hash] invocation options
+      # @option options [Boolean] :async invoke the service asynchronously via call_async
+      # @option options [Symbol] :queue the queue name for async jobs
+      # @option options [Proc] :if condition that must return true for invocation
+      # @option options [Proc] :unless condition that must return false for invocation
+      # @yield [payload] block that maps event payload to service arguments
+      # @yieldparam payload [Hash] the event payload
+      # @yieldreturn [Hash] keyword arguments for the service's initialize method
+      # @return [void]
+      #
+      # @example Basic invocation
+      #   invoke SendEmail::Service do |payload|
+      #     { user_id: payload[:user_id], email: payload[:email] }
+      #   end
+      #
+      # @example Async invocation with queue
+      #   invoke SendEmail::Service, async: true, queue: :mailers do |payload|
+      #     { user_id: payload[:user_id] }
+      #   end
+      #
+      # @example Conditional invocation
+      #   invoke GrantRewards::Service, if: ->(p) { p[:premium] } do |payload|
+      #     { user_id: payload[:user_id] }
+      #   end
+      def invoke(service_class, options = {}, &block)
+        raise ArgumentError, 'Block required for payload mapping' unless block
+
+        @invocations ||= []
+        @invocations << {
+          service_class: service_class,
+          options: options,
+          mapper: block
+        }
+      end
+
+      # Returns all service invocations declared for this handler.
+      #
+      # @return [Array<Hash>] array of invocation configurations
+      def invocations
+        @invocations || []
+      end
+
+      # Defines the JSON schema for validating event payloads.
+      #
+      # @param payload [Hash, nil] JSON schema for validating event payloads
+      # @return [void]
+      #
+      # @example
+      #   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' }
+      #       }
+      #     }
+      #   end
+      def schema(payload: nil)
+        @payload_schema = payload.with_indifferent_access if payload
+      end
+
+      # Returns the payload schema.
+      #
+      # @return [Hash, nil] the payload schema or nil if not defined
+      # @api private
+      attr_reader :payload_schema
+
+      # Emits the event this handler is subscribed to.
+      #
+      # Provides a type-safe, discoverable way to emit events from anywhere in
+      # the application (controllers, jobs, rake tasks) without creating a service.
+      #
+      # @param payload [Hash] the event payload
+      # @return [void]
+      # @raise [RuntimeError] if no event configured via `handles`
+      #
+      # @example Emit from controller
+      #   class UsersController
+      #     def create
+      #       user = User.create!(params)
+      #       UserCreatedHandler.emit({ user_id: user.id, email: user.email })
+      #       redirect_to user
+      #     end
+      #   end
+      #
+      # @example Emit from background job
+      #   class ProcessDataJob
+      #     def perform(data_id)
+      #       result = process_data(data_id)
+      #       DataProcessedHandler.emit({ data_id: data_id, status: result })
+      #     end
+      #   end
+      def emit(payload)
+        raise 'No event configured. Call handles :event_name first.' unless @event_name
+
+        Servus::Support::Validator.validate_event_payload!(self, payload)
+
+        Servus::Events::Bus.emit(@event_name, payload)
+      end
+
+      # Handles an event by invoking all configured services.
+      #
+      # Iterates through all declared invocations, evaluates conditions,
+      # maps the payload to service arguments, and invokes each service.
+      #
+      # @param payload [Hash] the event payload
+      # @return [Array<Servus::Support::Response>] results from all invoked services
+      #
+      # @example
+      #   UserCreatedHandler.handle({ user_id: 123, email: 'user@example.com' })
+      def handle(payload)
+        invocations.map do |invocation|
+          next unless should_invoke?(payload, invocation[:options])
+
+          invoke_service(invocation, payload)
+        end.compact
+      end
+
+      # Validates that all registered handlers subscribe to events that are actually emitted by services.
+      #
+      # Checks all handlers against all service emissions and raises an error if any
+      # handler subscribes to a non-existent event. Helps catch typos and orphaned handlers.
+      #
+      # Respects the `Servus.config.strict_event_validation` setting - skips validation if false.
+      #
+      # @return [void]
+      # @raise [Servus::Events::OrphanedHandlerError] if a handler subscribes to a non-existent event
+      #
+      # @example
+      #   Servus::EventHandler.validate_all_handlers!
+      def validate_all_handlers!
+        return unless Servus.config.strict_event_validation
+
+        emitted_events = collect_emitted_events
+        orphaned       = find_orphaned_handlers(emitted_events)
+
+        return if orphaned.empty?
+
+        raise Servus::Events::OrphanedHandlerError,
+              "Handler(s) subscribe to non-existent events:\n" \
+              "#{orphaned.map { |h| "  - #{h[:handler]} subscribes to :#{h[:event]}" }.join("\n")}"
+      end
+
+      private
+
+      # Collects all event names that are emitted by services.
+      #
+      # @return [Set<Symbol>] set of all emitted event names
+      # @api private
+      def collect_emitted_events
+        events = Set.new
+
+        ObjectSpace.each_object(Class)
+                   .select { |klass| klass < Servus::Base }
+                   .each do |service_class|
+          service_class.event_emissions.each_value do |emissions|
+            emissions.each { |emission| events << emission[:event_name] }
+          end
+        end
+
+        events
+      end
+
+      # Finds handlers that subscribe to events not emitted by any service.
+      #
+      # @param emitted_events [Set<Symbol>] set of all emitted event names
+      # @return [Array<Hash>] array of orphaned handler info
+      # @api private
+      def find_orphaned_handlers(emitted_events)
+        orphaned = []
+
+        ObjectSpace.each_object(Class)
+                   .select { |klass| klass < Servus::EventHandler && klass != Servus::EventHandler }
+                   .each do |handler_class|
+          next unless handler_class.event_name
+          next if emitted_events.include?(handler_class.event_name)
+
+          orphaned << { handler: handler_class.name, event: handler_class.event_name }
+        end
+
+        orphaned
+      end
+
+      # Invokes a single service with the mapped payload.
+      #
+      # @param invocation [Hash] the invocation configuration
+      # @param payload [Hash] the event payload
+      # @return [Servus::Support::Response] the service result
+      # @api private
+      def invoke_service(invocation, payload)
+        service_kwargs = invocation[:mapper].call(payload)
+
+        async = invocation.dig(:options, :async) || false
+        queue = invocation.dig(:options, :queue) || nil
+
+        if async
+          service_kwargs = service_kwargs.merge(queue: queue) if queue
+          invocation[:service_class].call_async(**service_kwargs)
+        else
+          invocation[:service_class].call(**service_kwargs)
+        end
+      end
+
+      # Checks if a service should be invoked based on conditions.
+      #
+      # @param payload [Hash] the event payload
+      # @param options [Hash] the invocation options
+      # @return [Boolean] true if the service should be invoked
+      # @api private
+      def should_invoke?(payload, options)
+        return false if options[:if] && !options[:if].call(payload)
+        return false if options[:unless]&.call(payload)
+
+        true
+      end
+    end
+  end
+end