servus 0.1.5 → 0.2.0

data/lib/servus/guards/truthy_guard.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Servus
+  module Guards
+    # Guard that ensures all specified attributes on an object are truthy.
+    #
+    # @example Single attribute
+    #   enforce_truthy!(on: user, check: :active)
+    #
+    # @example Multiple attributes (all must be truthy)
+    #   enforce_truthy!(on: user, check: [:active, :verified, :confirmed])
+    #
+    # @example Conditional check
+    #   if check_truthy?(on: subscription, check: :valid?)
+    #     # subscription is valid
+    #   end
+    class TruthyGuard < Servus::Guard
+      http_status 422
+      error_code 'must_be_truthy'
+
+      message '%<class_name>s.%<failed_attr>s must be truthy (got %<value>s)' do
+        message_data
+      end
+
+      # Tests whether all specified attributes are truthy.
+      #
+      # @param on [Object] the object to check
+      # @param check [Symbol, Array<Symbol>] attribute(s) to verify
+      # @return [Boolean] true if all attributes are truthy
+      def test(on:, check:)
+        Array(check).all? { |attr| !!on.public_send(attr) }
+      end
+
+      private
+
+      # Builds the interpolation data for the error message.
+      #
+      # @return [Hash] message interpolation data
+      def message_data
+        object = kwargs[:on]
+        check  = kwargs[:check]
+        failed = find_failing_attribute(object, Array(check))
+
+        {
+          failed_attr: failed,
+          class_name: object.class.name,
+          value: object.public_send(failed).inspect
+        }
+      end
+
+      # Finds the first attribute that fails the truthy check.
+      #
+      # @param object [Object] the object to check
+      # @param checks [Array<Symbol>] attributes to check
+      # @return [Symbol] the first failing attribute
+      def find_failing_attribute(object, checks)
+        checks.find { |attr| !object.public_send(attr) }
+      end
+    end
+  end
+end

data/lib/servus/guards.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Servus
+  # Module providing guard functionality to Servus services.
+  #
+  # Guard methods are defined directly on this module when guard classes
+  # inherit from Servus::Guard. The inherited hook triggers method definition,
+  # so no registry or method_missing is needed.
+  #
+  # @example Using guards in a service
+  #   class TransferService < Servus::Base
+  #     def call
+  #       enforce_presence!(user: user, account: account)
+  #       enforce_state!(on: account, check: :status, is: :active)
+  #       # ... perform transfer ...
+  #       success(result)
+  #     end
+  #   end
+  #
+  # @see Servus::Guard
+  module Guards
+    # Guard methods are defined dynamically via Servus::Guard.inherited
+    # when guard classes are loaded. Each guard class defines:
+    #   - enforce_<name>!  (throws :guard_failure on failure)
+    #   - check_<name>?  (returns boolean)
+
+    class << self
+      # Loads default guards if configured.
+      #
+      # Called after Guards module is defined to load built-in guards
+      # when Servus.config.include_default_guards is true.
+      #
+      # @return [void]
+      # @api private
+      def load_defaults
+        return unless Servus.config.include_default_guards
+
+        require_relative 'guards/presence_guard'
+        require_relative 'guards/truthy_guard'
+        require_relative 'guards/falsey_guard'
+        require_relative 'guards/state_guard'
+      end
+    end
+  end
+end
+
+# Load default guards based on configuration
+Servus::Guards.load_defaults

data/lib/servus/helpers/controller_helpers.rb

@@ -14,16 +14,12 @@ module Servus
     #   end
     #
     # @see #run_service
-    # @see #render_service_object_error
+    # @see #render_service_error
     module ControllerHelpers
       # Executes a service and handles success/failure automatically.
       #
-      # 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.
-      #
-      # The result is always stored in the @result instance variable, making it
-      # available in views for rendering successful responses.
+      # On success, stores the result in @result for use in views.
+      # On failure, renders the error as JSON with the appropriate HTTP status.
       #
       # @param klass [Class] service class to execute (must inherit from {Servus::Base})
       # @param params [Hash] keyword arguments to pass to the service
@@ -33,69 +29,45 @@ module Servus
       #   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
       #
