servus 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc5b23e5aa35d4127cfb7afe7e784dced5eca17c776f3561a1c00037b7b59e74
-  data.tar.gz: b70c8e9b14cd59b2e4d1eb38a0846f3cdbbabf65d372204690a4458b5d14f8af
+  metadata.gz: 11fe445ce97bbd8300a08023e80eb1516011657d7412b6f5c9215f6c40aeb12d
+  data.tar.gz: 4cf1448c26b970cea781ccc2e7c21ddf5b8bde6f7703d070b59ea0809d752d1b
 SHA512:
-  metadata.gz: 6990920d0e7f5b6c9285ce9636a5fef5b301a329f05ee03316c17b4e268e7838cb83e0dd2d352e147e6865e2d5a58cc274940bb2110e52d8cdec3af3d7509f1b
-  data.tar.gz: 5b90d1643831c078ad81ad09ff04aa9baa9b84a5203f22c31e91d5cb42aa869b2e2ca089664effaab2f1c78b1d7a504840e2add6236e2b10478b44cd2bc9c17d
+  metadata.gz: f294661ff53e5340f52c8de15485c06c16820cb2b90b8d517c8e01322ee54fb0e7beec46f9560b3fe47d4c09b184474ccb5634368c2d902b0ab2c2106407d5bb
+  data.tar.gz: 3772632d087a92a26dcf24268570d1a4c1fd8887df493dd0a4c39b5cf899db8d5ec8e0bd3397738d4d64934f345ae9778eb7fef98e3a7f415d3f166f31005859

data/lib/servus/base.rb

@@ -246,7 +246,7 @@ module Servus
       # @see #initialize
       # @see #call
       #
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def call(**args)
         before_call(args)
 
@@ -272,7 +272,6 @@ module Servus
         Logger.log_exception(self, e)
         raise e
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Executes pre-call hooks including logging and argument validation.
       #

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

@@ -70,21 +70,18 @@ module Servus
         # @see Servus::Base.call
         # @see #servus_job_class
         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
-          job_options.compact!
+          refuse_nameless_job!
 
-          # Remove special keys that shouldn't be passed to the service
-          args.except!(:wait, :wait_until, :queue, :priority, :job_options)
+          job_options = extract_job_options!(args)
 
           # The named job class identifies the service — only args are serialized.
           job = job_options.any? ? servus_job_class.set(**job_options) : servus_job_class
           job.perform_later(**args)
-        rescue Servus::Support::Errors::ServiceError, Servus::Events::Errors::Error
+        rescue Servus::Support::Errors::ServiceError, Servus::Events::Errors::Error, Errors::AsyncError
           # With the :inline and :test adapters perform_later runs the service,
-          # so Servus's own errors surface here. Wrapping them as an enqueue
-          # failure would blame the wrong layer.
+          # so Servus's own errors surface here — as do this extension's own,
+          # like the name-conflict refusal above. Wrapping any of them as an
+          # enqueue failure would blame the wrong layer.
           raise
         rescue StandardError => e
           raise Errors::JobEnqueueError, "Failed to enqueue async job for #{self}: #{e.message}"
@@ -158,6 +155,23 @@ module Servus
 
         private
 
+        # Splits ActiveJob configuration out of the combined argument hash, mutating
+        # +args+ so only the service's own arguments remain.
+        #
+        # @param args [Hash] combined service arguments and job configuration options
+        # @return [Hash] the ActiveJob options (+wait+, +queue+, …) for +set+
+        # @api private
+        def extract_job_options!(args)
+          job_options = args.slice(:wait, :wait_until, :queue, :priority)
+          job_options.merge!(args.delete(:job_options) || {}) # merge custom job options
+          job_options.compact!
+
+          # Remove special keys that shouldn't be passed to the service
+          args.except!(:wait, :wait_until, :queue, :priority, :job_options)
+
+          job_options
+        end
+
         # Generates a named job subclass for this service and installs it as a sibling
         # constant in the service's parent namespace.
         #
@@ -166,6 +180,12 @@ module Servus
         # {#inherited}) means Rails' production eager-load defines every service's job
         # at boot, so worker processes can constantize the serialized job name.
         #
