servus 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8da8eeaf0d61216b5df16e50dbb6a7cf0fd36bc8a9a2c5d59f233a5ba6d399a8
-  data.tar.gz: ba37edced59e89519122e27dbee45334edadd1b35cda36b03f7966fe3452a0c9
+  metadata.gz: 10e4e061222d303e5d694d816afd1d0557eb6c4e7804dd5b454e48cddcdf0797
+  data.tar.gz: b6cdb1fcabe827988e6e8daf44d20d2da2649cf4b252d36ac68dd1f8f14db584
 SHA512:
-  metadata.gz: 5b7969e87edf801cc7c4e5e452db45a4bedb90f11b8bafb24e4750843a9babf80ca0b6d00d2a8abad6ce046192165cf17b50fe405b952d8324cdc3d04b131aed
-  data.tar.gz: 5485a32d587becac5ad967c3e552396c1b6994263dbe7a1c977e33d0a290c391dd748f02a3455a2e45307658932a1b66b51b9448ac6d8bcc92b96c0ce243ae55
+  metadata.gz: 61ab96b3ed1da09eb768ced10cbacc5cb6f4e8a8f4aead7ed57aa6f49dbdd016513dee1f1f2402a7a21504913b9ae5c0ef23298301fc398c3dcb6f224d2dcedc
+  data.tar.gz: 011eaaabc88c46604d60c9f82727e43f6152521a7f1cb64b483a1b912eb0a047eaf8607eab31b51f31a92df90333c4130af845f10a8d7263aa3bcfd3fda85f60

data/lib/servus/base.rb

@@ -115,6 +115,40 @@ module Servus
     Response = Servus::Support::Response
     Validator = Servus::Support::Validator
 
+    class << self
+      # Assigns the logger Servus writes this service's call, outcome, and
+      # error lines through. It covers this class and every service below it.
+      #
+      # Build the logger from {Servus.logger} so it keeps the appenders and
+      # formatting the app configured, rather than replacing them.
+      #
+      # Assigning +nil+ returns the class to the logger it inherits.
+      #
+      # @param logger [::Logger, nil]
+      #
+      # @example Giving an engine's services their own logger
+      #   class Treasury::ApplicationService < Servus::Base
+      #     self.logger = SemanticLogger[Treasury]
+      #   end
+      attr_writer :logger
+
+      # The logger for this service class: its own, else the one it inherits,
+      # else {Servus.logger}.
+      #
+      # @return [::Logger]
+      def logger
+        return @logger if @logger
+
+        superclass <= Servus::Base ? superclass.logger : Servus.logger
+      end
+    end
+
+    # @return [::Logger] the logger of this service's class
+    # @see .logger
+    def logger
+      self.class.logger
+    end
+
     # Creates a successful response with the provided data.
     #
     # Use this method to return successful results from your service's call method.
@@ -182,6 +216,46 @@ module Servus
       Response.new(false, data, error)
     end
 
+    # Ends the service with a failure response, from anywhere inside +call+.
+    #
+    # Builds the same response as {#failure} and returns it from the service as
+    # if +call+ had returned it, so it is logged, validated against the failure
+    # schema, and emits events exactly as a returned failure does. Unlike
+    # {#failure}, it does not need to be the value of +call+: a private check
+    # method can end the service itself, which keeps +call+ a list of steps.
+    #
+    # It is not an exception: +rescue+ does not see it, and +ensure+ still runs.
+    # A failure ends only the service that raised it — a nested service called
+    # from +call+ hands its failure back as a response, as it always has.
+    #
+    # @param message [String, nil] custom error message (uses error type's default if nil)
+    # @param data [Object, nil] optional structured data to attach to the failure response
+    # @param type [Class] error class to instantiate (must inherit from ServiceError)
+    # @return [void] never returns
+    #
+    # @example Ending the service from a check
+    #   def call
+    #     account_open!
+    #     success(account.withdraw!(amount))
+    #   end
+    #
+    #   private
+    #
+    #   def account_open!
+    #     return if account.open?
+    #
+    #     failure!("Account is closed", type: Servus::Support::Errors::UnprocessableEntityError)
+    #   end
+    #
+    # @note Leaving an ActiveRecord +transaction+ (or +with_lock+) block this way
+    #   commits it, as any non-exception exit does. Run checks before writing, or
+    #   raise to roll back.
+    # @see #failure
+    # @see #error!
+    def failure!(message = nil, data: nil, type: Servus::Support::Errors::ServiceError)
+      throw :service_failure, failure(message, data:, type:)
+    end
+
     # Logs an error and raises an exception, halting service execution.
     #
     # Use this method when you need to immediately halt execution with an exception
@@ -254,7 +328,7 @@ module Servus
 
         # Wrap execution in catch block to handle guard failures
         result = catch(:guard_failure) do
-          benchmark(**args) { instance.send(:call) }
+          benchmark(**args) { catch(:service_failure) { instance.send(:call) } }
         end
 
         if result.is_a?(Servus::Support::Errors::GuardError)

data/lib/servus/config.rb

@@ -76,6 +76,20 @@ module Servus
     # @return [Boolean] true to require payload schemas, false to allow schema-less events
     attr_accessor :require_event_payload_schema
 
+    # The logger Servus writes through.
+    #
+    # Left +nil+ (the default), Servus resolves one itself: `Rails.logger`
+    # when Rails is loaded, otherwise a `$stdout` logger. Read the resolved
+    # logger through {Servus.logger}.
+    #
+    # @return [::Logger, nil] the configured logger, or nil when none is set
+    #
+    # @example
+    #   Servus.configure do |config|
+    #     config.logger = SemanticLogger[Servus]
+    #   end
+    attr_accessor :logger
+
     # The ordered list of routers that resolve invocations for events.
     #
     # The Bus iterates routers in order, collects invocations, deduplicates
@@ -181,6 +195,21 @@ module Servus
     @config ||= Config.new
   end
 
+  # The logger Servus writes through.
+  #
+  # Build a service's own logger from this one rather than replacing it, so
+  # the app's appenders and formatting are kept.
+  #
+  # @return [::Logger]
+  #
+  # @example A per-service logger that adds a tag (SemanticLogger)
+  #   class Treasury::ApplicationService < Servus::Base
+  #     self.logger = Servus.logger.tagged(engine: 'treasury')
+  #   end
+  def self.logger
+    Servus::Support::Logger.logger
+  end
+
   # Yields the configuration for modification.
   #
   # @yieldparam config [Servus::Config] the configuration object to modify

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/support/logger.rb

@@ -6,15 +6,16 @@ module Servus
   module Support
     # Logger class for logging service calls and results
     class Logger
-      # Returns the logger instance depending on the environment
+      # The logger Servus writes through: the one set in {Servus::Config#logger},
+      # else `Rails.logger`, else a `$stdout` logger. Resolved on every read, so
+      # Servus follows Rails if the application swaps its logger after boot.
       #
-      # @return [Logger] The logger instance
+      # Lines about a service go to that service's {Servus::Base.logger} instead.
+      #
+      # @return [::Logger] The logger instance
+      # @see Servus.logger
       def self.logger
-        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-          Rails.logger
-        else
-          @logger ||= ::Logger.new($stdout)
-        end
+        Servus.config.logger || rails_logger || stdout_logger
       end
 
       # Logs a call to a service.
@@ -27,7 +28,7 @@ module Servus
       # @param args [Hash] The arguments passed to the service
       def self.log_call(service_class, args)
         rendered = log_parameters(args)
-        logger.info("Calling #{service_class.name} with args: #{rendered.inspect}")
+        service_class.logger.info("Calling #{service_class.name} with args: #{rendered.inspect}")
       end
 
       # Logs a result from a service
@@ -48,7 +49,7 @@ module Servus
       # @param service_class [Class] The service class
       # @param duration [Float] The duration of the service call
       def self.log_success(service_class, duration)
-        logger.info("#{service_class.name} succeeded in #{duration.round(3)}s")
+        service_class.logger.info("#{service_class.name} succeeded in #{duration.round(3)}s")
       end
 
       # Logs a failed result from a service
@@ -57,7 +58,7 @@ module Servus
       # @param error [Servus::Support::Errors::ServiceError] The error from the service
       # @param duration [Float] The duration of the service call
       def self.log_failure(service_class, error, duration)
-        logger.warn("#{service_class.name} failed in #{duration.round(3)}s with error: #{error}")
+        service_class.logger.warn("#{service_class.name} failed in #{duration.round(3)}s with error: #{error}")
       end
 
       # Logs a guard failure from a service
@@ -65,7 +66,7 @@ module Servus
       # @param service_class [Class] The service class
       # @param error [Servus::Support::Errors::GuardError] The guard error
       def self.log_guard_failure(service_class, error)
-        logger.warn("#{service_class.name} guard failed: #{error.message}")
+        service_class.logger.warn("#{service_class.name} guard failed: #{error.message}")
       end
 
       # Logs an event emission with correlation ID and duration.
@@ -83,7 +84,7 @@ module Servus
       # @param service_class [Class] The service class
       # @param error [Servus::Support::Errors::ValidationError] The validation error
       def self.log_validation_error(service_class, error)
-        logger.error("#{service_class.name} validation error: #{error.message}")
+        service_class.logger.error("#{service_class.name} validation error: #{error.message}")
       end
 
       # Logs an uncaught exception from a service
@@ -91,7 +92,9 @@ module Servus
       # @param service_class [Class] The service class
       # @param exception [Exception] The uncaught exception
       def self.log_exception(service_class, exception)
-        logger.error("#{service_class.name} uncaught exception: #{exception.class} - #{exception.message}")
+        service_class.logger.error(
+          "#{service_class.name} uncaught exception: #{exception.class} - #{exception.message}"
+        )
       end
 
       # Logs that a registered schema fragment was replaced with a different value.
@@ -104,6 +107,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)
+        service_class.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
@@ -115,6 +134,18 @@ module Servus
           Servus.config.parameter_filter.filter(params)
         end
       end
+
+      # @return [::Logger, nil] Rails' logger, when Rails is loaded and has one
+      def self.rails_logger
+        Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+      private_class_method :rails_logger
+
+      # @return [::Logger] the fallback logger, built once
+      def self.stdout_logger
+        @stdout_logger ||= ::Logger.new($stdout)
+      end
+      private_class_method :stdout_logger
     end
   end
 end

data/lib/servus/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Sebastian Scholl
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport