servus 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69e20c0a6d4d7b3651839114f930d1befbc49701c15f9489f6a180e9384698c9
-  data.tar.gz: 1267963f2b5957d73fc4fb39654df87104932fc831786541db48ba478fa53d4f
+  metadata.gz: 0bddb5c486e4996dff5183d6a9bd57ef086739d7007a12125479d320464a0018
+  data.tar.gz: 2d948b6202d0888664a75766cf4e9a3c607b4f819e7d9293ac0d0ff8f42c6c32
 SHA512:
-  metadata.gz: 9ebcf136c2ce120b4489c4cf403c9a4b850ae83156429816acdc15776140b21a3d420cbe14fb24def19fde9c07fa7ef2fdac3cc2b62b0d2f6004a8dbd0898e8d
-  data.tar.gz: b367bd7c82bf0f5e4606b0bf8cbee2c777171018a370478d3a9ef07a5dc7d24ea6e240c78bdaf34c5a0cd19491101ea88c865b15e9bfa589e3dad76672ad4868
+  metadata.gz: 18a6ffd8d72e5a452bda53b5d91a621d0b963872c08d72b8ee4a533160babfde16ed9690a1f9a0b2c5aa1a4c330f3e6209b9ada2ffdba3635bad9cf0bd351d8e
+  data.tar.gz: 59b87da3ae33ec0a586275892632b6fe84810b44d75759d9c6c2733fdb9224093d1ed9740467438908eb4a5640b41b6468f1c8381c65cc07adf843e23979fb80

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [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.

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,12 +272,12 @@ 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
@@ -271,9 +294,9 @@ class SomeServiceObject::Service < Servus::Base
   class SomethingGlitched < StandardError; end
 
   # Rescue from standard errors and use custom error
-  rescue_from 
-    SomethingBroke, 
-    SomethingGlitched, 
+  rescue_from
+    SomethingBroke,
+    SomethingGlitched,
     use: Servus::Support::Errors::ServiceUnavailableError # this is optional
 
   def call
@@ -312,8 +335,8 @@ Service objects can be called from controllers using the `run_service` and `rend
 
 ### 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 
+`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.
 
@@ -335,7 +358,7 @@ 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 
+`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.
 
@@ -344,7 +367,7 @@ overridden if needed to handle different usecases.
 #
 #  error = result.error.api_error
 #  => { message: "Error message", code: 400 }
-# 
+#
 #  render json: { message: error[:message], code: error[:code] }, status: error[:code]
 
 class SomeController < AppController
@@ -472,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/lib/servus/config.rb

@@ -9,11 +9,7 @@ module Servus
 
     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
@@ -32,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/railtie.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# lib/servus/railtie.rb
 require 'rails/railtie'
 
 module Servus
@@ -11,5 +10,13 @@ module Servus
         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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -79,6 +79,7 @@ files:
 - 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
@@ -87,6 +88,10 @@ 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