servus 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11fe445ce97bbd8300a08023e80eb1516011657d7412b6f5c9215f6c40aeb12d
-  data.tar.gz: 4cf1448c26b970cea781ccc2e7c21ddf5b8bde6f7703d070b59ea0809d752d1b
+  metadata.gz: 10e4e061222d303e5d694d816afd1d0557eb6c4e7804dd5b454e48cddcdf0797
+  data.tar.gz: b6cdb1fcabe827988e6e8daf44d20d2da2649cf4b252d36ac68dd1f8f14db584
 SHA512:
-  metadata.gz: f294661ff53e5340f52c8de15485c06c16820cb2b90b8d517c8e01322ee54fb0e7beec46f9560b3fe47d4c09b184474ccb5634368c2d902b0ab2c2106407d5bb
-  data.tar.gz: 3772632d087a92a26dcf24268570d1a4c1fd8887df493dd0a4c39b5cf899db8d5ec8e0bd3397738d4d64934f345ae9778eb7fef98e3a7f415d3f166f31005859
+  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/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.
@@ -113,7 +116,7 @@ module Servus
       # @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.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."
@@ -131,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.2'
+  VERSION = '1.2.0'
 end

metadata

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