+        # An app that already owns that constant keeps it: +Foo+ alongside a
+        # hand-written +FooJob+ is ordinary Rails, and overwriting it replaced a real
+        # job class with this one silently. The generated class is still returned so
+        # the service keeps working, but it is unnamed — {#call_async} refuses it with
+        # {Errors::JobNameConflictError} rather than enqueue an unresolvable job.
+        #
         # @return [Class<Servus::Extensions::Async::Job>] the generated job class
         # @api private
         def build_servus_job_class
@@ -174,10 +194,77 @@ module Servus
           klass = Class.new(Servus::Extensions::Async::Job)
           klass.servus_service = self
 
-          module_parent.const_set("#{name.demodulize}Job", klass)
+          publish_job_const(servus_job_const_name, klass)
 
           klass
         end
+
+        # @return [String] the sibling constant the service's job is published under
+        # @api private
+        def servus_job_const_name
+          "#{name.demodulize}Job"
+        end
+
+        # A job with no name lost its constant to the application (see
+        # {#publish_job_const}). ActiveJob serializes a job by its class name, so
+        # enqueueing it would succeed and then fail on the worker at
+        # deserialization — refuse at the call site instead.
+        #
+        # @raise [Errors::JobNameConflictError] when the service's job is unnamed
+        # @return [void]
+        # @api private
+        def refuse_nameless_job!
+          return unless servus_job_class.name.nil?
+
+          raise Errors::JobNameConflictError.for(self, qualified_const_name(servus_job_const_name))
+        end
+
+        # Installs the generated job as a sibling constant, unless the application
+        # owns that name — in which case its class is left alone and the skip is
+        # logged.
+        #
+        # @param const_name [String]
+        # @param klass [Class<Servus::Extensions::Async::Job>]
+        # @return [void]
+        # @api private
+        def publish_job_const(const_name, klass)
+          unless job_const_available?(const_name)
+            return Servus::Support::Logger.log_job_class_conflict(self, qualified_const_name(const_name))
+          end
+
+          # Reclaiming a stale generated job: drop it first so Ruby does not warn
+          # about an already-initialized constant on every reload.
+          module_parent.send(:remove_const, const_name) if module_parent.const_defined?(const_name, false)
+          module_parent.const_set(const_name, klass)
+        end
+
+        # Whether this service may publish its job class as +const_name+.
+        #
+        # Free names are available, and so is a name already holding a generated job —
+        # that is our own constant from a previous definition, which survives a
+        # development reload when the parent namespace is +Object+ and therefore
+        # unmanaged by Zeitwerk.
+        #
+        # A pending autoload is treated as the app's without resolving it: forcing the
+        # load here would run app code in the middle of defining a service.
+        #
+        # @param const_name [String]
+        # @return [Boolean]
+        # @api private
+        def job_const_available?(const_name)
+          return true unless module_parent.const_defined?(const_name, false)
+          return false if module_parent.autoload?(const_name)
+
+          existing = module_parent.const_get(const_name, false)
+          existing.is_a?(Class) && existing <= Servus::Extensions::Async::Job
+        end
+
+        # @param const_name [String]
+        # @return [String] the constant's fully qualified name
+        # @api private
+        def qualified_const_name(const_name)
+          module_parent.equal?(Object) ? const_name : "#{module_parent.name}::#{const_name}"
+        end
       end
     end
   end

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

@@ -22,6 +22,29 @@ module Servus
         #   Services::SendEmail::Service.call_async(user_id: 123)
         #   # => Servus::Extensions::Async::Errors::JobEnqueueError: Failed to enqueue async job
         class JobEnqueueError < AsyncError; end