-      # @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 Manual success handling
-      #   class UsersController < ApplicationController
-      #     def create
-      #       run_service Services::CreateUser::Service, user_params
-      #       return unless @result.success?
-      #
-      #       # Custom success handling
-      #       redirect_to user_path(@result.data[:user_id])
-      #     end
-      #   end
-      #
-      # @see #render_service_object_error
+      # @see #render_service_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?
+        render_service_error(@result.error) unless @result.success?
       end
 
       # Renders a service error as a JSON response.
       #
-      # 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.
+      # Uses error.http_status for the response status code and
+      # error.api_error for the response body.
       #
       # 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}
+      # @param error [Servus::Support::Errors::ServiceError] the error to render
       # @return [void]
       #
       # @example Default behavior
-      #   # Renders: { code: :not_found, message: "User not found" }
+      #   # Renders: { error: { 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
+      #   def render_service_error(error)
+      #     render json: {
+      #       error: {
+      #         type: error.api_error[:code],
+      #         details: error.message,
+      #         timestamp: Time.current
+      #       }
+      #     }, status: error.http_status
       #   end
       #
       # @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]
+      # @see Servus::Support::Errors::ServiceError#http_status
+      def render_service_error(error)
+        render json: { error: error.api_error }, status: error.http_status
       end
     end
   end

data/lib/servus/railtie.rb

@@ -19,14 +19,22 @@ module Servus
       end
     end
 
-    # Load event handlers and clear on reload
+    # Load guards and event handlers, clear caches on reload
     config.to_prepare do
+      # Load custom guards from guards_dir
+      guards_path = Rails.root.join(Servus.config.guards_dir)
+      if Dir.exist?(guards_path)
+        Dir[File.join(guards_path, '**/*_guard.rb')].each do |file|
+          require_dependency file
+        end
+      end
+
       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
+      Dir[File.join(events_path, '**/*_handler.rb')].each do |file|
+        require_dependency file
       end
     end
 

data/lib/servus/support/errors.rb

@@ -4,31 +4,31 @@ 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}.
+    # All error classes inherit from {ServiceError} and provide:
+    # - {ServiceError#http_status} for the HTTP response status
+    # - {ServiceError#api_error} for the JSON response body
     #
     # @see ServiceError
     module Errors
       # Base error class for all Servus service errors.
       #
-      # 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
+      # Subclasses define their HTTP status via {#http_status} and their
+      # API response format via {#api_error}.
       #
       # @example Creating a custom error type
-      #   class MyCustomError < Servus::Support::Errors::ServiceError
-      #     DEFAULT_MESSAGE = 'Something went wrong'
+      #   class InsufficientFundsError < Servus::Support::Errors::ServiceError
+      #     DEFAULT_MESSAGE = 'Insufficient funds'
+      #
+      #     def http_status = :unprocessable_entity
       #
       #     def api_error
-      #       { code: :custom_error, message: message }
+      #       { code: 'insufficient_funds', message: message }
       #     end
       #   end
       #
       # @example Using with failure method
       #   def call
-      #     return failure("User not found", type: Servus::Support::Errors::NotFoundError)
-      #     # ...
+      #     return failure("User not found", type: NotFoundError)
       #   end
       class ServiceError < StandardError
         attr_reader :message
@@ -38,188 +38,117 @@ module Servus
         # 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}")
+          super("#{self.class}: #{@message}")
         end
 
-        # Returns an API-friendly error response.
+        # Returns the HTTP status code for this error.
         #
-        # 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 [Symbol] Rails-compatible status symbol
+        def http_status = :bad_request
+
+        # Returns an API-friendly error response.
         #
         # @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
+        def api_error = { code: http_status, message: message }
       end
 
-      # 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
+      # 400 Bad Request - malformed or invalid request data.
       class BadRequestError < ServiceError
         DEFAULT_MESSAGE = 'Bad request'
 
-        # 400 error response
-        # @return [Hash] The error response
-        def api_error
-          { code: :bad_request, message: message }
-        end
+        def http_status = :bad_request
+        def api_error = { code: http_status, message: message }
       end
 
