servus 0.1.3 → 0.1.5

data/lib/servus/extensions/async/errors.rb

@@ -3,14 +3,34 @@
 module Servus
   module Extensions
     module Async
+      # Error classes for asynchronous service execution.
+      #
+      # These errors are raised when async operations fail, such as job enqueueing
+      # failures or missing service classes during job execution.
       module Errors
-        # Base error class for async extensions
+        # Base error class for all async extension errors.
+        #
+        # All async-related errors inherit from this class for easy rescue handling.
         class AsyncError < StandardError; end
 
-        # Error raised when the job fails to enqueue
+        # Raised when enqueueing a background job fails.
+        #
+        # This typically occurs due to connection issues with the job backend
+        # (Redis, database, etc.) or configuration problems.
+        #
+        # @example
+        #   Services::SendEmail::Service.call_async(user_id: 123)
+        #   # => Servus::Extensions::Async::Errors::JobEnqueueError: Failed to enqueue async job
         class JobEnqueueError < AsyncError; end
 
-        # Error raised when the service class cannot be found
+        # Raised when a service class name cannot be found.
+        #
+        # This occurs during job execution when the service class string
+        # cannot be constantized, usually due to typos or deleted classes.
+        #
+        # @example
+        #   Job.perform_later(name: "NonExistent::Service", args: {})
+        #   # => Servus::Extensions::Async::Errors::ServiceNotFoundError: Service class 'NonExistent::Service' not found
         class ServiceNotFoundError < AsyncError; end
       end
     end

data/lib/servus/extensions/async/ext.rb

@@ -2,13 +2,21 @@
 
 module Servus
   module Extensions
-    # Async extensions for Servus
+    # Asynchronous execution extensions for Servus services.
+    #
+    # This module provides the infrastructure for running services in background jobs
+    # via ActiveJob. When loaded, it extends {Servus::Base} with the {Call#call_async} method.
+    #
+    # @see Servus::Extensions::Async::Call
+    # @see Servus::Extensions::Async::Job
     module Async
       require 'servus/extensions/async/errors'
       require 'servus/extensions/async/job'
       require 'servus/extensions/async/call'
 
-      # Module providing async extensions for Servus
+      # Extension module for async functionality.
+      #
+      # @api private
       module Ext; end
     end
   end

data/lib/servus/extensions/async/job.rb

@@ -3,21 +3,32 @@
 module Servus
   module Extensions
     module Async
-      # Job to run a service class with given arguments.
+      # ActiveJob for executing Servus services asynchronously.
       #
-      # This job will be migrated to Servus once it's stable as a .call_async method.
-      # It takes the fully-qualified class name of the service as a string and any keyword arguments
-      # required by the service's .call method.
+      # This job is used by {Call#call_async} to execute services in the background.
+      # It receives the service class name and arguments, instantiates the service,
+      # and executes it via {Servus::Base.call}.
       #
-      # Example usage:
-      #   RunServiceJob.perform_later('SomeModule::SomeService', arg1: value1, arg2: value2)
+      # @example Enqueued by call_async
+      #   Services::SendEmail::Service.call_async(user_id: 123)
+      #   # Internally enqueues:
+      #   #   Job.perform_later(name: "Services::SendEmail::Service", args: { user_id: 123 })
       #
-      # This will invoke SomeModule::SomeService.call(arg1: value1, arg2: value2) in a background job.
-      #
-      # Errors during service execution are logged.
+      # @api private
       class Job < ActiveJob::Base
         queue_as :default
 
+        # Executes the service with the provided arguments.
+        #
+        # Dynamically loads the service class by name and calls it with the
+        # provided keyword arguments.
+        #
+        # @param name [String] fully-qualified service class name
+        # @param args [Hash] keyword arguments to pass to the service
+        # @return [Servus::Support::Response] the service execution result
+        # @raise [Servus::Extensions::Async::Errors::ServiceNotFoundError] if service class doesn't exist
+        #
+        # @api private
         def perform(name:, args:)
           constantize!(name).call(**args)
         end
@@ -26,6 +37,16 @@ module Servus
 
         attr_reader :klass
 
+        # Safely constantizes a class name string.
+        #
+        # Converts a string class name to its corresponding class constant,
+        # raising an error if the class doesn't exist.
+        #
+        # @param class_name [String] the service class name
+        # @return [Class] the service class
+        # @raise [Servus::Extensions::Async::Errors::ServiceNotFoundError] if class not found
+        #
+        # @api private
         def constantize!(class_name)
           "::#{class_name}".safe_constantize ||
             (raise Errors::ServiceNotFoundError, "Service class '#{class_name}' not found.")

data/lib/servus/helpers/controller_helpers.rb

