redis_queued_locks 1.12.0 → 1.13.0

data/lib/redis_queued_locks/config/dsl.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# @api private
+# @since [1.13.0]
+module RedisQueuedLocks::Config::DSL
+  # @api private
+  # @since [1.13.0]
+  module ClassMethods
+    # NOTE:
+    #   1. Style/DefWithParentheses rubocop's cop incorrectly drops `()` from method definition
+    #   and breaks ruby code syntax. So this cop is disabled here;
+    #   2. attr_reader is not used cuz `steep` can't understand it form inside the class where
+    #   the current module is mixed;
+    #
+    # @return [Hash<String,Block>]
+    #
+    # @api private
+    # @since [1.13.0]
+    def config_setters()= @config_setters # rubocop:disable Style/DefWithParentheses
+
+    # NOTE:
+    #   1. Style/DefWithParentheses rubocop's cop incorrectly drops `()` from method definition
+    #   and breaks ruby code syntax. So this cop is disabled here;
+    #   2. attr_reader is not used cuz `steep` can't understand it form inside the class where
+    #   the current module is mixed;
+    #
+    # @return [Hash<String,Block>]
+    #
+    # @api private
+    # @since [1.13.0]
+    def config_validators()= @config_validators # rubocop:disable Style/DefWithParentheses
+
+    # @param config_key [String]
+    # @param validator [Block]
+    # @return [Bool]
+    #
+    # @api private
+    # @since [1.13.0]
+    def validate(config_key, &validator)
+      config_validators[config_key] = validator
+    end
+
+    # @param config_key [String]
+    # @param config_value [Any]
+    # @return [void]
+    #
+    # @api private
+    # @since [1.13.0]
+    def setting(config_key, config_value)
+      config_setters[config_key] = proc do |config|
+        config[config_key] = config_value
+      end
+    end
+  end
+
+  module InstanceMethods
+    # @return [Hash<String,Blcok>]
+    #
+    # @api private
+    # @since [1.13.0]
+    def config_setters
+      self.class.config_setters # steep:ignore
+    end
+
+    # @return [Hash<String,Blcok>]
+    #
+    # @api private
+    # @since [1.13.0]
+    def config_validators
+      self.class.config_validators # steep:ignore
+    end
+  end
+
+  class << self
+    # @param child_klass [Class]
+    # @return [void]
+    #
+    # @api private
+    # @since [1.13.0]
+    def included(child_klass)
+      child_klass.instance_variable_set(
+        :@config_setters,
+        {} #: RedisQueuedLocks::Config::DSL::configSetters
+      )
+      child_klass.instance_variable_set(
+        :@config_validators,
+        {} #: RedisQueuedLocks::Config::DSL::configValidators
+      )
+      child_klass.extend(ClassMethods)
+      child_klass.include(InstanceMethods)
+      super
+    end
+  end
+end

