redis_queued_locks 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 612f9339ffba6231bcfe2277af85e2225346f6166eb5bb77da0f507beaeae888
+  data.tar.gz: 35229b1d26a17a9c46e39e565d11ec416ca0e173f57360765c064327ffa6390a
+SHA512:
+  metadata.gz: 1fdb43047ee4b3ac72d28a244ddc9cb4d6b363ff3aa3852b3cc27cbb77ab0a159ef1a45e7eb13f4e4407449fc7b7383e1aac1775f5f739e6ae2e2fcacc5ced46
+  data.tar.gz: 2fbf7fb572005090140ccc9a972e4d84d5be0b1a9a2154fc37c1b04f2dcf44abb06ec6e530c1fa36be0f7ddb3795615f6d7626a224a9d3f3fe913cbf3362734f

data/.rspec

@@ -0,0 +1,3 @@
+--format progress
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,35 @@
+inherit_gem:
+  armitage-rubocop:
+    - lib/rubocop.general.yml
+    - lib/rubocop.rake.yml
+    - lib/rubocop.rspec.yml
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Include:
+    - lib/**/*.rb
+    - spec/**/*.rb
+    - Gemfile
+    - Rakefile
+    - redis_queued_locks.gemspec
+    - bin/console
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Lint/EmptyBlock:
+  Exclude:
+    - spec/**/*.rb
+
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: Gemfile
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.0.0] - 2024-02-25
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at iamdaiver@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Rustam Ibragimov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,3 @@
+# RedisQueuedLocks
+
+Distributed lock implementation with "lock acquisition queue" capabilities based on the Redis Database.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/redis_queued_locks/acquier/delay.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::Delay
+  # @param retry_delay [Integer] In milliseconds
+  # @param retry_jitter [Integer] In milliseconds
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def delay_execution(retry_delay, retry_jitter)
+    delay = (retry_delay + rand(retry_jitter)) / 1_000
+    sleep(delay)
+  end
+end

data/lib/redis_queued_locks/acquier/expire.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::Expire
+  # @param redis [RedisClient]
+  # @param lock_key [String]
+  # @param block [Block]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def yield_with_expire(redis, lock_key, &block)
+    yield if block_given?
+  ensure
+    redis.call('EXPIRE', lock_key, '0')
+  end
+end

data/lib/redis_queued_locks/acquier/release.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::Release
+  # Realease the lock: clear the lock queue and expire the lock.
+  #
+  # @param redis [RedisClient]
+  # @param lock_key [String]
+  # @param lock_key_queue [String]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def fully_release_lock(redis, lock_key, lock_key_queue)
+    redis.multi do |transact|
+      transact.call('ZREMRANGEBYSCORE', lock_key_queue, '-inf', '+inf')
+      transact.call('EXPIRE', lock_key, '0')
+    end
+  end
+
+  # Release all locks: clear all lock queus and expire all locks.
+  #
+  # @param redis [RedisClient]
+  # @param batch_size [Integer]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def fully_release_all_locks(redis, batch_size)
+    # Step A: release all queus and their related locks
+    redis.scan('MATCH', RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN) do |lock_queue|
+      redis.pipelined do |pipeline|
+        pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
+        pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue))
+      end
+    end
+
+    # Step B: release all locks
+    redis.pipelined do |pipeline|
+      redis.scan('MATCH', RedisQueuedLocks::Resource::LOCK_PATTERN) do |lock_key|
+        pipeline.call('EXPIRE', lock_key, '0')
+      end
+    end
+  end
+end