@@ -2,62 +2,98 @@
 
 module Servus
   module Helpers
-    # Controller helpers
+    # Rails controller helper methods for service integration.
+    #
+    # Provides convenient methods for calling services from controllers and
+    # handling their responses. Automatically included in ActionController::Base
+    # when Servus is loaded in a Rails application.
+    #
+    # @example Including in a controller
+    #   class ApplicationController < ActionController::Base
+    #     include Servus::Helpers::ControllerHelpers
+    #   end
+    #
+    # @see #run_service
+    # @see #render_service_object_error
     module ControllerHelpers
-      # Run a service object and return the result
+      # Executes a service and handles success/failure automatically.
       #
-      # This method is a helper method for controllers to run a service object and return the result.
-      # Servus errors (Servus::Support::Errors::*) all impliment an api_error method that returns a hash with
-      # a code and message. The service_object_error method and any custom implimentation, can be used to
-      # automatically format and return an API error response.
+      # This method runs the service with the provided parameters. On success,
+      # it stores the result in @result for use in views. On failure, it
+      # automatically calls {#render_service_object_error} with the error details.
       #
-      # @example:
-      #   class TestController < ApplicationController
-      #     def index
-      #       run_service MyService::Service, params
-      #     end
-      #   end
+      # The result is always stored in the @result instance variable, making it
+      # available in views for rendering successful responses.
       #
-      # The result of the service is stored in the instance variable @result, which can be used
-      # in views to template a response.
+      # @param klass [Class] service class to execute (must inherit from {Servus::Base})
+      # @param params [Hash] keyword arguments to pass to the service
+      # @return [Servus::Support::Response, nil] the service result, or nil if error rendered
       #
-      # @example:
-      #   json.data do
-      #     json.some_key @result.data[:some_key]
+      # @example Basic usage
+      #   class UsersController < ApplicationController
+      #     def create
+      #       run_service Services::CreateUser::Service, user_params
+      #       # If successful, @result is available for rendering
+      #       # If failed, error response is automatically rendered
+      #     end
       #   end
       #
-      # When investigating the servus error classes, you can see the api_error method implimentation
-      # for each error type. Below is an example implementation of the service_object_error method, which
-      # could be overwritten to meet a specific applications needs.
+      # @example Using @result in views
+      #   # In your Jbuilder view (create.json.jbuilder)
+      #   json.user do
+      #     json.id @result.data[:user_id]
+      #     json.email @result.data[:email]
+      #   end
       #
-      # @example:
-      #   # Example implementation of api_error on Servus::Support::Errors::ServiceError
-      #   # def api_error
-      #   #   { code: :bad_request, message: message }
-      #   # end
+      # @example Manual success handling
+      #   class UsersController < ApplicationController
+      #     def create
+      #       run_service Services::CreateUser::Service, user_params
+      #       return unless @result.success?
       #
-      #   Example implementation of service_object_error
-      #   def service_object_error(api_error)
-      #     render json: api_error, status: api_error[:code]
+      #       # Custom success handling
+      #       redirect_to user_path(@result.data[:user_id])
+      #     end
       #   end
       #
-      # @param klass [Class] The service class
-      # @param params [Hash] The parameters to pass to the service
-      # @return [Servus::Support::Response] The result of the service
-      #
-      # @see Servus::Support::Errors::ServiceError
+      # @see #render_service_object_error
+      # @see Servus::Base.call
       def run_service(klass, params)
         @result = klass.call(**params)
         render_service_object_error(@result.error.api_error) unless @result.success?
       end
 
-      # Service object error renderer
+      # Renders a service error as a JSON response.
       #
-      # This method is a helper method for controllers to render service object errors.
+      # This method is called automatically by {#run_service} when a service fails,
+      # but can also be called manually for custom error handling. It renders the
+      # error's api_error hash with the appropriate HTTP status code.
       #
-      # @param api_error [Hash] The API error response
+      # Override this method in your controller to customize error response format.
+      #
+      # @param api_error [Hash] error hash with :code and :message keys from {Servus::Support::Errors::ServiceError#api_error}
+      # @return [void]
+      #
+      # @example Default behavior
+      #   # Renders: { code: :not_found, message: "User not found" }
+      #   # With status: 404
+      #   render_service_object_error(result.error.api_error)
+      #
+      # @example Custom error rendering
+      #   class ApplicationController < ActionController::Base
+      #     def render_service_object_error(api_error)
+      #       render json: {
+      #         error: {
+      #           type: api_error[:code],
+      #           details: api_error[:message],
+      #           timestamp: Time.current
+      #         }
+      #       }, status: api_error[:code]
+      #     end
+      #   end
       #
