servus 0.0.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36f4d4b15ff9038d9c039f6efb0fe5027c6326811334dc3e478a906b31286d5d
-  data.tar.gz: 786b002fe1937d5204088fdb982156bc1fb1ce7bc1c20f2ecd4c737e23e1acd5
+  metadata.gz: 0bddb5c486e4996dff5183d6a9bd57ef086739d7007a12125479d320464a0018
+  data.tar.gz: 2d948b6202d0888664a75766cf4e9a3c607b4f819e7d9293ac0d0ff8f42c6c32
 SHA512:
-  metadata.gz: 04ce3e7a6cdd2371c4da93d98123ea640736856638dfa5c2a60d3c4b4c7ae1109bd597bf577cec892461677a906e0955ee782c20532901b3808eca80c6ccbb6a
-  data.tar.gz: 9c07175986bd05753df2b29dbc70f854cbab12745183d6e8937cc89dd46e5e819df588ac0ef88ea2db8298cb6e470e798a8e3361cc8765194ddee1244c7a2d1c
+  metadata.gz: 18a6ffd8d72e5a452bda53b5d91a621d0b963872c08d72b8ee4a533160babfde16ed9690a1f9a0b2c5aa1a4c330f3e6209b9ada2ffdba3635bad9cf0bd351d8e
+  data.tar.gz: 59b87da3ae33ec0a586275892632b6fe84810b44d75759d9c6c2733fdb9224093d1ed9740467438908eb4a5640b41b6468f1c8381c65cc07adf843e23979fb80

data/.rubocop.yml

@@ -0,0 +1,11 @@
+AllCops:
+  Include:
+    - 'lib/**/*.rb'
+    - 'spec/**/*.rb'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.1.2] - 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
+
+## [0.1.1] - 2025-08-20
+
+- Added: Added `rescue_from` method to `Servus::Base` to rescue from standard errors and use custom error types.
+- Added: Added `run_service` and `render_service_object_error` helpers to `Servus::Helpers::ControllerHelpers`.
+- Fixed: All rubocop warnings.
+
 ## [0.1.0] - 2025-04-28
 
 - Initial release

data/READme.md

@@ -119,6 +119,29 @@ 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)
+
+```ruby
+# Good ✅
+Services::NotifyUser::Service.call_async(
+  user_id: current_user.id,
+  wait: 5.minutes,
+  queue: :low_priority,
+  job_options: { tags: ['notifications'] }
+)
+
+# Bad ❌
+Services::NotifyUser::Support::MessageBuilder.call_async(
+  # Invalid: support classes don't inherit from Servus::Base
+)
+```
+
 ## **Inheritance**
 
 - Every main service class (`service.rb`) must inherit from `Servus::Base`
@@ -249,18 +272,114 @@ end
 class SomeController < AppController
 	def controller_action
 	  result = SomeServiceObject::Service.call(arg: 1)
-	
+
 	  return if result.success?
-	
+
 	  # If you just want the error message
 	  bad_request(result.error.message)
-	
+
 	  # If you want the API error
 	  service_object_error(result.error.api_error)
 	end
 end
 ```
 
+### `rescue_from` for service errors
+
+Services can configure default error handling using the `rescue_from` method.
+
+```ruby
+class SomeServiceObject::Service < Servus::Base
+  class SomethingBroke < StandardError; end
+  class SomethingGlitched < StandardError; end
+
+  # Rescue from standard errors and use custom error
+  rescue_from
+    SomethingBroke,
+    SomethingGlitched,
+    use: Servus::Support::Errors::ServiceUnavailableError # this is optional
+
+  def call
+    do_something
+  end
+
+  private
+
+  def do_something
+    make_and_api_call
+    rescue Net::HTTPError => e
+      raise SomethingGlitched, "Whoaaaa, something went wrong! #{e.message}"
+    end
+  end
+end
+```
+
+```sh
+result = SomeServiceObject::Service.call
+# Failure response
+result.error.class
+=> Servus::Support::Errors::ServiceUnavailableError
+result.error.message
+=> "[SomeServiceObject::Service::SomethingGlitched]: Whoaaaa, something went wrong! Net::HTTPError (503)"
+result.error.api_error
+=> { code: :service_unavailable, message: "[SomeServiceObject::Service::SomethingGlitched]: Whoaaaa, something went wrong! Net::HTTPError (503)" }
+```
+
+The `rescue_from` method will rescue from the specified errors and use the specified error type to create a failure response object with
+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.
+
+## Controller Helpers
+
+Service objects can be called from controllers using the `run_service` and `render_service_object_error` helpers.
+
+### run_service
+
+`run_service` calls the service object with the provided parameters and set's an instance variable `@result` to the
+result of the service object if the result is successful. If the result is not successful, it will pass the result
+to error to the `render_service_object_error` helper. This allows for easy error handling in the controller for
+repetetive usecases.
+
+```ruby
+class SomeController < AppController
+  # Before
+  def controller_action
+    result = Services::SomeServiceObject::Service.call(my_params)
+    return if result.success?
+    render_service_object_error(result.error.api_error)
+  end
+
+  # After
+  def controller_action_refactored
+    run_service Services::SomeServiceObject::Service, my_params
+  end
+end
+```
+
+### render_service_object_error
+
+`render_service_object_error` renders the error of a service object. It expects a hash with a `message` key and a `code` key from
+the api_error method of the service error. This is all setup by default for a JSON API response, thought the method can be
+overridden if needed to handle different usecases.
+
+```ruby
+# Behind the scenes, render_service_object_error calls the following:
+#
+#  error = result.error.api_error
+#  => { message: "Error message", code: 400 }
+#
+#  render json: { message: error[:message], code: error[:code] }, status: error[:code]
+
+class SomeController < AppController
+  def controller_action
+    result = Services::SomeServiceObject::Service.call(my_params)
+    return if result.success?
+
+    render_service_object_error(result.error.api_error)
+  end
+end
+```
+
 ## **Schema Validation**
 
 Service objects support two methods for schema validation: JSON Schema files and inline schema declarations.
@@ -376,4 +495,4 @@ 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 `SchemaValidation.clear_cache!`

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

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

@@ -4,17 +4,17 @@ module Servus
   module Generators
     # Servus Generator
     class ServiceGenerator < Rails::Generators::NamedBase
-      source_root File.expand_path("templates", __dir__)
+      source_root File.expand_path('templates', __dir__)
 
-      argument :parameters, type: :array, default: [], banner: "parameter"
+      argument :parameters, type: :array, default: [], banner: 'parameter'
 
       def create_service_file
-        template "service.rb.erb", service_path
-        template "service_spec.rb.erb", service_path_spec
+        template 'service.rb.erb', service_path
+        template 'service_spec.rb.erb', service_path_spec
 
         # Template json schemas
-        template "result.json.erb", service_result_schema_path
-        template "arguments.json.erb", service_arguments_shecma_path
+        template 'result.json.erb', service_result_schema_path
+        template 'arguments.json.erb', service_arguments_shecma_path
       end
 
       private
@@ -40,13 +40,13 @@ module Servus
       end
 
       def service_full_class_name
-        service_class_name.include?("::") ? service_class_name : "::#{service_class_name}"
+        service_class_name.include?('::') ? service_class_name : "::#{service_class_name}"
       end
 
       def parameter_list
-        return "" if parameters.empty?
+        return '' if parameters.empty?
 
-        "(#{parameters.map { |param| "#{param}:" }.join(", ")})"
+        "(#{parameters.map { |param| "#{param}:" }.join(', ')})"
       end
 
       def initialize_params
@@ -54,9 +54,9 @@ module Servus
       end
 
       def attr_readers
-        return "" if parameters.empty?
+        return '' if parameters.empty?
 
-        "attr_reader #{parameters.map { |param| ":#{param}" }.join(", ")}"
+        "attr_reader #{parameters.map { |param| ":#{param}" }.join(', ')}"
       end
     end
   end

data/lib/servus/base.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 module Servus
+  # Base class for all services
   class Base
     include Servus::Support::Errors
+    include Servus::Support::Rescuer
 
     # Support class aliases
     Logger = Servus::Support::Logger
@@ -10,21 +12,16 @@ module Servus
     Validator = Servus::Support::Validator
 
     # Calls the service and returns a response
+    #
     # @param args [Hash] The arguments to pass to the service
     # @return [Servus::Support::Response] The response
     # @raise [StandardError] If an exception is raised
     # @raise [Servus::Support::Errors::ValidationError] If result is invalid
     # @raise [Servus::Support::Errors::ValidationError] If arguments are invalid
     def self.call(**args)
-      Logger.log_call(self, args)
-
-      Validator.validate_arguments!(self, args)
-
-      result = benchmark(**args) do
-        new(**args).call
-      end
-
-      Validator.validate_result!(self, result)
+      before_call(args)
+      result = benchmark(**args) { new(**args).call }
+      after_call(result)
 
       result
     rescue ValidationError => e
@@ -36,6 +33,7 @@ module Servus
     end
 
     # Returns a success response
+    #
     # @param data [Object] The data to return
     # @return [Servus::Support::Response] The success response
     def success(data)
@@ -43,6 +41,7 @@ module Servus
     end
 
     # Returns a failure response
+    #
     # @param message [String] The error message
     # @param type [Class] The error type
     # @return [Servus::Support::Response] The failure response
@@ -52,6 +51,7 @@ module Servus
     end
 
     # Raises an error and logs it
+    #
     # @param message [String] The error message
     # @param type [Class] The error type
     # @return [void]
@@ -60,7 +60,25 @@ module Servus
       raise type, message
     end
 
+    # Runs call setup before call
+    #
+    # @param args [Hash] The arguments to pass to the service
+    # @return [Object] The result of the call
+    def self.before_call(args)
+      Logger.log_call(self, args)
+      Validator.validate_arguments!(self, args)
+    end
+
+    # Runs after call
+    #
+    # @param args [Hash] The arguments to pass to the service
+    # @return [Object] The result of the call
+    def self.after_call(args)
+      Validator.validate_result!(self, args)
+    end
+
     # Benchmarks the call
+    #
     # @param args [Hash] The arguments to pass to the service
     # @return [Object] The result of the call
     def self.benchmark(**_args)

data/lib/servus/config.rb

@@ -1,17 +1,15 @@
 # frozen_string_literal: true
 
+# Servus namespace
 module Servus
+  # Configuration class for Servus
   class Config
     # The directory where schemas are loaded from, can be set by the user
     attr_reader :schema_root
 
     def initialize
       # Default to Rails.root if available, otherwise use current working directory
-      @schema_root = if defined?(Rails)
-        Rails.root.join("app/schemas/services")
-      else
-        File.expand_path("../../../app/schemas/services", __dir__)
-      end
+      @schema_root = File.join(root_path, 'app/schemas/services')
     end
 
     # Returns the path for a specific service's schema
@@ -30,6 +28,19 @@ module Servus
     def schema_dir_for(service_namespace)
       File.join(schema_root.to_s, service_namespace)
     end
+
+    private
+
+    # Sets the schema root directory
+    #
+    # @param path [String] the new schema root directory
+    def root_path
+      if defined?(Rails) && Rails.respond_to?(:root)
+        Rails.root
+      else
+        File.expand_path('../../..', __dir__)
+      end
+    end
   end
 
   # Singleton config instance

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Async
+      # Calls the service asynchronously using AsyncCallerJob.
+      #
+      # Supports all standard ActiveJob scheduling and routing options:
+      #   - wait:        <ActiveSupport::Duration>   (e.g., 5.minutes)
+      #   - wait_until:  <Time>                      (e.g., 2.hours.from_now)
+      #   - queue:       <Symbol/String>             (e.g., :critical, 'low_priority')
+      #   - priority:    <Integer>                   (depends on adapter support)
+      #   - retry:       <Boolean>                   (custom control for job retry)
+      #   - job_options: <Hash>                      (extra options, merged in)
+      #
+      # Example:
+      #   call_async(
+      #     wait: 10.minutes,
+      #     queue: :low_priority,
+      #     priority: 20,
+      #     job_options: { tags: ['user_graduation'] },
+      #     user_id: current_user.id
+      #   )
+      #
+      module Call
+        # @param args [Hash] The arguments to pass to the service and job options.
+        # @return [void]
+        def call_async(**args)
+          # Extract ActiveJob configuration options
+          job_options = args.slice(:wait, :wait_until, :queue, :priority)
+          job_options.merge!(args.delete(:job_options) || {}) # merge custom job options
+
+          # Remove special keys that shouldn't be passed to the service
+          args.except!(:wait, :wait_until, :queue, :priority, :job_options)
+
+          # Build job with optional delay, scheduling, or queue settings
+          job = job_options.any? ? Job.set(**job_options.compact) : Job
+
+          # Enqueue the job asynchronously
+          job.perform_later(name: name, args: args)
+        rescue StandardError => e
+          raise Errors::JobEnqueueError, "Failed to enqueue async job for #{self}: #{e.message}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Async
+      module Errors
+        # Base error class for async extensions
+        class AsyncError < StandardError; end
+
+        # Error raised when the job fails to enqueue
+        class JobEnqueueError < AsyncError; end
+
+        # Error raised when the service class cannot be found
+        class ServiceNotFoundError < AsyncError; end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    # Async extensions for Servus
+    module Async
+      require 'servus/extensions/async/errors'
+      require 'servus/extensions/async/job'
+      require 'servus/extensions/async/call'
+
+      # Module providing async extensions for Servus
+      module Ext; end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Async
+      # Job to run a service class with given arguments.
+      #
+      # 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.
+      #
+      # Example usage:
+      #   RunServiceJob.perform_later('SomeModule::SomeService', arg1: value1, arg2: value2)
+      #
+      # This will invoke SomeModule::SomeService.call(arg1: value1, arg2: value2) in a background job.
+      #
+      # Errors during service execution are logged.
+      class Job < ActiveJob::Base
+        queue_as :default
+
+        def perform(name:, args:)
+          constantize!(name).call(**args)
+        end
+
+        private
+
+        attr_reader :klass
+
+        def constantize!(class_name)
+          class_name.safe_constantize || (raise Errors::ServiceNotFoundError,
+                                                "Service class '#{class_name}' not found.")
+        end
+      end
+    end
+  end
+end

data/lib/servus/helpers/controller_helpers.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Servus
+  module Helpers
+    # Controller helpers
+    module ControllerHelpers
+      # Run a service object and return the result
+      #
+      # 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.
+      #
+      # @example:
+      #   class TestController < ApplicationController
+      #     def index
+      #       run_service MyService::Service, params
+      #     end
+      #   end
+      #
+      # The result of the service is stored in the instance variable @result, which can be used
+      # in views to template a response.
+      #
+      # @example:
+      #   json.data do
+      #     json.some_key @result.data[:some_key]
+      #   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:
+      #   # Example implementation of api_error on Servus::Support::Errors::ServiceError
+      #   # def api_error
+      #   #   { code: :bad_request, message: message }
+      #   # end
+      #
+      #   Example implementation of service_object_error
+      #   def service_object_error(api_error)
+      #     render json: api_error, status: api_error[:code]
+      #   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
+      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
+      #
+      # This method is a helper method for controllers to render service object errors.
+      #
+      # @param api_error [Hash] The API error response
+      #
+      # @see Servus::Support::Errors::ServiceError
+      def render_service_object_error(api_error)
+        render json: api_error, status: api_error[:code]
+      end
+    end
+  end
+end

data/lib/servus/railtie.rb

@@ -1,8 +1,22 @@
 # frozen_string_literal: true
 
-# lib/servus/railtie.rb
-require "rails/railtie"
+require 'rails/railtie'
 
 module Servus
-  class Railtie < Rails::Railtie; end
+  # Railtie for Rails integration
+  class Railtie < Rails::Railtie
+    initializer 'servus.controller_helpers' do
+      ActiveSupport.on_load(:action_controller) do
+        include Servus::Helpers::ControllerHelpers
+      end
+    end
+
+    initializer 'servus.job_async' do
+      ActiveSupport.on_load(:active_job) do
+        require 'servus/extensions/async/ext'
+        # Extend the base service with the async call method
+        Servus::Base.extend Servus::Extensions::Async::Call
+      end
+    end
+  end
 end

data/lib/servus/support/errors.rb

@@ -4,12 +4,13 @@ module Servus
   module Support
     module Errors
       # Base error class for application services
+      #
       # @param message [String] The error message
       # @return [ServiceError] The error instance
       class ServiceError < StandardError
         attr_reader :message
 
-        DEFAULT_MESSAGE = "An error occurred"
+        DEFAULT_MESSAGE = 'An error occurred'
 
         # Initializes a new error instance
         # @param message [String] The error message
@@ -30,7 +31,7 @@ module Servus
       # @param message [String] The error message
       # @return [BadRequestError] The error instance
       class BadRequestError < ServiceError
-        DEFAULT_MESSAGE = "Bad request"
+        DEFAULT_MESSAGE = 'Bad request'
 
         # 400 error response
         # @return [Hash] The error response
@@ -43,7 +44,7 @@ module Servus
       # @param message [String] The error message
       # @return [AuthenticationError] The error instance
       class AuthenticationError < ServiceError
-        DEFAULT_MESSAGE = "Authentication failed"
+        DEFAULT_MESSAGE = 'Authentication failed'
 
         # 401 error response
         # @return [Hash] The error response
@@ -56,14 +57,14 @@ module Servus
       # @param message [String] The error message
       # @return [UnauthorizedError] The error instance
       class UnauthorizedError < AuthenticationError
-        DEFAULT_MESSAGE = "Unauthorized"
+        DEFAULT_MESSAGE = 'Unauthorized'
       end
 
       # Error class for forbidden errors
       # @param message [String] The error message
       # @return [ForbiddenError] The error instance
       class ForbiddenError < ServiceError
-        DEFAULT_MESSAGE = "Forbidden"
+        DEFAULT_MESSAGE = 'Forbidden'
 
         # 403 error response
         # @return [Hash] The error response
@@ -76,7 +77,7 @@ module Servus
       # @param message [String] The error message
       # @return [NotFoundError] The error instance
       class NotFoundError < ServiceError
-        DEFAULT_MESSAGE = "Not found"
+        DEFAULT_MESSAGE = 'Not found'
 
         # 404 error response
         # @return [Hash] The error response
@@ -89,7 +90,7 @@ module Servus
       # @param message [String] The error message
       # @return [UnprocessableEntityError] The error instance
       class UnprocessableEntityError < ServiceError
-        DEFAULT_MESSAGE = "Unprocessable entity"
+        DEFAULT_MESSAGE = 'Unprocessable entity'
 
         # 422 error response
         # @return [Hash] The error response
@@ -102,14 +103,14 @@ module Servus
       # @param message [String] The error message
       # @return [ValidationError] The error instance
       class ValidationError < UnprocessableEntityError
-        DEFAULT_MESSAGE = "Validation failed"
+        DEFAULT_MESSAGE = 'Validation failed'
       end
 
       # Error class for internal server errors
       # @param message [String] The error message
       # @return [InternalServerError] The error instance
       class InternalServerError < ServiceError
-        DEFAULT_MESSAGE = "Internal server error"
+        DEFAULT_MESSAGE = 'Internal server error'
 
         # 500 error response
         # @return [Hash] The error response
@@ -122,7 +123,7 @@ module Servus
       # @param message [String] The error message
       # @return [ServiceUnavailableError] The error instance
       class ServiceUnavailableError < ServiceError
-        DEFAULT_MESSAGE = "Service unavailable"
+        DEFAULT_MESSAGE = 'Service unavailable'
 
         # 503 error response
         # @return [Hash] The error response

data/lib/servus/support/logger.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
-require "logger"
+require 'logger'
 
 module Servus
   module Support
+    # Logger class for logging service calls and results
     class Logger
       # Returns the logger instance depending on the environment
       #

data/lib/servus/support/rescuer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Servus
+  module Support
+    # Module that rescues the call method from errors
+    module Rescuer
+      # Includes the rescuer module into the base class
+      #
+      # @param base [Class] The base class to include the rescuer module into
+      def self.included(base)
+        base.class_attribute :rescuable_errors, default: []
+        base.class_attribute :rescuable_error_type, default: nil
+        base.singleton_class.prepend(CallOverride)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods for rescue_from
+      module ClassMethods
+        # Rescues the call method from errors
+        #
+        # By configuring error classes in the rescue_from method, the call method will rescue from those errors
+        # and return a failure response with a ServiceError and formatted error message. This prevents the need to
+        # to have excessive rescue blocks in the call method.
+        #
+        # @example:
+        #   class TestService < Servus::Base
+        #     rescue_from SomeError, type: Servus::Support::Errors::ServiceError
+        #   end
+        #
+        # @param [Error] errors One or more errors to rescue from (variadic)
+        # @param [Error] use The error to be used (optional, defaults to Servus::Support::Errors::ServiceError)
+        def rescue_from(*errors, use: Servus::Support::Errors::ServiceError)
+          self.rescuable_errors = errors
+          self.rescuable_error_type = use
+        end
+      end
+
+      # Module that overrides the call method to rescue from errors
+      module CallOverride
+        # Overrides the call method to rescue from errors
+        #
+        # @param args [Hash] The arguments passed to the call method
+        # @return [Servus::Support::Response] The result of the call method
+        def call(**args)
+          if rescuable_errors.any?
+            begin
+              super
+            rescue *rescuable_errors => e
+              handle_failure(e, rescuable_error_type)
+            end
+          else
+            super
+          end
+        end
+
+        # Returns a failure response with a ServiceError and formatted error message
+        #
+        # The `failure` method is an instance method of the base class, so it can't be called from this module which
+        # is rescuing the call method.
+        #
+        # @param [Error] error The error to be used
+        # @param [Class] type The error type
+        # @return [Servus::Support::Response] The failure response
+        def handle_failure(error, type)
+          error = type.new(template_error_message(error))
+          Response.new(false, nil, error)
+        end
+
+        # Templates the error message
+        #
+        # @param [Error] error The error to be used
+        # @return [String] The formatted error message
+        def template_error_message(error)
+          "[#{error.class}]: #{error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/servus/support/response.rb

@@ -2,15 +2,28 @@
 
 module Servus
   module Support
+    # Response class for service results
     class Response
-      attr_reader :data, :error
+      # [Object] The data returned by the service
+      attr_reader :data
 
+      # [Servus::Support::Errors::ServiceError] The error returned by the service
+      attr_reader :error
+
+      # Initializes a new response
+      #
+      # @param success [Boolean] Whether the response was successful
+      # @param data [Object] The data returned by the service
+      # @param error [Servus::Support::Errors::ServiceError] The error returned by the service
       def initialize(success, data, error)
         @success = success
         @data = data
         @error = error
       end
 
+      # Returns whether the response was successful
+      #
+      # @return [Boolean] Whether the response was successful
       def success?
         @success
       end

data/lib/servus/support/validator.rb

@@ -2,20 +2,21 @@
 
 module Servus
   module Support
+    # Validates arguments and results
     class Validator
       # Class-level schema cache
       @schema_cache = {}
 
       # Validate service arguments against schema
       def self.validate_arguments!(service_class, args)
-        schema = load_schema(service_class, "arguments")
+        schema = load_schema(service_class, 'arguments')
         return true unless schema # Skip validation if no schema exists
 
         serialized_result = args.as_json
         validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
 
         if validation_errors.any?
-          error_message = "Invalid arguments for #{service_class.name}: #{validation_errors.join(", ")}"
+          error_message = "Invalid arguments for #{service_class.name}: #{validation_errors.join(', ')}"
           raise Servus::Base::ValidationError, error_message
         end
 
@@ -26,14 +27,14 @@ module Servus
       def self.validate_result!(service_class, result)
         return result unless result.success?
 
-        schema = load_schema(service_class, "result")
+        schema = load_schema(service_class, 'result')
         return result unless schema # Skip validation if no schema exists
 
         serialized_result = result.data.as_json
         validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
 
         if validation_errors.any?
-          error_message = "Invalid result structure from #{service_class.name}: #{validation_errors.join(", ")}"
+          error_message = "Invalid result structure from #{service_class.name}: #{validation_errors.join(', ')}"
           raise Servus::Base::ValidationError, error_message
         end
 
@@ -43,27 +44,18 @@ module Servus
       # Load schema from file with caching
       def self.load_schema(service_class, type)
         # Get service path based on class name (e.g., "process_payment" from "Servus::ProcessPayment::Service")
-        service_namespace = service_class.name.split("::")[..-2].map do |s|
-          s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
-        end.join("/")
+        service_namespace = parse_service_namespace(service_class)
         schema_path = Servus.config.schema_path_for(service_namespace, type)
 
         # Return from cache if available
         return @schema_cache[schema_path] if @schema_cache.key?(schema_path)
 
         inline_schema_constant_name = "#{service_class}::#{type.upcase}_SCHEMA"
-        inline_schema_constant = Object.const_defined?(inline_schema_constant_name) ? Object.const_get(inline_schema_constant_name) : nil
-
-        if inline_schema_constant
-          @schema_cache[schema_path] =
-            inline_schema_constant.respond_to?(:deep_stringify_keys) ? inline_schema_constant.deep_stringify_keys : inline_schema_constant
-        elsif File.exist?(schema_path)
-          @schema_cache[schema_path] = JSON.parse(File.read(schema_path))
-        else
-          # Cache nil result to avoid checking file system again
-          @schema_cache[schema_path] = nil
-        end
+        inline_schema_constant = if Object.const_defined?(inline_schema_constant_name)
+                                   Object.const_get(inline_schema_constant_name)
+                                 end
 
+        @schema_cache[schema_path] = fetch_schema_from_sources(inline_schema_constant, schema_path)
         @schema_cache[schema_path]
       end
 
@@ -76,6 +68,32 @@ module Servus
       def self.cache
         @schema_cache
       end
+
+      # Fetches the schema from the sources
+      #
+      # This method checks if the schema is defined as an inline constant or if it exists as a file. The
+      # schema is then symbolized and returned. If the schema is not found, nil is returned.
+      #
+      # @param inline_schema_constant [Hash, String] the inline schema constant to process
+      # @param schema_path [String] the path to the schema file
+      # @return [Hash] the processed inline schema constant
+      def self.fetch_schema_from_sources(inline_schema_constant, schema_path)
+        if inline_schema_constant
+          inline_schema_constant.with_indifferent_access
+        elsif File.exist?(schema_path)
+          JSON.load_file(schema_path).with_indifferent_access
+        end
+      end
+
+      # Parses the service namespace from the service class name
+      #
+      # @param service_class [Class] the service class to parse
+      # @return [String] the service namespace
+      def self.parse_service_namespace(service_class)
+        service_class.name.split('::')[..-2].map do |s|
+          s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+        end.join('/')
+      end
     end
   end
 end

data/lib/servus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Servus
-  VERSION = "0.0.1"
+  VERSION = '0.1.2'
 end

data/lib/servus.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
 
 # Globals
-require "json-schema"
-require "active_model_serializers"
+require 'json-schema'
+require 'active_support'
+require 'active_support/core_ext/class/attribute'
+require 'active_model_serializers'
 
 # Servus namespace
 module Servus; end
 
+# Helpers
+require_relative 'servus/helpers/controller_helpers'
+
 # Railtie
-require_relative "servus/railtie" if defined?(Rails::Railtie)
+require_relative 'servus/railtie' if defined?(Rails::Railtie)
 
 # Config
-require_relative "servus/config"
+require_relative 'servus/config'
 
 # Support
-require_relative "servus/support/logger"
-require_relative "servus/support/response"
-require_relative "servus/support/validator"
-require_relative "servus/support/errors"
+require_relative 'servus/support/logger'
+require_relative 'servus/support/response'
+require_relative 'servus/support/validator'
+require_relative 'servus/support/errors'
+require_relative 'servus/support/rescuer'
 
 # Core
-require_relative "servus/version"
-require_relative "servus/base"
+require_relative 'servus/version'
+require_relative 'servus/base'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: json-schema
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A gem for managing service objects.
 email:
 - sebscholl@gmail.com
@@ -45,10 +73,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- ".rubocop.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - READme.md
 - Rakefile
+- builds/servus-0.0.1.gem
+- builds/servus-0.1.1.gem
 - lib/generators/servus/service/service_generator.rb
 - lib/generators/servus/service/templates/arguments.json.erb
 - lib/generators/servus/service/templates/result.json.erb
@@ -57,9 +88,15 @@ files:
 - lib/servus.rb
 - lib/servus/base.rb
 - lib/servus/config.rb
+- lib/servus/extensions/async/call.rb
+- lib/servus/extensions/async/errors.rb
+- lib/servus/extensions/async/ext.rb
+- lib/servus/extensions/async/job.rb
+- lib/servus/helpers/controller_helpers.rb
 - lib/servus/railtie.rb
 - lib/servus/support/errors.rb
 - lib/servus/support/logger.rb
+- lib/servus/support/rescuer.rb
 - lib/servus/support/response.rb
 - lib/servus/support/validator.rb
 - lib/servus/version.rb