data/lib/redis_queued_locks/acquier/try.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::Try
+  # @param redis [RedisClient]
+  # @param lock_key [String]
+  # @param lock_key_queue [String]
+  # @param acquier_id [String]
+  # @param acquier_position [Numeric]
+  # @param ttl [Integer]
+  # @param queue_ttl [Integer]
+  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol|Hash<Symbol,Any> }
+  #
+  # @api private
+  # @since 0.1.0
+  # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
+  def try_to_lock(redis, lock_key, lock_key_queue, acquier_id, acquier_position, ttl, queue_ttl)
+    # Step X: intermediate invocation results
+    inter_result = nil
+    timestamp = nil
+
+    # Step 0: watch the lock key changes (and discard acquirement if lock is already acquired)
+    result = redis.multi(watch: [lock_key]) do |transact|
+      # Step 1: add an acquier to the lock acquirement queue
+      res = redis.call('ZADD', lock_key_queue, 'NX', acquier_position, acquier_id)
+
+      RedisQueuedLocks.debug(
+        "Step №1: добавление в очередь (#{acquier_id}). [ZADD to the queue: #{res}]"
+      )
+
+      # Step 2.1: drop expired acquiers from the lock queue
+      res = redis.call(
+        'ZREMRANGEBYSCORE',
+        lock_key_queue,
+        '-inf',
+        RedisQueuedLocks::Resource.acquier_dead_score(queue_ttl)
+      )
+
+      RedisQueuedLocks.debug(
+        "Step №2: дропаем из очереди просроченных ожидающих. [ZREMRANGE: #{res}]"
+      )
+
+      # Step 3: get the actual acquier waiting in the queue
+      waiting_acquier = Array(redis.call('ZRANGE', lock_key_queue, '0', '0')).first
+
+      RedisQueuedLocks.debug(
+        "Step №3: какой процесс в очереди сейчас ждет. " \
+        "[ZRANGE <следующий процесс>: #{waiting_acquier} :: <текущий процесс>: #{acquier_id}]"
+      )
+
+      # Step 4: check the actual acquier: is it ours? are we aready to lock?
+      unless waiting_acquier == acquier_id
+        # Step ROLLBACK 1.1: our time hasn't come yet. retry!
+
+        RedisQueuedLocks.debug(
+          "Step ROLLBACK №1: не одинаковые ключи. выходим. " \
+          "[Ждет: #{waiting_acquier}. А нужен: #{acquier_id}]"
+        )
+
+        inter_result = :acquier_is_not_first_in_queue
+      else
+        # NOTE: our time has come! let's try to acquire the lock!
+
+        # Step 5: check if the our lock is already acquired
+        locked_by_acquier = redis.call('HGET', lock_key, 'acq_id')
+
+        RedisQueuedLocks.debug(
+          "Ste №5: Ищем требуемый лок. " \
+          "[HGET<#{lock_key}>: " \
+          "#{(locked_by_acquier == nil) ? 'не занят' : "занят процессом <#{locked_by_acquier}>"}"
+        )
+
+        if locked_by_acquier
+          # Step ROLLBACK 2: required lock is stil acquired. retry!
+
+          RedisQueuedLocks.debug(
+            "Step ROLLBACK №2: Ключ уже занят. Ничего не делаем. " \
+            "[Занят процессом: #{locked_by_acquier}]"
+          )
+
+          inter_result = :lock_is_still_acquired
+        else
+          # NOTE: required lock is free and ready to be acquired! acquire!
+
+          # Step 6.1: remove our acquier from waiting queue
+          transact.call('ZPOPMIN', lock_key_queue, '1')
+
+          RedisQueuedLocks.debug(
+            'Step №4: Забираем наш текущий процесс из очереди. [ZPOPMIN]'
+          )
+
+          RedisQueuedLocks.debug(
+            "===> <FINAL> Step №6: закрепляем лок за процессом [HSET<#{lock_key}>: #{acquier_id}]"
+          )
+
+          # Step 6.2: acquire a lock and store an info about the acquier
+          transact.call('HSET', lock_key, 'acq_id', acquier_id, 'ts', (timestamp = Time.now.to_i))
+
+          # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
+          transact.call('PEXPIRE', lock_key, ttl) # NOTE: in seconds
+        end
+      end
+    end
+
+    # Step 7: Analyze the aquirement attempt:
+    case
+    when inter_result == :lock_is_still_acquired || inter_result == :acquier_is_not_first_in_queue
+      # Step 7.a: lock is still acquired by another process => failed to acquire
+      { ok: false, result: inter_result }
+    when result == nil || (result.is_a?(::Array) && result.empty?)
+      # Step 7.b: lock is already acquired durign the acquire race => failed to acquire
+      { ok: false, result: :lock_is_acquired_during_acquire_race }
+    when result.is_a?(::Array) && result.size == 3 # NOTE: 3 is a count of lock commands
+      # TODO:
+      #   => (!) analyze the command result and do actions with the depending on it;
+      #   => (*) at this moment we accept that all comamnds are completed successfully;
+      #   => (!) need to analyze:
+      #   1. zpopmin should return our process (array with <acq_id> and <score>)
+      #   2. hset should return 2 (lock key is added to the redis db with 2 fields)
+      #   3. pexpire should return 1 (expiration time is successfully applied)
+
+      # Step 7.c: locked! :) let's go! => successfully acquired
+      { ok: true, result: { lock_key: lock_key, acq_id: acquier_id, ts: timestamp, ttl: ttl } }
+    else
+      # Ste 7.d: unknown behaviour :thinking:
+      { ok: false, result: :unknown }
+    end
+  end
+  # rubocop:enable Metrics/MethodLength, Metrics/PerceivedComplexity
+
+  # @param redis [RedisClient]
+  # @param lock_key_queue [String]
+  # @param acquier_id [String]
+  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+  #
+  # @api private
+  # @since 0.1.0
+  def dequeue_from_lock_queue(redis, lock_key_queue, acquier_id)
+    result = redis.call('ZREM', lock_key_queue, acquier_id)
+
+    RedisQueuedLocks.debug(
+      "Step ~ [СМЕРТЬ ПРОЦЕССА]: [#{acquier_id} :: #{lock_key_queue}] РЕЗУЛЬТАТ: #{result}"
+    )
+
+    { ok: true, result: result }
+  end
+end