-      # @see Servus::Support::Errors::ServiceError
+      # @see Servus::Support::Errors::ServiceError#api_error
+      # @see #run_service
       def render_service_object_error(api_error)
         render json: api_error, status: api_error[:code]
       end

data/lib/servus/railtie.rb

@@ -18,5 +18,21 @@ module Servus
         Servus::Base.extend Servus::Extensions::Async::Call
       end
     end
+
+    # Load event handlers and clear on reload
+    config.to_prepare do
+      Servus::Events::Bus.clear if Rails.env.development?
+
+      # Eager load all event handlers
+      events_path = Rails.root.join(Servus.config.events_dir)
+      Dir[File.join(events_path, '**/*_handler.rb')].each do |handler_file|
+        require_dependency handler_file
+      end
+    end
+
+    # NOTE: Event validation is available but not run automatically due to load order issues.
+    # To validate handlers match emitted events, call manually:
+    #   Servus::EventHandler.validate_all_handlers!
+    # Or create a rake task for CI validation.
   end
 end

data/lib/servus/support/errors.rb

@@ -2,34 +2,80 @@
 
 module Servus
   module Support
+    # Contains all error classes used by Servus services.
+    #
+    # All error classes inherit from {ServiceError} and provide both a human-readable
+    # message and an API-friendly error response via {ServiceError#api_error}.
+    #
+    # @see ServiceError
     module Errors
-      # Base error class for application services
+      # Base error class for all Servus service errors.
       #
-      # @param message [String] The error message
-      # @return [ServiceError] The error instance
+      # This class provides the foundation for all service-related errors, including:
+      # - Default error messages via DEFAULT_MESSAGE constant
+      # - API-friendly error responses via {#api_error}
+      # - Automatic message fallback to default if none provided
+      #
+      # @example Creating a custom error type
+      #   class MyCustomError < Servus::Support::Errors::ServiceError
+      #     DEFAULT_MESSAGE = 'Something went wrong'
+      #
+      #     def api_error
+      #       { code: :custom_error, message: message }
+      #     end
+      #   end
+      #
+      # @example Using with failure method
+      #   def call
+      #     return failure("User not found", type: Servus::Support::Errors::NotFoundError)
+      #     # ...
+      #   end
       class ServiceError < StandardError
         attr_reader :message
 
         DEFAULT_MESSAGE = 'An error occurred'
 
-        # Initializes a new error instance
-        # @param message [String] The error message
-        # @return [ServiceError] The error instance
+        # Creates a new service error instance.
+        #
+        # @param message [String, nil] custom error message (uses DEFAULT_MESSAGE if nil)
+        # @return [ServiceError] the error instance
+        #
+        # @example With custom message
+        #   error = ServiceError.new("Something went wrong")
+        #   error.message # => "Something went wrong"
+        #
+        # @example With default message
+        #   error = ServiceError.new
+        #   error.message # => "An error occurred"
         def initialize(message = nil)
           @message = message || self.class::DEFAULT_MESSAGE
           super("#{self.class}: #{message}")
         end
 
-        # 404 error response
-        # @return [Hash] The error response
+        # Returns an API-friendly error response.
+        #
+        # This method formats the error for API responses, providing both a
+        # symbolic code and the error message. Override in subclasses to customize
+        # the error code for specific HTTP status codes.
+        #
+        # @return [Hash] hash with :code and :message keys
+        #
+        # @example
+        #   error = ServiceError.new("Failed to process")
+        #   error.api_error # => { code: :bad_request, message: "Failed to process" }
         def api_error
           { code: :bad_request, message: message }
         end
       end
 
-      # Error class for bad request errors
-      # @param message [String] The error message
-      # @return [BadRequestError] The error instance
+      # Represents a 400 Bad Request error.
+      #
+      # Use this error when the client sends malformed or invalid request data.
+      #
+      # @example
+      #   def call
+      #     return failure("Invalid JSON format", type: BadRequestError)
+      #   end
       class BadRequestError < ServiceError
         DEFAULT_MESSAGE = 'Bad request'
 
@@ -40,29 +86,45 @@ module Servus
         end
       end
 
-      # Error class for authentication errors
-      # @param message [String] The error message
-      # @return [AuthenticationError] The error instance
+      # Represents a 401 Unauthorized error for authentication failures.
+      #
+      # Use this error when authentication credentials are missing, invalid, or expired.
+      #
+      # @example
+      #   def call
+      #     return failure("Invalid API key", type: AuthenticationError) unless valid_api_key?
+      #   end
       class AuthenticationError < ServiceError
         DEFAULT_MESSAGE = 'Authentication failed'
 