data/lib/redis_queued_locks/config.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+# @api private
+# @since [1.13.0]
+# rubocop:disable Metrics/ClassLength
+class RedisQueuedLocks::Config
+  require_relative 'config/dsl'
+
+  # @api private
+  # @since [1.13.0]
+  include DSL
+
+  setting('retry_count', 3)
+  setting('retry_delay', 200) # NOTE: in milliseconds)
+  setting('retry_jitter', 25) # NOTE: in milliseconds)
+  setting('try_to_lock_timeout', 10) # NOTE: in seconds)
+  setting('default_lock_ttl', 5_000) # NOTE: in milliseconds)
+  setting('default_queue_ttl', 15) # NOTE: in seconds)
+  setting('detailed_acq_timeout_error', false)
+  setting('lock_release_batch_size', 100)
+  setting('key_extraction_batch_size', 500)
+  setting('instrumenter', RedisQueuedLocks::Instrument::VoidNotifier)
+  setting('uniq_identifier', -> { RedisQueuedLocks::Resource.calc_uniq_identity })
+  setting('logger', RedisQueuedLocks::Logging::VoidLogger)
+  setting('log_lock_try', false)
+  setting('dead_request_ttl', 1 * 24 * 60 * 60 * 1000) # NOTE: 1 day in milliseconds)
+  setting('is_timed_by_default', false)
+  setting('default_conflict_strategy', :wait_for_lock)
+  setting('default_access_strategy', :queued)
+  setting('log_sampling_enabled', false)
+  setting('log_sampling_percent', 15)
+  setting('log_sampler', RedisQueuedLocks::Logging::Sampler)
+  setting('instr_sampling_enabled', false)
+  setting('instr_sampling_percent', 15)
+  setting('instr_sampler', RedisQueuedLocks::Instrument::Sampler)
+  setting('swarm.auto_swarm', false)
+  setting('swarm.supervisor.liveness_probing_period', 2) # NOTE: in seconds)
+  setting('swarm.probe_hosts.enabled_for_swarm', true)
+  setting('swarm.probe_hosts.probe_period', 2) # NOTE: in seconds)
+  setting('swarm.probe_hosts.redis_config.sentinel', false)
+  setting('swarm.probe_hosts.redis_config.pooled', false)
+  setting('swarm.probe_hosts.redis_config.config', {})
+  setting('swarm.probe_hosts.redis_config.pool_config', {})
+  setting('swarm.flush_zombies.enabled_for_swarm', true)
+  setting('swarm.flush_zombies.zombie_ttl', 15_000) # NOTE: in milliseconds)
+  setting('swarm.flush_zombies.zombie_lock_scan_size', 500)
+  setting('swarm.flush_zombies.zombie_queue_scan_size', 500)
+  setting('swarm.flush_zombies.zombie_flush_period', 10)
+  setting('swarm.flush_zombies.redis_config.sentinel', false)
+  setting('swarm.flush_zombies.redis_config.pooled', false)
+  setting('swarm.flush_zombies.redis_config.config', {})
+  setting('swarm.flush_zombies.redis_config.pool_config', {})
+
+  validate('swarm.auto_swarm') { |val| val == true || val == false }
+  validate('swarm.supervisor.liveness_probing_period') { |val| val.is_a?(Integer) }
+
+  validate('swarm.probe_hosts.enabled_for_swarm') { |val| val == true || val == false }
+  validate('swarm.probe_hosts.redis_config.sentinel') { |val| val == true || val == false }
+  validate('swarm.probe_hosts.redis_config.pooled') { |val| val == true || val == false }
+  validate('swarm.probe_hosts.redis_config.config') { |val| val.is_a?(Hash) }
+  validate('swarm.probe_hosts.redis_config.pool_config') { |val| val.is_a?(Hash) }
+  validate('swarm.probe_hosts.probe_period') { |val| val.is_a?(Integer) }
+
+  validate('swarm.flush_zombies.enabled_for_swarm') { |val| val == true || val == false }
+  validate('swarm.flush_zombies.redis_config.sentinel') { |val| val == true || val == false }
+  validate('swarm.flush_zombies.redis_config.pooled') { |val| val == true || val == false }
+  validate('swarm.flush_zombies.redis_config.config') { |val| val.is_a?(Hash) }
+  validate('swarm.flush_zombies.redis_config.pool_config') { |val| val.is_a?(Hash) }
+  validate('swarm.flush_zombies.zombie_ttl') { |val| val.is_a?(Integer) }
+  validate('swarm.flush_zombies.zombie_lock_scan_size') { |val| val.is_a?(Integer) }
+  validate('swarm.flush_zombies.zombie_queue_scan_size') { |val| val.is_a?(Integer) }
+  validate('swarm.flush_zombies.zombie_flush_period') { |val| val.is_a?(Integer) }
+
+  validate('retry_count') { |val| val == nil || (val.is_a?(Integer) && val >= 0) }
+  validate('retry_delay') { |val| val.is_a?(Integer) && val >= 0 }
+  validate('retry_jitter') { |val| val.is_a?(Integer) && val >= 0 }
+  validate('try_to_lock_timeout') { |val| val == nil || (val.is_a?(Integer) && val >= 0) }
+  validate('default_lock_tt') { |val| val.is_a?(Integer) }
+  validate('default_queue_ttl') { |val| val.is_a?(Integer) }
+  validate('detailed_acq_timeout_error') { |val| val == true || val == false }
+  validate('lock_release_batch_size') { |val| val.is_a?(Integer) }
+  validate('instrumenter') { |val| RedisQueuedLocks::Instrument.valid_interface?(val) }
+  validate('uniq_identifier') { |val| val.is_a?(Proc) }
+  validate('logger') { |val| RedisQueuedLocks::Logging.valid_interface?(val) }
+  validate('log_lock_try') { |val| val == true || val == false }
+  validate('dead_request_ttl') { |val| val.is_a?(Integer) && val > 0 }
+  validate('is_timed_by_default') { |val| val == true || val == false }
+  validate('log_sampler') { |val| RedisQueuedLocks::Logging.valid_sampler?(val) }
+  validate('log_sampling_enabled') { |val| val == true || val == false }
+  validate('log_sampling_percent') { |val| val.is_a?(Integer) && val >= 0 && val <= 100 }
+  validate('instr_sampling_enabled') { |val| val == true || val == false }
+  validate('instr_sampling_percent') { |val| val.is_a?(Integer) && val >= 0 && val <= 100 }
+  validate('instr_sampler') { |val| RedisQueuedLocks::Instrument.valid_sampler?(val) }
+  validate('default_conflict_strategy') do |val|
+    # rubocop:disable Layout/MultilineOperationIndentation
+    val == :work_through ||
+    val == :extendable_work_through ||
+    val == :wait_for_lock ||
+    val == :dead_locking
+    # rubocop:enable Layout/MultilineOperationIndentation
+  end
+  validate('default_access_strategy') do |val|
+    # rubocop:disable Layout/MultilineOperationIndentation
+    val == :queued ||
+    val == :random
+    # rubocop:enable Layout/MultilineOperationIndentation
+  end
+
+  # @return [Hash<Symbol,Any>]
+  #
+  # @api private
+  # @since [1.13.0]
+  attr_reader :config_state
+
+  # @return [void]
+  #
+  # @api private
+  # @since [1.13.0]
+  def initialize(&configuration)
+    @config_state = {}
+    config_setters.each_value { |setter| setter.call(@config_state) }
+    configure(&configuration)
+  end
+
+  # @param configuration [Block]
+  # @yield [?]
+  # @yieldparam [?]
+  # @return [void]
+  #
+  # @api private
+  # @since [1.13.0]
+  def configure(&configuration)
+    yield(self) if block_given?
+  end
+
+  # @param config_key [String]
+  # @return [Any]
+  #
+  # @raise [RedisQueuedLocks::ConfigNotFoundError]
+  #
+  # @api public
+  # @since [1.13.0]
+  def [](config_key)
+    prevent_key__non_existent(config_key)
+    config_state[config_key]
+  end
+
+  # @param config_key [String]
+  # @param config_value [Any]
+  # @return [void]
+  #
+  # @raise [RedisQueuedLocks::ConfigNotFoundError]
+  # @raise [RedisQueuedLocks::ConfigValidationError]
+  #
+  # @api public
+  # @since [1.13.0]
+  def []=(config_key, config_value)
+    prevent_key__non_existent(config_key)
+    prevent_key__invalid_type(config_key, config_value)
+    config_state[config_key] = config_value
+  end
+
+  # Returns the slice of the config values as a `hash` match the received pattern.
+  # Matched configs will be sliced as a nested config (as a hash object). And config valuess
+  # will be duplicated via `Object#dup`. How it works:
+  #   initial config sate: => {
+  #     'swarm.flush_zombies.redis_config.pooled' => true,
+  #     'swarm.flush_zombies.redis_config.sentinel' => true,
+  #     'swarm.aut_swarm' => false,
+  #     'logger' => Logger.new
+  #   }
+  #   slice with "swarm.flush_zombies.redis_config" pattern: => {
+  #     'pooled' => true,
+  #     'sentinel' => true
+  #   }
+  #
+  # @param config_key_pattern [String]
+  # @return [Hash<String,Any>]
+  #
+  # @api public
+  # @since [1.13.0]
+  def slice(config_key_pattern)
+    key_selector = "#{config_key_pattern}."
+    key_splitter = key_selector.size
+    sliced_config = {} #: Hash[String,untyped]
+
+    config_state.each_pair do |config_key, config_value|
+      next unless config_key.start_with?(key_selector)
+      sliced_config_key = config_key[key_splitter..] #: String
+      sliced_config[sliced_config_key] = config_value.dup
+    end
+
+    sliced_config
+  end
+
+  private
+
+  # @param config_key [String]
+  # @return [void]
+  #
+  # @raise [RedisQueuedLocks::ConfigNotFoundError]
+  #
+  # @api private
+  # @since [1.13.0]
+  def prevent_key__non_existent(config_key)
+    unless config_state.key?(config_key)
+      raise(
+        RedisQueuedLocks::ConfigNotFoundError,
+        "Config with '#{config_key}' key does not exist."
+      )
+    end
+  end
+
+  # @param config_key [String]
+  # @param config_value [Any]
+  # @return [void]
+  #
+  # @raise [RedisQueuedLocks::ConfigValidationError]
+  #
+  # @api private
+  # @sicne [1.13.0]
+  def prevent_key__invalid_type(config_key, config_value)
+    unless config_validators[config_key].call(config_value)
+      raise(
+        RedisQueuedLocks::ConfigValidationError,
+        "Trying to assing an invalid value to the '#{config_key}' config key."
+      )
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/data.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+# @api private
+# @since 0.0.18
 class RedisQueuedLocks::Data < Hash
 end

data/lib/redis_queued_locks/errors.rb

@@ -1,47 +1,63 @@
 # frozen_string_literal: true
 
+# NOTE:
+#   the one-line definition style (like "Error = Class.new(::StandardError)")
+#   is not used cuz that style can not be correctly defined via RBS types: we can not
+#   identify the superclass of our class for a constant;
 module RedisQueuedLocks
   # @api public
   # @since 1.0.0
-  Error = Class.new(::StandardError)
+  class Error < ::StandardError; end
 
   # @api public
   # @since 1.0.0
-  ArgumentError = Class.new(::ArgumentError)
+  class ArgumentError < ::ArgumentError; end
 
   # @api public
   # @since 1.0.0
-  LockAlreadyObtainedError = Class.new(Error)
+  class LockAlreadyObtainedError < Error; end
 
   # @api private
   # @since 1.11.0
-  LockAcquiermentIntermediateTimeoutError = Class.new(::Timeout::Error)
+  class LockAcquirementIntermediateTimeoutError < ::Timeout::Error; end
 
   # @api public
   # @since 1.0.0
-  LockAcquiermentTimeoutError = Class.new(Error)
+  class LockAcquirementTimeoutError < Error; end
 
   # @api public
   # @since 1.0.0
-  LockAcquiermentRetryLimitError = Class.new(Error)
+  class LockAcquirementRetryLimitError < Error; end
 
   # @api private
   # @since 1.12.0
-  TimedLockIntermediateTimeoutError = Class.new(::Timeout::Error)
+  class TimedLockIntermediateTimeoutError < ::Timeout::Error; end
 
   # @api pulic
   # @since 1.0.0
-  TimedLockTimeoutError = Class.new(Error)
+  class TimedLockTimeoutError < Error; end
 
   # @api public
   # @since 1.3.0
-  ConflictLockObtainError = Class.new(Error)
+  class ConflictLockObtainError < Error; end
 
   # @api public
   # @since 1.9.0
-  SwarmError = Class.new(Error)
+  class SwarmError < Error; end
 
   # @api public
   # @since 1.9.0
-  SwarmArgumentError = Class.new(ArgumentError)
+  class SwarmArgumentError < ArgumentError; end
+
+  # @api public
+  # @since [1.13.0]
+  class ConfigError < Error; end
+
+  # @api public
+  # @since [1.13.0]
+  class ConfigNotFoundError < ConfigError; end
+
+  # @api pub;ic
+  # @since [1.13.0]
+  class ConfigValidationError < ConfigError; end
 end

data/lib/redis_queued_locks/instrument.rb

@@ -36,6 +36,7 @@ module RedisQueuedLocks::Instrument
     def valid_sampler?(sampler)
       return false unless sampler.respond_to?(:sampling_happened?)
 
+      # @type var m_obj: Method
       m_obj = sampler.method(:sampling_happened?)
       m_sig = m_obj.parameters
 
@@ -45,12 +46,17 @@ module RedisQueuedLocks::Instrument
       #     => [[:opt, :sampling_percent]]
       #     => [[:req, :sampling_percent], [:block, :block]]
       #     => [[:opt, :sampling_percent], [:block, :block]]
-      if m_sig.size == 1
+      case m_sig.size
+      when 1
+        # => [[:req, :sampling_percent]]
+        # => [[:opt, :sampling_percent]]
         prm = m_sig[0][0]
         prm == :req || prm == :opt
-      elsif m_sig.size == 2
+      when 2
+        # => [[:req, :sampling_percent], [:block, :block]]
+        # => [[:opt, :sampling_percent], [:block, :block]]
         f_prm = m_sig[0][0]
-        s_prm = m_sign[1][0]
+        s_prm = m_sig[1][0]
 
         # rubocop:disable Layout/MultilineOperationIndentation
         f_prm == :req && s_prm == :block ||
@@ -69,13 +75,14 @@ module RedisQueuedLocks::Instrument
     def valid_interface?(instrumenter)
       if instrumenter == RedisQueuedLocks::Instrument::ActiveSupport
         # NOTE: active_support should be required in your app
-        defined?(::ActiveSupport::Notifications)
+        !!defined?(::ActiveSupport::Notifications)
       elsif instrumenter.respond_to?(:notify)
         # NOTE: the method signature should be (event, payload). Supported variants:
         #   => [[:req, :event], [:req, :payload]]
         #   => [[:req, :event], [:opt, :payload]]
         #   => [[:opt, :event], [:opt, :payload]]
 
+        # @type var m_obj: Method
         m_obj = instrumenter.method(:notify)
         m_sig = m_obj.parameters
 

data/lib/redis_queued_locks/logging/void_logger.rb

@@ -4,38 +4,75 @@
 # @since 1.0.0
 module RedisQueuedLocks::Logging::VoidLogger
   class << self
+    # @param progname [Any]
+    # @parma block [Block]
+    # @return [void]
+    #
     # @api public
     # @since 1.0.0
     def warn(progname = nil, &block); end
 
+    # @param progname [Any]
+    # @parma block [Block]
+    # @return [void]
+    #
     # @api public
     # @since 1.0.0
     def unknown(progname = nil, &block); end
 
+    # @param progname [Any]
+    # @parma block [Block]
+    # @return [void]
+    #
     # @api public
     # @since 1.0.0
     def log(progname = nil, &block); end
 
+    # @param progname [Any]
+    # @parma block [Block]
+    # @return [void]
+    #
     # @api public
     # @since 1.0.0
     def info(progname = nil, &block); end
 
+    # @param progname [Any]
+    # @parma block [Block]
+    # @return [void]
+    #
     # @api public
     # @since 1.0.0
     def error(progname = nil, &block); end
 
+    # @param progname [Any]
+    # @parma block [Block]
+    # @return [void]
+    #
     # @api public
     # @since 1.0.0
     def fatal(progname = nil, &block); end
 
+    # @param progname [Any]
+    # @parma block [Block]
+    # @return [void]
+    #
     # @api public
     # @since 1.0.0
     def debug(progname = nil, &block); end
 
+    # @param severity [Any]
+    # @param message [Any]
+    # @param progname [Any]
+    # @param block [Block]
+    # @return [void]
+    #
     # @api public
     # @since 1.0.0
-    def add(*, &block); end
+    def add(severity = nil, message = nil, progname = nil, &block); end
 
+    # @param message [Any]
+    # @retorun [void]
+    #
     # @api public
     # @since 1.0.0
     def <<(message); end

data/lib/redis_queued_locks/logging.rb

@@ -49,7 +49,7 @@ module RedisQueuedLocks::Logging
         prm == :req || prm == :opt
       elsif m_sig.size == 2
         f_prm = m_sig[0][0]
-        s_prm = m_sign[1][0]
+        s_prm = m_sig[1][0]
 
         # rubocop:disable Layout/MultilineOperationIndentation
         f_prm == :req && s_prm == :block ||
@@ -71,9 +71,14 @@ module RedisQueuedLocks::Logging
 
       # NOTE:
       #   - convinient/conventional way to support the popular `semantic_logger` library
-      #   - see https://logger.rocketjob.io/
-      #   - see https://github.com/reidmorrison/semantic_logger
+      #     - see https://logger.rocketjob.io/
+      #     - see https://github.com/reidmorrison/semantic_logger
+      #   - convinient/conventional way to support the popular `broadcast` RubyOnRails's logger;
+      #     - see https://api.rubyonrails.org/classes/ActiveSupport/BroadcastLogger.html
+      # rubocop:disable Layout/LineLength
       return true if defined?(::SemanticLogger::Logger) && logger.is_a?(::SemanticLogger::Logger)
+      return true if defined?(::ActiveSupport::BroadcastLogger) && logger.is_a?(::ActiveSupport::BroadcastLogger)
+      # rubocop:enable Layout/LineLength
 
       # NOTE: should provide `#debug` method.
       return false unless logger.respond_to?(:debug)
@@ -87,11 +92,14 @@ module RedisQueuedLocks::Logging
       #     => [[:req, :progname]]
       #     => [[:rest], [:block, :block]]
       #     => [[:rest]]
+      #     => ((...) method signature): [[:rest, :*], [:keyrest, :**], [:block, :&]]
 
+      # @type var m_obj: Method
       m_obj = logger.method(:debug)
       m_sig = m_obj.parameters
 
-      if m_sig.size == 2
+      case m_sig.size
+      when 2
         # => [[:opt, :progname], [:block, :block]]
         # => [[:req, :progname], [:block, :block]]
         # => [[:rest], [:block, :block]]
@@ -103,13 +111,20 @@ module RedisQueuedLocks::Logging
         f_prm == :req && s_prm == :block ||
         f_prm == :rest && s_prm == :block
         # rubocop:enable Layout/MultilineOperationIndentation
-      elsif m_sig.size == 1
+      when 1
         # => [[:opt, :progname]]
         # => [[:req, :progname]]
         # => [[:rest]]
         prm = m_sig[0][0]
 
         prm == :opt || prm == :req || prm == :rest
+      when 3
+        # => [[:rest, :*], [:keyrest, :**], [:block, :&]]
+        f_prm = m_sig[0][0]
+        s_prm = m_sig[1][0]
+        t_prm = m_sig[2][0]
+
+        f_prm == :rest && s_prm == :keyrest && t_prm == :block
       else
         false
       end