data/lib/redis_queued_locks/acquier.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier
+  require_relative 'acquier/try'
+  require_relative 'acquier/delay'
+  require_relative 'acquier/expire'
+  require_relative 'acquier/release'
+
+  # @since 0.1.0
+  extend Try
+  # @since 0.1.0
+  extend Delay
+  # @since 0.1.0
+  extend Expire
+  # @since 0.1.0
+  extend Release
+
+  # @return [Integer]
+  #   Redis expiration deviation in milliseconds:
+  #   -> 1 millisecond: for Redis's deviation;
+  #   -> 1 millisecond: for RubyVM's processing deviation;
+  #
+  # @api private
+  # @since 0.1.0
+  REDIS_EXPIRATION_DEVIATION = 2 # NOTE: milliseconds
+
+  class << self
+    # @param redis [RedisClient]
+    #   Redis connection client.
+    # @param lock_name [String]
+    #   Lock name to be acquier.
+    # @option process_id [Integer,String]
+    #   The process that want to acquire the lock.
+    # @option thread_id [Integer,String]
+    #   The process's thread that want to acquire the lock.
+    # @option ttl [Integer]
+    #   Lock's time to live (in milliseconds).
+    # @option queue_ttl [Integer]
+    #   ?
+    # @option timeout [Integer]
+    #   Time period whe should try to acquire the lock (in seconds).
+    # @option retry_count [Integer]
+    #   How many times we should try to acquire a lock.
+    # @option retry_delay [Integer]
+    #   A time-interval between the each retry (in milliseconds).
+    # @option retry_jitter [Integer]
+    #   Time-shift range for retry-delay (in milliseconds).
+    # @param [Block]
+    #   A block of code that should be executed after the successfully acquired lock.
+    # @return [Hash<Symbol,Any>]
+    #   Format: { ok: true/false, result: Any }
+    #
+    # @api private
+    # @since 0.1.0
+    # rubocop:disable Metrics/MethodLength
+    def acquire_lock!(
+      redis,
+      lock_name,
+      process_id:,
+      thread_id:,
+      ttl:,
+      queue_ttl:,
+      timeout:,
+      retry_count:,
+      retry_delay:,
+      retry_jitter:,
+      &block
+    )
+      # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
+      acquier_id = RedisQueuedLocks::Resource.acquier_identifier(process_id, thread_id)
+      lock_ttl = ttl + REDIS_EXPIRATION_DEVIATION
+      lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+      lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+      acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
+
+      # Step X: intermediate result observer
+      acq_process = { lock_info: {}, should_try: true, tries: 0, acquired: false, result: nil }
+      acq_dequeue = -> { dequeue_from_lock_queue(redis, lock_key_queue, acquier_id) }
+
+      # Step 2: try to lock with timeout
+      with_timeout(timeout, lock_key, on_timeout: acq_dequeue) do
+        # Step 2.1: caclically try to obtain the lock
+        while acq_process[:should_try]
+          try_to_lock(
+            redis,
+            lock_key,
+            lock_key_queue,
+            acquier_id,
+            acquier_position,
+            lock_ttl,
+            queue_ttl
+          ) => { ok:, result: }
+
+          # Step X: save the intermediate results to the result observer
+          acq_process[:result] = result
+
+          # Step 2.1: analyze an acquirement attempt
+          if ok
+            # Step 2.1.a: successfully acquired => build the result
+            acq_process[:lock_info] = result
+            acq_process[:acquired] = true
+            acq_process[:should_try] = false
+          else
+            # Step 2.1.b: failed acquirement => retry
+            acq_process[:tries] += 1
+
+            if acq_process[:tries] >= retry_count
+              # NOTE: reached the retry limit => quit from the loop
+              acq_process[:should_try] = false
+              # NOTE: reached the retry limit => dequeue from the lock queue
+              acq_dequeue.call
+            else
+              # NOTE:
+              #   delay the exceution in order to prevent chaotic attempts
+              #   and to allow other processes and threads to obtain the lock too.
+              delay_execution(retry_delay, retry_jitter)
+            end
+          end
+        end
+      end
+
+      # Step 3: analyze acquirement result
+      if acq_process[:acquired]
+        # Step 3.a: acquired successfully => run logic or return the result of acquirement
+        if block_given?
+          yield_with_expire(redis, lock_key, &block)
+        else
+          { ok: true, result: acq_process[:lock_info] }
+        end
+      else
+        # Step 3.b: lock is not acquired:
+        #   => drop itslef from the queue and return the reason of the failed acquirement
+        { ok: false, result: acq_process[:result] }
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # Release the concrete lock:
+    # - 1. clear lock queue: al; related processes released
+    #      from the lock aquierment and should retry;
+    # - 2. delete the lock: drop lock key from Redis;
+    # It is safe because the lock obtain logic is transactional and
+    # watches the original lock for changes.
+    #
+    # @param redis [RedisClient] Redis connection client.
+    # @param lock_name [String] The lock name that should be released.
+    # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+    #
+    # @api private
+    # @since 0.1.0
+    def release_lock!(redis, lock_name)
+      lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+      lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+
+      result = fully_release_lock(redis, lock_key, lock_key_queue)
+      { ok: true, result: result }
+    end
+
+    # Release all locks:
+    # - 1. clear all lock queus: drop them all from Redis database by the lock queue pattern;
+    # - 2. delete all locks: drop lock keys from Redis by the lock key pattern;
+    #
+    # @param redis [RedisClient] Redis connection client.
+    # @param batch_size [Integer] The number of lock keys that should be released in a time.
+    # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+    #
+    # @api private
+    # @since 0.1.0
+    def release_all_locks!(redis, batch_size)
+      result = fully_release_all_locks(redis, batch_size)
+      { ok: true, result: result }
+    end
+
+    private
+
+    # @param timeout [Integer] Time period after which the logic will fail with timeout error.
+    # @param lock_key [String] Lock name.
+    # @option on_timeout [Proc,NilClass] Callback invoked on Timeout::Error.
+    # @return [Any]
+    #
+    # @api private
+    # @since 0.1.0
+    def with_timeout(timeout, lock_key, on_timeout: nil, &block)
+      ::Timeout.timeout(timeout, &block)
+    rescue ::Timeout::Error
+      on_timeout.call unless on_timeout == nil
+      raise(RedisQueuedLocks::LockAcquiermentTimeoutError, <<~ERROR_MESSAGE.strip)
+        Failed to acquire the lock "#{lock_key}" for the given timeout (#{timeout} seconds).
+      ERROR_MESSAGE
+    end
+  end
+end

data/lib/redis_queued_locks/client.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 0.1.0
+class RedisQueuedLocks::Client
+  # @since 0.1.0
+  include Qonfig::Configurable
+
+  configuration do
+    setting :retry_count, 3
+    setting :retry_delay, 200 # NOTE: milliseconds
+    setting :retry_jitter, 50 # NOTE: milliseconds
+    setting :acquire_timeout, 10 # NOTE: seconds
+    setting :exp_precision, 1 # NOTE: milliseconds
+    setting :default_lock_ttl, 10_000 # NOTE: milliseconds
+    setting :default_queue_ttl, 5 # NOTE: seconds
+    setting :lock_release_batch_size, 100
+
+    # TODO: setting :logger, Logger.new(IO::NULL)
+    # TODO: setting :debug, true/false
+
+    validate 'retry_count', :integer
+    validate 'retry_delay', :integer
+    validate 'retry_jitter', :integer
+    validate 'acquire_timeout', :integer
+    validate 'exp_precision', :integer
+    validate 'default_lock_tt', :integer
+    validate 'default_queue_ttl', :integer
+    validate 'lock_release_batch_size', :integer
+  end
+
+  # @return [RedisClient]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :redis_client
+
+  # @param redis_client [RedisClient]
+  #   Redis connection manager, which will be used for the lock acquierment and distribution.
+  #   It should be an instance of RedisClient.
+  # @param configs [Block]
+  #   Custom configs for in-runtime configuration.
+  # @return [void]
+  #
+  # @api public
+  # @since 0.1.0
+  def initialize(redis_client, &configs)
+    configure(&configs)
+    @redis_client = redis_client
+  end
+
+  # @param lock_name [String]
+  #   Lock name to be acquier.
+  # @option process_id [Integer,String]
+  #   The process that want to acquire the lock.
+  # @option thread_id [Integer,String]
+  #   The process's thread that want to acquire the lock.
+  # @option ttl [Integer]
+  #   Lock's time to live (in milliseconds).
+  # @option queue_ttl [Integer]
+  #   ?
+  # @option timeout [Integer]
+  #   Time period whe should try to acquire the lock (in seconds).
+  # @option retry_count [Integer]
+  #   How many times we should try to acquire a lock.
+  # @option retry_delay [Integer]
+  #   A time-interval between the each retry (in milliseconds).
+  # @option retry_jitter [Integer]
+  #   Time-shift range for retry-delay (in milliseconds).
+  # @param [Block]
+  #   A block of code that should be executed after the successfully acquired lock.
+  # @return [Hash<Symbol,Any>]
+  #   Format: { ok: true/false, result: Symbol/Hash }.
+  #
+  # @api public
+  # @since 0.1.0
+  def lock(
+    lock_name,
+    process_id: RedisQueuedLocks::Resource.get_process_id,
+    thread_id: RedisQueuedLocks::Resource.get_thread_id,
+    ttl: config[:default_lock_ttl],
+    queue_ttl: config[:default_queue_ttl],
+    timeout: config[:acquire_timeout],
+    retry_count: config[:retry_count],
+    retry_delay: config[:retry_delay],
+    retry_jitter: config[:retry_jitter],
+    &block
+  )
+    RedisQueuedLocks::Acquier.acquire_lock!(
+      redis_client,
+      lock_name,
+      process_id:,
+      thread_id:,
+      ttl:,
+      queue_ttl:,
+      timeout:,
+      retry_count:,
+      retry_delay:,
+      retry_jitter:,
+      &block
+    )
+  end
+
+  # @param lock_name [String] The lock name that should be released.
+  # @return [?]
+  #
+  # @api public
+  # @since 0.1.0
+  def unlock(lock_name)
+    RedisQueuedLocks::Acquier.release_lock!(redis_client, lock_name)
+  end
+
+  # @return [?]
+  #
+  # @api public
+  # @since 0.1.0
+  def clear_locks(batch_size: config[:lock_release_batch_size])
+    RedisQueuedLocks::Acquier.release_all_locks!(redis_client, batch_size)
+  end
+end

data/lib/redis_queued_locks/debugger/interface.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Debugger::Interface
+  # @param message [String]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def debug(message)
+    RedisQueuedLocks::Debugger.debug(message)
+  end
+
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def enable_debugger!
+    RedisQueuedLocks::Debugger.enable!
+  end
+
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def disable_debugger!
+    RedisQueuedLocks::Debugger.disable!
+  end
+end

data/lib/redis_queued_locks/debugger.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Debugger
+  require_relative 'debugger/interface'
+
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  DEBUG_ENABLED_METHOD = <<~METHOD_DECLARATION.strip.freeze
+    def debug(message) = STDOUT.write_nonblock("#\{message}\n")
+  METHOD_DECLARATION
+
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  DEBUG_DISABLED_MEHTOD = <<~METHOD_DECLARATION.strip.freeze
+    def debug(message); end
+  METHOD_DECLARATION
+
+  class << self
+    # @api private
+    # @since 0.1.0
+    instance_variable_set(:@enabled, false)
+
+    # @return [void]
+    #
+    # @api private
+    # @since 0.1.0
+    def enable!
+      @enabled = true
+      eval(DEBUG_ENABLED_METHOD)
+    end
+
+    # @return [void]
+    #
+    # @api private
+    # @since 0.1.0
+    def disable!
+      @enabled = false
+      eval(DEBUG_DISABLED_MEHTOD)
+    end
+
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 0.1.0
+    def enabled?
+      @enabled
+    end
+
+    # @param message [String]
+    # @return [void]
+    #
+    # @api private
+    # @since 0.1.0
+    def debug(message); end
+  end
+end

data/lib/redis_queued_locks/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RedisQueuedLocks
+  # @api public
+  # @since 0.1.0
+  Error = Class.new(::StandardError)
+
+  # @api public
+  # @since 0.1.0
+  ArgumentError = Class.new(::ArgumentError)
+
+  # @api public
+  # @since 0.1.0
+  LockAcquiermentTimeoutError = Class.new(Error)
+
+  # @api public
+  # @since 0.1.0
+  LockAcquiermentLimitError = Class.new(Error)
+end

data/lib/redis_queued_locks/instrumentation.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Instrumentation
+end

data/lib/redis_queued_locks/resource.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Resource
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  LOCK_PATTERN = 'rql:lock:*'
+
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  LOCK_QUEUE_PATTERN = 'rql:lock_queue:*'
+
+  class << self
+    # @param process_id [Integer,String]
+    # @param thread_id [Integer,String]
+    # @return [String]
+    #
+    # @api private
+    # @since 0.1.0
+    def acquier_identifier(process_id = get_process_id, thread_id = get_thread_id)
+      "rql:acq:#{process_id}/#{thread_id}"
+    end
+
+    # @param lock_name [String]
+    # @return [String]
+    #
+    # @api private
+    # @since 0.1.0
+    def prepare_lock_key(lock_name)
+      "rql:lock:#{lock_name}"
+    end
+
+    # @param lock_name [String]
+    # @return [String]
+    #
+    # @api private
+    # @since 0.1.0
+    def prepare_lock_queue(lock_name)
+      "rql:lock_queue:#{lock_name}"
+    end
+
+    # @return [Integer] Redis's <Set> score that is calculated from the time (epoch) as an integer.
+    #
+    # @api private
+    # @since 0.1.0
+    def calc_initial_acquier_position
+      Time.now.to_i
+    end
+
+    # @param queue_ttl [Integer] In seconds
+    # @return [Integer] Redis's <Set> score barrier before wich all other acquiers are removed.
+    #
+    # @api private
+    # @since 0.1.0
+    def acquier_dead_score(queue_ttl)
+      Time.now.to_i - queue_ttl
+    end
+
+    # @param lock_queue [String]
+    # @return [String]
+    #
+    # @api private
+    # @since 0.1.0
+    def lock_key_from_queue(lock_queue)
+      # NOTE: 15 is a start position of the lock name
+      "rql:lock:#{lock_queue[15..]}"
+    end
+
+    # @return [Integer]
+    #
+    # @api private
+    # @since 0.1.0
+    def get_thread_id
+      ::Thread.current.object_id
+    end
+
+    # @return [Integer]
+    #
+    # @api private
+    # @since 0.1.0
+    def get_process_id
+      ::Process.pid
+    end
+  end
+end

data/lib/redis_queued_locks/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RedisQueuedLocks
+  # @return [String]
+  #
+  # @api public
+  # @since 0.0.0
+  VERSION = '0.0.0'
+end

data/lib/redis_queued_locks.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'redis-client'
+require 'qonfig'
+require 'timeout'
+
+# @api public
+# @since 0.1.0
+module RedisQueuedLocks
+  require_relative 'redis_queued_locks/version'
+  require_relative 'redis_queued_locks/errors'
+  require_relative 'redis_queued_locks/debugger'
+  require_relative 'redis_queued_locks/resource'
+  require_relative 'redis_queued_locks/acquier'
+  require_relative 'redis_queued_locks/instrumentation'
+  require_relative 'redis_queued_locks/client'
+
+  # @since 0.1.0
+  extend RedisQueuedLocks::Debugger::Interface
+end

data/redis_queued_locks.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'lib/redis_queued_locks/version'
+
+Gem::Specification.new do |spec|
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.name    = 'redis_queued_locks'
+  spec.version = RedisQueuedLocks::VERSION
+  spec.authors = ['Rustam Ibragimov']
+  spec.email   = ['iamdaiver@gmail.com']
+
+  spec.summary     = 'Queued distributed locks based on Redis.'
+  spec.description = 'Distributed lock implementation with "lock acquisition queue" ' \
+                     'capabilities based on the Redis Database.'
+  spec.homepage    = 'https://github.com/0exp/redis_queued_locks'
+  spec.license     = 'MIT'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = "#{spec.homepage}/blob/master"
+  spec.metadata['changelog_uri']   = "#{spec.homepage}/blob/master/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
+    end
+  end
+
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'redis-client', '~> 0.20'
+  spec.add_dependency 'qonfig', '~> 0.28'
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: redis_queued_locks
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Rustam Ibragimov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-02-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+- !ruby/object:Gem::Dependency
+  name: qonfig
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+description: Distributed lock implementation with "lock acquisition queue" capabilities
+  based on the Redis Database.
+email:
+- iamdaiver@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/redis_queued_locks.rb
+- lib/redis_queued_locks/acquier.rb
+- lib/redis_queued_locks/acquier/delay.rb
+- lib/redis_queued_locks/acquier/expire.rb
+- lib/redis_queued_locks/acquier/release.rb
+- lib/redis_queued_locks/acquier/try.rb
+- lib/redis_queued_locks/client.rb
+- lib/redis_queued_locks/debugger.rb
+- lib/redis_queued_locks/debugger/interface.rb
+- lib/redis_queued_locks/errors.rb
+- lib/redis_queued_locks/instrumentation.rb
+- lib/redis_queued_locks/resource.rb
+- lib/redis_queued_locks/version.rb
+- redis_queued_locks.gemspec
+homepage: https://github.com/0exp/redis_queued_locks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/0exp/redis_queued_locks
+  source_code_uri: https://github.com/0exp/redis_queued_locks/blob/master
+  changelog_uri: https://github.com/0exp/redis_queued_locks/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Queued distributed locks based on Redis.
+test_files: []