-      # 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
+      # 401 Unauthorized - authentication credentials missing or invalid.
       class AuthenticationError < ServiceError
         DEFAULT_MESSAGE = 'Authentication failed'
 
-        # @return [Hash] API error response with :unauthorized code
-        def api_error
-          { code: :unauthorized, message: message }
-        end
+        def http_status = :unauthorized
+        def api_error = { code: http_status, message: message }
       end
 
-      # 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
+      # 401 Unauthorized (alias for AuthenticationError).
       class UnauthorizedError < AuthenticationError
         DEFAULT_MESSAGE = 'Unauthorized'
       end
 
-      # 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
+      # 403 Forbidden - authenticated but not authorized.
       class ForbiddenError < ServiceError
         DEFAULT_MESSAGE = 'Forbidden'
 
-        # 403 error response
-        # @return [Hash] The error response
-        def api_error
-          { code: :forbidden, message: message }
-        end
+        def http_status = :forbidden
+        def api_error = { code: http_status, message: message }
       end
 
-      # 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
+      # 404 Not Found - requested resource does not exist.
       class NotFoundError < ServiceError
         DEFAULT_MESSAGE = 'Not found'
 
-        # @return [Hash] API error response with :not_found code
-        def api_error
-          { code: :not_found, message: message }
-        end
+        def http_status = :not_found
+        def api_error = { code: http_status, message: message }
       end
 
-      # 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
+      # 422 Unprocessable Entity - semantic errors in request.
       class UnprocessableEntityError < ServiceError
         DEFAULT_MESSAGE = 'Unprocessable entity'
 
-        # @return [Hash] API error response with :unprocessable_entity code
-        def api_error
-          { code: :unprocessable_entity, message: message }
-        end
+        def http_status = :unprocessable_entity
+        def api_error = { code: http_status, message: message }
       end
 
-      # 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
+      # 422 Validation Error - schema or business validation failed.
       class ValidationError < UnprocessableEntityError
         DEFAULT_MESSAGE = 'Validation failed'
+
+        def api_error = { code: http_status, message: message }
       end
 
-      # Represents a 500 Internal Server Error.
+      # Guard validation failure with custom code.
       #
-      # Use this error for unexpected server-side failures.
+      # Guards define their own error code and HTTP status via the DSL.
       #
       # @example
-      #   def call
-      #     return failure("Database connection lost", type: InternalServerError) if db_down?
-      #   end
+      #   GuardError.new("Amount must be positive", code: 'invalid_amount', http_status: 422)
+      class GuardError < ServiceError
+        DEFAULT_MESSAGE = 'Guard validation failed'
+
+        # @return [String] application-specific error code
+        attr_reader :code
+
+        # @return [Symbol, Integer] HTTP status code
+        attr_reader :http_status
+
+        # Creates a new guard error with metadata.
+        #
+        # @param message [String, nil] error message
+        # @param code [String] error code for API responses (default: 'guard_failed')
+        # @param http_status [Symbol, Integer] HTTP status (default: :unprocessable_entity)
+        def initialize(message = nil, code: 'guard_failed', http_status: :unprocessable_entity)
+          super(message)
+          @code        = code
+          @http_status = http_status
+        end
+
+        def api_error = { code: code, message: message }
+      end
+
+      # 500 Internal Server Error - unexpected server-side failure.
       class InternalServerError < ServiceError
         DEFAULT_MESSAGE = 'Internal server error'
 
-        # @return [Hash] API error response with :internal_server_error code
-        def api_error
-          { code: :internal_server_error, message: message }
-        end
+        def http_status = :internal_server_error
+        def api_error = { code: http_status, message: message }
       end
 
-      # 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
+      # 503 Service Unavailable - dependency temporarily unavailable.
       class ServiceUnavailableError < ServiceError
         DEFAULT_MESSAGE = 'Service unavailable'
 
-        # @return [Hash] API error response with :service_unavailable code
-        def api_error
-          { code: :service_unavailable, message: message }
-        end
+        def http_status = :service_unavailable
+        def api_error = { code: http_status, message: message }
       end
     end
   end