-        # 401 error response
-        # @return [Hash] The error response
+        # @return [Hash] API error response with :unauthorized code
         def api_error
           { code: :unauthorized, message: message }
         end
       end
 
-      # Error class for unauthorized errors
-      # @param message [String] The error message
-      # @return [UnauthorizedError] The error instance
+      # Represents a 401 Unauthorized error (alias for AuthenticationError).
+      #
+      # Use this error for authorization failures when credentials are valid but
+      # lack sufficient permissions.
+      #
+      # @example
+      #   def call
+      #     return failure("Access denied", type: UnauthorizedError) unless user.admin?
+      #   end
       class UnauthorizedError < AuthenticationError
         DEFAULT_MESSAGE = 'Unauthorized'
       end
 
-      # Error class for forbidden errors
-      # @param message [String] The error message
-      # @return [ForbiddenError] The error instance
+      # Represents a 403 Forbidden error.
+      #
+      # Use this error when the user is authenticated but not authorized to perform
+      # the requested action.
+      #
+      # @example
+      #   def call
+      #     return failure("Insufficient permissions", type: ForbiddenError) unless can_access?
+      #   end
       class ForbiddenError < ServiceError
         DEFAULT_MESSAGE = 'Forbidden'
 
@@ -73,60 +135,88 @@ module Servus
         end
       end
 
-      # Error class for not found errors
-      # @param message [String] The error message
-      # @return [NotFoundError] The error instance
+      # Represents a 404 Not Found error.
+      #
+      # Use this error when a requested resource cannot be found.
+      #
+      # @example
+      #   def call
+      #     user = User.find_by(id: @user_id)
+      #     return failure("User not found", type: NotFoundError) unless user
+      #   end
       class NotFoundError < ServiceError
         DEFAULT_MESSAGE = 'Not found'
 
-        # 404 error response
-        # @return [Hash] The error response
+        # @return [Hash] API error response with :not_found code
         def api_error
           { code: :not_found, message: message }
         end
       end
 
-      # Error class for unprocessable entity errors
-      # @param message [String] The error message
-      # @return [UnprocessableEntityError] The error instance
+      # Represents a 422 Unprocessable Entity error.
+      #
+      # Use this error when the request is well-formed but contains semantic errors
+      # that prevent processing (e.g., business logic violations).
+      #
+      # @example
+      #   def call
+      #     return failure("Order already shipped", type: UnprocessableEntityError) if @order.shipped?
+      #   end
       class UnprocessableEntityError < ServiceError
         DEFAULT_MESSAGE = 'Unprocessable entity'
 
-        # 422 error response
-        # @return [Hash] The error response
+        # @return [Hash] API error response with :unprocessable_entity code
         def api_error
           { code: :unprocessable_entity, message: message }
         end
       end
 
-      # Error class for validation errors
-      # @param message [String] The error message
-      # @return [ValidationError] The error instance
+      # Represents validation failures (inherits 422 status).
+      #
+      # Automatically raised by the framework when schema validation fails.
+      # Can also be used for custom validation errors.
+      #
+      # @example
+      #   def call
+      #     return failure("Email format invalid", type: ValidationError) unless valid_email?
+      #   end
       class ValidationError < UnprocessableEntityError
         DEFAULT_MESSAGE = 'Validation failed'
       end
 
-      # Error class for internal server errors
-      # @param message [String] The error message
-      # @return [InternalServerError] The error instance
+      # Represents a 500 Internal Server Error.
+      #
+      # Use this error for unexpected server-side failures.
+      #
+      # @example
+      #   def call
+      #     return failure("Database connection lost", type: InternalServerError) if db_down?
+      #   end
       class InternalServerError < ServiceError
         DEFAULT_MESSAGE = 'Internal server error'
 
-        # 500 error response
-        # @return [Hash] The error response
+        # @return [Hash] API error response with :internal_server_error code
         def api_error
           { code: :internal_server_error, message: message }
         end
       end
 
-      # Error class for service unavailable errors
-      # @param message [String] The error message
-      # @return [ServiceUnavailableError] The error instance
+      # Represents a 503 Service Unavailable error.
+      #
+      # Use this error when a service dependency is temporarily unavailable.
+      #
+      # @example Using with rescue_from
+      #   class MyService < Servus::Base
+      #     rescue_from Net::HTTPError, use: ServiceUnavailableError
+      #
+      #     def call
+      #       make_external_api_call
+      #     end
+      #   end
       class ServiceUnavailableError < ServiceError
         DEFAULT_MESSAGE = 'Service unavailable'
 
-        # 503 error response
-        # @return [Hash] The error response
+        # @return [Hash] API error response with :service_unavailable code
         def api_error
           { code: :service_unavailable, message: message }
         end