+
+        # Raised when +call_async+ is invoked on a service whose generated job was
+        # never published because the application already owns the constant.
+        #
+        # The generated job class exists but has no name, and ActiveJob serializes a
+        # job by its class name — enqueueing it would succeed and then fail on the
+        # worker at deserialization, far from the call site. Refusing here keeps the
+        # failure where it was caused.
+        #
+        # @see Servus::Extensions::Async::Call#call_async
+        class JobNameConflictError < AsyncError
+          # @param service [Class] the service whose job constant is taken
+          # @param const_name [String] the constant the application owns
+          # @return [JobNameConflictError]
+          def self.for(service, const_name)
+            new(
+              "Cannot enqueue #{service.name}: its generated job was not published because " \
+              "#{const_name} is already defined by the application. An unnamed job would " \
+              'enqueue but no worker could deserialize it. Rename the service or the ' \
+              "application's #{const_name} to stop the collision."
+            )
+          end
+        end
       end
     end
   end

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

@@ -12,6 +12,7 @@ module Servus
     module Async
       require 'active_support/core_ext/module/introspection' # Module#module_parent
       require 'active_support/core_ext/string/inflections' # String#demodulize
+      require 'active_support/core_ext/class/subclasses' # Class#descendants
 
       require 'servus/extensions/async/errors'
       require 'servus/extensions/async/job'
@@ -21,6 +22,33 @@ module Servus
       #
       # @api private
       module Ext; end
+
+      # Installs async support on {Servus::Base} and backfills job classes for
+      # services that were already defined.
+      #
+      # The backfill exists because {Call#inherited} — which publishes a service's
+      # job constant — only exists once this module is installed, and installation
+      # is deferred to +on_load(:active_job)+. Servus's own railtie force-loads
+      # +app/events/*_event.rb+, and every service named by an +enqueue+ there loads
+      # with it, typically before anything has touched +ActiveJob::Base+. Those
+      # services would otherwise never publish a job constant, and a worker — which
+      # resolves jobs by name and never calls {Call#call_async} — would fail
+      # deserialization with +ActiveJob::UnknownJobClassError+.
+      #
+      # Only services still reachable under their own name are backfilled. An
+      # anonymous service has no constant to publish, and a class whose name no
+      # longer resolves to it — replaced by a reload, or defined under a namespace
+      # that has since gone — has nothing to publish it under either.
+      #
+      # @return [void]
+      # @api private
+      def self.install!
+        Servus::Base.extend(Call)
+
+        Servus::Base.descendants.each do |service|
+          service.servus_job_class if service.name&.safe_constantize.equal?(service)
+        end
+      end
     end
   end
 end

data/lib/servus/railtie.rb

@@ -14,7 +14,7 @@ module Servus
     initializer 'servus.job_async' do
       ActiveSupport.on_load(:active_job) do
         require 'servus/extensions/async/ext'
-        Servus::Base.extend Servus::Extensions::Async::Call
+        Servus::Extensions::Async.install!
       end
     end
 

data/lib/servus/schema.rb

@@ -175,7 +175,7 @@ module Servus
       #   Servus::Schema.ref('core', '$defs', 'amount')
       #   # => { "$ref" => "#/core/$defs/amount" }
       def ref(key, *path)
-        { '$ref' => "#/#{[key, *path].map(&:to_s).join('/')}" }
+        { '$ref' => "#/#{[key, *path].join('/')}" }
       end
 
       # Compiles a schema, replacing every +$ref+ with the fragment it names.

data/lib/servus/support/logger.rb

@@ -104,6 +104,22 @@ module Servus
         logger.warn("Schema fragment #{key.inspect} was already registered with a different value; replacing it.")
       end
 
+      # Logs that a service could not publish its generated job class because the
+      # constant is already taken by the application.
+      #
+      # The application's class is left alone. The service still runs, but its
+      # generated job has no name, so +call_async+ on it cannot be serialized.
+      #
+      # @param service_class [Class<Servus::Base>] The service whose job was not published
+      # @param const_name [String] The constant the application already owns
+      def self.log_job_class_conflict(service_class, const_name)
+        logger.warn(
+          "#{service_class.name} did not publish its generated job as #{const_name} — that constant " \
+          'is already defined by the application. The application class is unchanged; ' \
+          "#{service_class.name}.call_async cannot be enqueued until the service or the job is renamed."
+        )
+      end
+
       # Filters parameters for logging based on the configured filter list.
       #
       # @param params [Hash] The parameters to filter

data/lib/servus/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Sebastian Scholl
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -28,16 +28,22 @@ dependencies:
   name: json-schema
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement