redlock 0.2.2 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 70744bd95881adacc0fc6623a3ba75ee0840339e
-  data.tar.gz: 3b5b971c30395079d645eab57504ba002b7bed61
+SHA256:
+  metadata.gz: a91b03cbb845e7b01556262e80e946e2d72980beeebce12d51380d7c57c57fb9
+  data.tar.gz: 73d38bac32a8003a556d3d8967155d15a8edbe988fc43387174ec506b21e8c99
 SHA512:
-  metadata.gz: 3e468fb7a3a98f4cb896a8d6ac6bed4ed25574ae20b6bd9f66c478674f8a3346404dcfc063bc82e74c1669e3e5402f8b1423e381c6e520073baf652b38ef69b1
-  data.tar.gz: 91506cfd3c6913f84cb50ce243ad13e4b9c4593a093872f83ac9518227ca477416f022b564f4aaa9004dab6c6f083614934283f58219b0970aa0cb33140d27f7
+  metadata.gz: e55aa47e007175e619e22ec2b2ca996add245143290750c79a27fbafc8bb6bd32e5c02b07d9a9752c1ad8cb7f22a10a2b245c9b963c1b4f186427d6c7a987d3a
+  data.tar.gz: dd61e0d187a5972ecbe09bde3345c1a6174263f06fca6b7d1da3ce8be19fe5bb69ffca4cfc24073705c5b5a40551bb1a65ffba1358c5fbaf37f10ea46a15a929

data/.gitignore

@@ -1,3 +1,5 @@
 *.gem
 coverage/
 .bundle/
+Gemfile.lock
+dump.rdb

data/.travis.yml

@@ -1,8 +1,23 @@
 language: ruby
-services:
-    - redis-server
+cache: bundler
+sudo: false
+
 rvm:
-  - "2.2.2"
+  - 2.4.9
+  - 2.5.7
+  - 2.6.5
+  - 2.7.0
+  - ruby-head
+
+before_install:
+  - yes | gem update --system
+  - gem install bundler -v "~> 2.0"
+
 script: bundle exec rspec spec
-sudo: false
-cache: bundler
+
+jobs:
+  allow_failures:
+    - rvm: ruby-head
+
+services:
+    - redis-server

data/Makefile

@@ -2,3 +2,8 @@ default: test
 test:
 	docker-compose run --rm test
 
+build:
+	docker-compose run --rm test gem build redlock.gemspec
+
+publish:
+	docker-compose run --rm test gem push `ls -lt *gem | head -n 1 | awk '{ print $$9 }'`

data/README.md

@@ -1,12 +1,9 @@
-[![Stories in Ready](https://badge.waffle.io/leandromoreira/redlock-rb.png?label=ready&title=Ready)](https://waffle.io/leandromoreira/redlock-rb)
 [![Build Status](https://travis-ci.org/leandromoreira/redlock-rb.svg?branch=master)](https://travis-ci.org/leandromoreira/redlock-rb)
 [![Coverage Status](https://coveralls.io/repos/leandromoreira/redlock-rb/badge.svg?branch=master)](https://coveralls.io/r/leandromoreira/redlock-rb?branch=master)
 [![Code Climate](https://codeclimate.com/github/leandromoreira/redlock-rb/badges/gpa.svg)](https://codeclimate.com/github/leandromoreira/redlock-rb)
-[![Dependency Status](https://gemnasium.com/leandromoreira/redlock-rb.svg)](https://gemnasium.com/leandromoreira/redlock-rb)
 [![Gem Version](https://badge.fury.io/rb/redlock.svg)](http://badge.fury.io/rb/redlock)
 [![security](https://hakiri.io/github/leandromoreira/redlock-rb/master.svg)](https://hakiri.io/github/leandromoreira/redlock-rb/master)
 [![Inline docs](http://inch-ci.org/github/leandromoreira/redlock-rb.svg?branch=master)](http://inch-ci.org/github/leandromoreira/redlock-rb)
-[![Join the chat at https://gitter.im/leandromoreira/redlock-rb](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/leandromoreira/redlock-rb?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 
 # Redlock - A ruby distributed lock using redis.
@@ -43,30 +40,28 @@ Or install it yourself as:
 
 ## Usage example
 
+### Acquiring a lock
+
+NOTE: All expiration durations are in milliseconds.
 ```ruby
   # Locking
   lock_manager = Redlock::Client.new([ "redis://127.0.0.1:7777", "redis://127.0.0.1:7778", "redis://127.0.0.1:7779" ])
   first_try_lock_info = lock_manager.lock("resource_key", 2000)
   second_try_lock_info = lock_manager.lock("resource_key", 2000)
 
-  # it prints lock info {validity: 1987, resource: "resource_key", value: "generated_uuid4"}
   p first_try_lock_info
-  # it prints false
+  # => {validity: 1987, resource: "resource_key", value: "generated_uuid4"}
+
   p second_try_lock_info
+  # => false
 
   # Unlocking
   lock_manager.unlock(first_try_lock_info)
+
   second_try_lock_info = lock_manager.lock("resource_key", 2000)
 
-  # now it prints lock info
   p second_try_lock_info
-```
-
-Redlock works seamlessly with [redis sentinel](http://redis.io/topics/sentinel), which is supported in redis 3.2+. It also allows clients to set any other arbitrary options on the Redis connection, e.g. password, driver, and more.
-
-```ruby
-servers = [ 'redis://localhost:6379', Redis.new(:url => 'redis://someotherhost:6379') ]
-redlock = Redlock::Client.new(servers)
+  # => {validity: 1962, resource: "resource_key", value: "generated_uuid5"}
 ```
 
 There's also a block version that automatically unlocks the lock:
@@ -81,7 +76,7 @@ lock_manager.lock("resource_key", 2000) do |locked|
 end
 ```
 
-There's also a bang version that only executes the block if the lock is successfully acquired, returning the block's value as a result, or raising an exception otherwise:
+There's also a bang version that only executes the block if the lock is successfully acquired, returning the block's value as a result, or raising an exception otherwise. Passing a block is mandatory.
 
 ```ruby
 begin
@@ -93,34 +88,105 @@ rescue Redlock::LockError
 end
 ```
 
+### Extending a lock
+
 To extend the life of the lock:
 
 ```ruby
 begin
-  block_result = lock_manager.lock!("resource_key", 2000) do |lock_info|
-    # critical code
-    lock_manager.lock("resource key", 3000, extend: lock_info)
-    # more critical code
+  lock_info = lock_manager.lock("resource_key", 2000)
+  while lock_info
+    # Critical code
+
+    # Time up and more work to do? Extend the lock.
+    lock_info = lock_manager.lock("resource key", 3000, extend: lock_info)
   end
 rescue Redlock::LockError
   # error handling
 end
 ```
 
-The above code will also acquire the lock if the previous lock has expired and the lock is currently free. Keep in mind that this means the lock could have been acquired by someone else in the meantime. To only extend the life of the lock if currently locked by yourself, use `extend_life` parameter:
+The above code will also acquire the lock if the previous lock has expired and the lock is currently free. Keep in mind that this means the lock could have been acquired and released by someone else in the meantime. To only extend the life of the lock if currently locked by yourself, use the `extend_only_if_locked` parameter:
 
 ```ruby
-begin
-  block_result = lock_manager.lock!("resource_key", 2000) do |lock_info|
-    # critical code
-    lock_manager.lock("resource key", 3000, extend: lock_info, extend_life: true)
-    # more critical code, only if lock was still hold
-  end
-rescue Redlock::LockError
-  # error handling
-end
+lock_manager.lock("resource key", 3000, extend: lock_info, extend_only_if_locked: true)
 ```
 
+### Querying lock status
+
+You can check if a resource is locked:
+
+```ruby
+resource = "resource_key"
+lock_info = lock_manager.lock(resource, 2000)
+lock_manager.locked?(resource)
+#=> true
+
+lock_manager.unlock(lock_info)
+lock_manager.locked?(resource)
+#=> false
+```
+
+Any caller can call the above method to query the status. If you hold a lock and would like to check if it is valid, you can use the `valid_lock?` method:
+
+```ruby
+lock_info = lock_manager.lock("resource_key", 2000)
+lock_manager.valid_lock?(lock_info)
+#=> true
+
+lock_manager.unlock(lock_info)
+lock_manager.valid_lock?(lock_info)
+#=> false
+```
+
+The above methods **are not safe if you are using this to time critical code**, since they return true if the lock has not expired, even if there's only (for example) 1ms left on the lock. If you want to safely time the lock validity, you can use the `get_remaining_ttl_for_lock` and `get_remaining_ttl_for_resource` methods.
+
+Use `get_remaining_ttl_for_lock` if you hold a lock and want to check the TTL specifically for your lock:
+```ruby
+resource = "resource_key"
+lock_info = lock_manager.lock(resource, 2000)
+sleep 1
+
+lock_manager.get_remaining_ttl_for_lock(lock_info)
+#=> 986
+
+lock_manager.unlock(lock_info)
+lock_manager.get_remaining_ttl_for_lock(lock_info)
+#=> nil 
+```
+
+Use `get_remaining_ttl_for_resource` if you do not hold a lock, but want to know the remaining TTL on a locked resource:
+```ruby
+# Some part of the code
+resource = "resource_key"
+lock_info = lock_manager.lock(resource, 2000)
+
+# Some other part of the code
+lock_manager.locked?(resource)
+#=> true
+lock_manager.get_remaining_ttl_for_resource(resource)
+#=> 1975 
+
+# Sometime later
+lock_manager.locked?(resource)
+#=> false
+lock_manager.get_remaining_ttl_for_resource(resource)
+#=> nil 
+```
+
+## Redis client configuration
+
+`Redlock::Client` expects URLs or Redis objects on initialization. Redis objects should be used for configuring the connection in more detail, i.e. setting username and password.
+
+```ruby
+servers = [ 'redis://localhost:6379', Redis.new(:url => 'redis://someotherhost:6379') ]
+redlock = Redlock::Client.new(servers)
+```
+
+Redlock works seamlessly with [redis sentinel](http://redis.io/topics/sentinel), which is supported in redis 3.2+.
+
+## Redlock configuration
+
 It's possible to customize the retry logic providing the following options:
 
 ```ruby
@@ -133,8 +199,15 @@ It's possible to customize the retry logic providing the following options:
                  })
 ```
 
-For more information you can check [documentation](http://www.rubydoc.info/gems/redlock/Redlock%2FClient:initialize).
+It is possible to associate `:retry_delay` option with `Proc` object. It will be called every time, with attempt number
+as argument, to get delay time value before next retry.
+
+```ruby
+retry_delay = proc { |attempt_number| 200 * attempt_number ** 2 } # delay of 200ms for 1st retry, 800ms for 2nd retry, etc.
+lock_manager = Redlock::Client.new(servers, retry_delay: retry_delay)
+```
 
+For more information you can check [documentation](http://www.rubydoc.info/gems/redlock/Redlock%2FClient:initialize).
 
 ## Run tests
 

data/docker-compose.yml

@@ -11,17 +11,23 @@ services:
       - REDIS1_PORT=6379
       - REDIS2_HOST=redis2.local.com
       - REDIS2_PORT=6379
+      - REDIS3_HOST=redis3.local.com
+      - REDIS3_PORT=6379
       - DEFAULT_REDIS_HOST=redis1.local.com
       - DEFAULT_REDIS_PORT=6379
     links:
       - redis1:redis1.local.com
       - redis2:redis2.local.com
+      - redis3:redis3.local.com
     depends_on:
       - redis1
       - redis2
+      - redis3
 
   redis1:
     image: redis
   redis2:
     image: redis
+  redis3:
+    image: redis
 

data/lib/redlock.rb

@@ -3,5 +3,9 @@ require 'redlock/version'
 module Redlock
   autoload :Client, 'redlock/client'
 
-  LockError = Class.new(StandardError)
+  class LockError < StandardError
+    def initialize(resource)
+      super "failed to acquire lock on '#{resource}'".freeze
+    end
+  end
 end

data/lib/redlock/client.rb

@@ -12,14 +12,27 @@ module Redlock
     DEFAULT_RETRY_JITTER  = 50
     CLOCK_DRIFT_FACTOR    = 0.01
 
+    ##
+    # Returns default time source function depending on CLOCK_MONOTONIC availability.
+    #
+    def self.default_time_source
+      if defined?(Process::CLOCK_MONOTONIC)
+        proc { (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i }
+      else
+        proc { (Time.now.to_f * 1000).to_i }
+      end
+    end
+
     # Create a distributed lock manager implementing redlock algorithm.
     # Params:
     # +servers+:: The array of redis connection URLs or Redis connection instances. Or a mix of both.
-    # +options+:: You can override the default value for `retry_count`, `retry_delay` and `retry_gitter`.
+    # +options+::
     #    * `retry_count`   being how many times it'll try to lock a resource (default: 3)
     #    * `retry_delay`   being how many ms to sleep before try to lock again (default: 200)
     #    * `retry_jitter`  being how many ms to jitter retry delay (default: 50)
     #    * `redis_timeout` being how the Redis timeout will be set in seconds (default: 0.1)
+    #    * `time_source`   being a callable object returning a monotonic time in milliseconds
+    #                      (default: see #default_time_source)
     def initialize(servers = DEFAULT_REDIS_URLS, options = {})
       redis_timeout = options[:redis_timeout] || DEFAULT_REDIS_TIMEOUT
       @servers = servers.map do |server|
@@ -33,6 +46,7 @@ module Redlock
       @retry_count = options[:retry_count] || DEFAULT_RETRY_COUNT
       @retry_delay = options[:retry_delay] || DEFAULT_RETRY_DELAY
       @retry_jitter = options[:retry_jitter] || DEFAULT_RETRY_JITTER
+      @time_source = options[:time_source] || self.class.default_time_source
     end
 
     # Locks a resource for a given time.
@@ -41,11 +55,21 @@ module Redlock
     # +ttl+:: The time-to-live in ms for the lock.
     # +options+:: Hash of optional parameters
     #  * +extend+: A lock ("lock_info") to extend.
-    #  * +extend_only_if_life+: If +extend+ is given, only acquire lock if currently held
+    #  * +extend_only_if_locked+: Boolean, if +extend+ is given, only acquire lock if currently held
+    #  * +extend_only_if_life+: Deprecated, same as +extend_only_if_locked+
+    #  * +extend_life+: Deprecated, same as +extend_only_if_locked+
     # +block+:: an optional block to be executed; after its execution, the lock (if successfully
     # acquired) is automatically unlocked.
     def lock(resource, ttl, options = {}, &block)
       lock_info = try_lock_instances(resource, ttl, options)
+      if options[:extend_only_if_life] && !Gem::Deprecate.skip
+        warn 'DEPRECATION WARNING: The `extend_only_if_life` option has been renamed `extend_only_if_locked`.'
+        options[:extend_only_if_locked] = options[:extend_only_if_life]
+      end
+      if options[:extend_life] && !Gem::Deprecate.skip
+        warn 'DEPRECATION WARNING: The `extend_life` option has been renamed `extend_only_if_locked`.'
+        options[:extend_only_if_locked] = options[:extend_life]
+      end
 
       if block_given?
         begin
@@ -69,15 +93,52 @@ module Redlock
     # Locks a resource, executing the received block only after successfully acquiring the lock,
     # and returning its return value as a result.
     # See Redlock::Client#lock for parameters.
-    def lock!(*args)
+    def lock!(resource, *args)
       fail 'No block passed' unless block_given?
 
-      lock(*args) do |lock_info|
-        raise LockError, 'failed to acquire lock' unless lock_info
+      lock(resource, *args) do |lock_info|
+        raise LockError, resource unless lock_info
         return yield
       end
     end
 
+    # Gets remaining ttl of a resource. The ttl is returned if the holder
+    # currently holds the lock and it has not expired, otherwise the method
+    # returns nil.
+    # Params:
+    # +lock_info+:: the lock that has been acquired when you locked the resource
+    def get_remaining_ttl_for_lock(lock_info)
+      ttl_info = try_get_remaining_ttl(lock_info[:resource])
+      return nil if ttl_info.nil? || ttl_info[:value] != lock_info[:value]
+      ttl_info[:ttl]
+    end
+
+    # Gets remaining ttl of a resource. If there is no valid lock, the method
+    # returns nil.
+    # Params:
+    # +resource+:: the name of the resource (string) for which to check the ttl
+    def get_remaining_ttl_for_resource(resource)
+      ttl_info = try_get_remaining_ttl(resource)
+      return nil if ttl_info.nil?
+      ttl_info[:ttl]
+    end
+
+    # Checks if a resource is locked
+    # Params:
+    # +lock_info+:: the lock that has been acquired when you locked the resource
+    def locked?(resource)
+      ttl = get_remaining_ttl_for_resource(resource)
+      !(ttl.nil? || ttl.zero?)
+    end
+
+    # Checks if a lock is still valid
+    # Params:
+    # +lock_info+:: the lock that has been acquired when you locked the resource
+    def valid_lock?(lock_info)
+      ttl = get_remaining_ttl_for_lock(lock_info)
+      !(ttl.nil? || ttl.zero?)
+    end
+
     private
 
     class RedisInstance
@@ -98,11 +159,26 @@ module Redlock
         end
       eos
 
+      PTTL_SCRIPT = <<-eos
+        return { redis.call("get", KEYS[1]), redis.call("pttl", KEYS[1]) }
+      eos
+
+      module ConnectionPoolLike
+        def with
+          yield self
+        end
+      end
+
       def initialize(connection)
-        if connection.respond_to?(:client)
+        if connection.respond_to?(:with)
           @redis = connection
         else
-          @redis = Redis.new(connection)
+          if connection.respond_to?(:client)
+            @redis = connection
+          else
+            @redis = Redis.new(connection)
+          end
+          @redis.extend(ConnectionPoolLike)
         end
 
         load_scripts
@@ -110,23 +186,34 @@ module Redlock
 
       def lock(resource, val, ttl, allow_new_lock)
         recover_from_script_flush do
-          @redis.evalsha @lock_script_sha, keys: [resource], argv: [val, ttl, allow_new_lock]
+          @redis.with { |conn| conn.evalsha @lock_script_sha, keys: [resource], argv: [val, ttl, allow_new_lock] }
         end
+      rescue Redis::BaseConnectionError
+        false
       end
 
       def unlock(resource, val)
         recover_from_script_flush do
-          @redis.evalsha @unlock_script_sha, keys: [resource], argv: [val]
+          @redis.with { |conn| conn.evalsha @unlock_script_sha, keys: [resource], argv: [val] }
         end
       rescue
         # Nothing to do, unlocking is just a best-effort attempt.
       end
 
+      def get_remaining_ttl(resource)
+        recover_from_script_flush do
+          @redis.with { |conn| conn.evalsha @pttl_script_sha, keys: [resource] }
+        end
+      rescue Redis::BaseConnectionError
+        nil
+      end
+
       private
 
       def load_scripts
-        @unlock_script_sha = @redis.script(:load, UNLOCK_SCRIPT)
-        @lock_script_sha = @redis.script(:load, LOCK_SCRIPT)
+        @unlock_script_sha = @redis.with { |conn| conn.script(:load, UNLOCK_SCRIPT) }
+        @lock_script_sha = @redis.with { |conn| conn.script(:load, LOCK_SCRIPT) }
+        @pttl_script_sha = @redis.with { |conn| conn.script(:load, PTTL_SCRIPT) }
       end
 
       def recover_from_script_flush
@@ -149,11 +236,11 @@ module Redlock
     end
 
     def try_lock_instances(resource, ttl, options)
-      tries = options[:extend] ? 1 : @retry_count
+      tries = options[:extend] ? 1 : (@retry_count + 1)
 
       tries.times do |attempt_number|
         # Wait a random delay before retrying.
-        sleep((@retry_delay + rand(@retry_jitter)).to_f / 1000) if attempt_number > 0
+        sleep(attempt_retry_delay(attempt_number)) if attempt_number > 0
 
         lock_info = lock_instances(resource, ttl, options)
         return lock_info if lock_info
@@ -162,9 +249,20 @@ module Redlock
       false
     end
 
+    def attempt_retry_delay(attempt_number)
+      retry_delay =
+        if @retry_delay.respond_to?(:call)
+          @retry_delay.call(attempt_number)
+        else
+          @retry_delay
+        end
+
+      (retry_delay + rand(@retry_jitter)).to_f / 1000
+    end
+
     def lock_instances(resource, ttl, options)
       value = (options[:extend] || { value: SecureRandom.uuid })[:value]
-      allow_new_lock = (options[:extend_life] || options[:extend_only_if_life]) ? 'no' : 'yes'
+      allow_new_lock = options[:extend_only_if_locked] ? 'no' : 'yes'
 
       locked, time_elapsed = timed do
         @servers.select { |s| s.lock resource, value, ttl, allow_new_lock }.size
@@ -180,6 +278,37 @@ module Redlock
       end
     end
 
+    def try_get_remaining_ttl(resource)
+      # Responses from the servers are a 2 tuple of format [lock_value, ttl].
+      # The lock_value is nil if it does not exist. Since servers may have
+      # different lock values, the responses are grouped by the lock_value and
+      # transofrmed into a hash: { lock_value1 => [ttl1, ttl2, ttl3],
+      # lock_value2 => [ttl4, tt5] }
+      ttls_by_value, time_elapsed = timed do
+        @servers.map { |s| s.get_remaining_ttl(resource) }
+          .select { |ttl_tuple| ttl_tuple&.first }
+          .group_by(&:first)
+          .transform_values { |ttl_tuples| ttl_tuples.map { |t| t.last } }
+      end
+
+      # Authoritative lock value is that which is returned by the majority of
+      # servers
+      authoritative_value, ttls =
+        ttls_by_value.max_by { |(lock_value, ttls)| ttls.length }
+
+      if ttls && ttls.size >= @quorum
+        # Return the  minimum TTL of an N/2+1 selection. It will always be
+        # correct (it will guarantee that at least N/2+1 servers have a TTL that
+        # value or longer)
+        min_ttl = ttls.sort.last(@quorum).first
+        min_ttl = min_ttl - time_elapsed - drift(min_ttl)
+        { value: authoritative_value, ttl: min_ttl }
+      else
+        # No lock_value is authoritatively held for the resource
+        nil
+      end
+    end
+
     def drift(ttl)
       # Add 2 milliseconds to the drift to account for Redis expires
       # precision, which is 1 millisecond, plus 1 millisecond min drift
@@ -188,8 +317,8 @@ module Redlock
     end
 
     def timed
-      start_time = (Time.now.to_f * 1000).to_i
-      [yield, (Time.now.to_f * 1000).to_i - start_time]
+      start_time = @time_source.call()
+      [yield, @time_source.call() - start_time]
     end
   end
 end

data/lib/redlock/testing.rb

@@ -1,17 +1,29 @@
+require 'redlock'
+
 module Redlock
   class Client
-    attr_writer :testing_mode
+    class << self
+      attr_accessor :testing_mode
+    end
+
+    def testing_mode=(mode)
+      warn 'DEPRECATION WARNING: Instance-level `testing_mode` has been removed, and this ' +
+        'setter will be removed in the future. Please set the testing mode on the `Redlock::Client` ' +
+        'instead, e.g. `Redlock::Client.testing_mode = :bypass`.'
+
+      self.class.testing_mode = mode
+    end
 
     alias_method :try_lock_instances_without_testing, :try_lock_instances
 
     def try_lock_instances(resource, ttl, options)
-      if @testing_mode == :bypass
+      if self.class.testing_mode == :bypass
         {
           validity: ttl,
           resource: resource,
           value: options[:extend] ? options[:extend].fetch(:value) : SecureRandom.uuid
         }
-      elsif @testing_mode == :fail
+      elsif self.class.testing_mode == :fail
         false
       else
         try_lock_instances_without_testing resource, ttl, options
@@ -21,14 +33,14 @@ module Redlock
     alias_method :unlock_without_testing, :unlock
 
     def unlock(lock_info)
-      unlock_without_testing lock_info unless @testing_mode == :bypass
+      unlock_without_testing lock_info unless self.class.testing_mode == :bypass
     end
 
     class RedisInstance
       alias_method :load_scripts_without_testing, :load_scripts
 
       def load_scripts
-        load_scripts_without_testing
+        load_scripts_without_testing unless Redlock::Client.testing_mode == :bypass
       rescue Redis::CommandError
         # FakeRedis doesn't have #script, but doesn't need it either.
         raise unless defined?(::FakeRedis)

data/lib/redlock/version.rb

@@ -1,3 +1,3 @@
 module Redlock
-  VERSION = '0.2.2'
+  VERSION = '1.2.1'
 end

data/redlock.gemspec

@@ -1,26 +1,29 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'redlock/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "redlock"
+  spec.name          = 'redlock'
   spec.version       = Redlock::VERSION
-  spec.authors       = ["Leandro Moreira"]
-  spec.email         = ["leandro.ribeiro.moreira@gmail.com"]
-  spec.summary       = %q{Distributed lock using Redis written in Ruby.}
-  spec.description   = %q{Distributed lock using Redis written in Ruby. Highly inspired by https://github.com/antirez/redlock-rb.}
-  spec.homepage      = "https://github.com/leandromoreira/redlock-rb"
+  spec.authors       = ['Leandro Moreira']
+  spec.email         = ['leandro.ribeiro.moreira@gmail.com']
+  spec.summary       = 'Distributed lock using Redis written in Ruby.'
+  spec.description   = 'Distributed lock using Redis written in Ruby. Highly inspired by https://github.com/antirez/redlock-rb.'
+  spec.homepage      = 'https://github.com/leandromoreira/redlock-rb'
   spec.license       = 'BSD-2-Clause'
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
   spec.add_dependency 'redis', '>= 3.0.0', '< 5.0'
 
-  spec.add_development_dependency "coveralls", "~> 0.8.13"
-  spec.add_development_dependency 'rake', '~> 11.1', '>= 11.1.2'
+  spec.add_development_dependency 'connection_pool', '~> 2.2'
+  spec.add_development_dependency 'coveralls', '~> 0.8'
+  spec.add_development_dependency 'json', '>= 2.3.0', '~> 2.3.1'
+  spec.add_development_dependency 'rake', '>= 11.1.2', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3', '>= 3.0.0'
 end

data/spec/client_spec.rb

@@ -1,20 +1,31 @@
 require 'spec_helper'
 require 'securerandom'
+require 'redis'
+require 'connection_pool'
 
 RSpec.describe Redlock::Client do
   # It is recommended to have at least 3 servers in production
   let(:lock_manager_opts) { { retry_count: 3 } }
   let(:lock_manager) { Redlock::Client.new(Redlock::Client::DEFAULT_REDIS_URLS, lock_manager_opts) }
+  let(:redis_client) { Redis.new(url: "redis://#{redis1_host}:#{redis1_port}") }
   let(:resource_key) { SecureRandom.hex(3)  }
   let(:ttl) { 1000 }
   let(:redis1_host) { ENV["REDIS1_HOST"] || "localhost" }
   let(:redis1_port) { ENV["REDIS1_PORT"] || "6379" }
   let(:redis2_host) { ENV["REDIS2_HOST"] || "127.0.0.1" }
   let(:redis2_port) { ENV["REDIS2_PORT"] || "6379" }
+  let(:redis3_host) { ENV["REDIS3_HOST"] || "127.0.0.1" }
+  let(:redis3_port) { ENV["REDIS3_PORT"] || "6379" }
+  let(:unreachable_redis) {
+    redis = Redis.new(url: 'redis://localhost:46864')
+    def redis.with
+      yield self
+    end
+    redis
+  }
 
   describe 'initialize' do
     it 'accepts both redis URLs and Redis objects' do
-      print redis1_host
       servers = [ "redis://#{redis1_host}:#{redis1_port}", Redis.new(url: "redis://#{redis2_host}:#{redis2_port}") ]
       redlock = Redlock::Client.new(servers)
 
@@ -24,6 +35,15 @@ RSpec.describe Redlock::Client do
 
       expect(redlock_servers).to match_array([redis1_host, redis2_host])
     end
+
+    it 'accepts ConnectionPool objects' do
+      pool = ConnectionPool.new { Redis.new(url: "redis://#{redis1_host}:#{redis1_port}") }
+      redlock = Redlock::Client.new([pool])
+
+      lock_info = lock_manager.lock(resource_key, ttl)
+      expect(resource_key).to_not be_lockable(lock_manager, ttl)
+      lock_manager.unlock(lock_info)
+    end
   end
 
   describe 'lock' do
@@ -42,6 +62,12 @@ RSpec.describe Redlock::Client do
         expect(@lock_info).to be_lock_info_for(resource_key)
       end
 
+      it 'interprets lock time as milliseconds' do
+        ttl = 20000
+        @lock_info = lock_manager.lock(resource_key, ttl)
+        expect(redis_client.pttl(resource_key)).to be_within(200).of(ttl)
+      end
+
       it 'can extend its own lock' do
         my_lock_info = lock_manager.lock(resource_key, ttl)
         @lock_info = lock_manager.lock(resource_key, ttl, extend: my_lock_info)
@@ -57,16 +83,26 @@ RSpec.describe Redlock::Client do
         end
       end
 
-      context 'when extend_only_if_life flag is given' do
+      context 'when extend_only_if_locked flag is given' do
         it 'does not extend a non-existent lock' do
-          @lock_info = lock_manager.lock(resource_key, ttl, extend: {value: 'hello world'}, extend_only_if_life: true)
+          @lock_info = lock_manager.lock(resource_key, ttl, extend: {value: 'hello world'}, extend_only_if_locked: true)
           expect(@lock_info).to eq(false)
         end
       end
 
-      context 'when extend_only_if_life flag is not given' do
+      it '(when extending) resets the TTL, rather than adding extra time to it' do
+        ttl = 20000
+        lock_info = lock_manager.lock(resource_key, ttl)
+        expect(resource_key).to_not be_lockable(lock_manager, ttl)
+
+        lock_info = lock_manager.lock(resource_key, ttl, extend: lock_info, extend_only_if_locked: true)
+        expect(lock_info).not_to be_nil
+        expect(redis_client.pttl(resource_key)).to be_within(200).of(ttl)
+      end
+
+      context 'when extend_only_if_locked flag is not given' do
         it "sets the given value when trying to extend a non-existent lock" do
-          @lock_info = lock_manager.lock(resource_key, ttl, extend: {value: 'hello world'}, extend_only_if_life: false)
+          @lock_info = lock_manager.lock(resource_key, ttl, extend: {value: 'hello world'}, extend_only_if_locked: false)
           expect(@lock_info).to be_lock_info_for(resource_key)
           expect(@lock_info[:value]).to eq('hello world') # really we should test what's in redis
         end
@@ -77,6 +113,28 @@ RSpec.describe Redlock::Client do
         second_attempt = lock_manager.lock(resource_key, ttl)
         expect(second_attempt).to eq(false)
       end
+
+      context 'when extend_life flag is given' do
+        it 'treats it as extend_only_if_locked but warns it is deprecated' do
+          ttl = 20_000
+          lock_info = lock_manager.lock(resource_key, ttl)
+          expect(resource_key).to_not be_lockable(lock_manager, ttl)
+          expect(lock_manager).to receive(:warn).with(/DEPRECATION WARNING: The `extend_life`/)
+          lock_info = lock_manager.lock(resource_key, ttl, extend: lock_info, extend_life: true)
+          expect(lock_info).not_to be_nil
+        end
+      end
+
+      context 'when extend_only_if_life flag is given' do
+        it 'treats it as extend_only_if_locked but warns it is deprecated' do
+          ttl = 20_000
+          lock_info = lock_manager.lock(resource_key, ttl)
+          expect(resource_key).to_not be_lockable(lock_manager, ttl)
+          expect(lock_manager).to receive(:warn).with(/DEPRECATION WARNING: The `extend_only_if_life`/)
+          lock_info = lock_manager.lock(resource_key, ttl, extend: lock_info, extend_only_if_life: true)
+          expect(lock_info).not_to be_nil
+        end
+      end
     end
 
     context 'when lock is not available' do
@@ -95,14 +153,14 @@ RSpec.describe Redlock::Client do
         expect(lock_info).to eql(false)
       end
 
-      it 'retries up to \'retry_count\' times' do
+      it 'tries up to \'retry_count\' + 1 times' do
         expect(lock_manager).to receive(:lock_instances).exactly(
-          lock_manager_opts[:retry_count]).times.and_return(false)
+          lock_manager_opts[:retry_count] + 1).times.and_return(false)
         lock_manager.lock(resource_key, ttl)
       end
 
       it 'sleeps in between retries' do
-        expect(lock_manager).to receive(:sleep).exactly(lock_manager_opts[:retry_count] - 1).times
+        expect(lock_manager).to receive(:sleep).exactly(lock_manager_opts[:retry_count]).times
         lock_manager.lock(resource_key, ttl)
       end
 
@@ -121,6 +179,46 @@ RSpec.describe Redlock::Client do
         end.at_least(:once)
         lock_manager.lock(resource_key, ttl)
       end
+
+      it 'accepts retry_delay as proc' do
+        retry_delay = proc do |attempt_number|
+          expect(attempt_number).to eq(1)
+          2000
+        end
+
+        lock_manager = Redlock::Client.new(Redlock::Client::DEFAULT_REDIS_URLS, retry_count: 1, retry_delay: retry_delay)
+        another_lock_info = lock_manager.lock(resource_key, ttl)
+
+        expect(lock_manager).to receive(:sleep) do |sleep|
+          expect(sleep * 1000).to be_within(described_class::DEFAULT_RETRY_JITTER).of(2000)
+        end.exactly(:once)
+        lock_manager.lock(resource_key, ttl)
+        lock_manager.unlock(another_lock_info)
+      end
+    end
+
+    context 'when a server goes away' do
+      it 'does not raise an error on connection issues' do
+        # We re-route the lock manager to a (hopefully) non-existent Redis URL.
+        redis_instance = lock_manager.instance_variable_get(:@servers).first
+        redis_instance.instance_variable_set(:@redis, unreachable_redis)
+
+        expect {
+          expect(lock_manager.lock(resource_key, ttl)).to be_falsey
+        }.to_not raise_error
+      end
+    end
+
+    context 'when a server comes back' do
+      it 'recovers from connection issues' do
+        # Same as above.
+        redis_instance = lock_manager.instance_variable_get(:@servers).first
+        old_redis = redis_instance.instance_variable_get(:@redis)
+        redis_instance.instance_variable_set(:@redis, unreachable_redis)
+        expect(lock_manager.lock(resource_key, ttl)).to be_falsey
+        redis_instance.instance_variable_set(:@redis, old_redis)
+        expect(lock_manager.lock(resource_key, ttl)).to be_truthy
+      end
     end
 
     context 'when script cache has been flushed' do
@@ -254,7 +352,9 @@ RSpec.describe Redlock::Client do
       after { lock_manager.unlock(@another_lock_info) }
 
       it 'raises a LockError' do
-        expect { lock_manager.lock!(resource_key, ttl) {} }.to raise_error(Redlock::LockError)
+        expect { lock_manager.lock!(resource_key, ttl) {} }.to raise_error(
+          Redlock::LockError, "failed to acquire lock on '#{resource_key}'"
+        )
       end
 
       it 'does not execute the block' do
@@ -267,4 +367,171 @@ RSpec.describe Redlock::Client do
       end
     end
   end
+
+  describe 'get_remaining_ttl_for_resource' do
+    context 'when lock is valid' do
+      after(:each) { lock_manager.unlock(@lock_info) if @lock_info }
+
+      it 'gets the remaining ttl of a lock' do
+        ttl = 20_000
+        @lock_info = lock_manager.lock(resource_key, ttl)
+        remaining_ttl = lock_manager.get_remaining_ttl_for_resource(resource_key)
+        expect(remaining_ttl).to be_within(300).of(ttl)
+      end
+
+      context 'when servers respond with varying ttls' do
+        let (:servers) {
+          [
+            "redis://#{redis1_host}:#{redis1_port}",
+            "redis://#{redis2_host}:#{redis2_port}",
+            "redis://#{redis3_host}:#{redis3_port}"
+          ]
+        }
+        let (:redlock) { Redlock::Client.new(servers) }
+        after(:each) { redlock.unlock(@lock_info) if @lock_info }
+
+        it 'returns the minimum ttl value' do
+          ttl = 20_000
+          @lock_info = redlock.lock(resource_key, ttl)
+
+          # Mock redis server responses to return different ttls
+          returned_ttls = [20_000, 15_000, 10_000]
+          redlock.instance_variable_get(:@servers).each_with_index do |server, index|
+            allow(server).to(receive(:get_remaining_ttl))
+              .with(resource_key)
+              .and_return([@lock_info[:value], returned_ttls[index]])
+          end
+
+          remaining_ttl = redlock.get_remaining_ttl_for_lock(@lock_info)
+
+          # Assert that the TTL is closest to the closest to the correct value
+          expect(remaining_ttl).to be_within(300).of(returned_ttls[1])
+        end
+      end
+    end
+
+    context 'when lock is not valid' do
+      it 'returns nil' do
+        lock_info = lock_manager.lock(resource_key, ttl)
+        lock_manager.unlock(lock_info)
+        remaining_ttl = lock_manager.get_remaining_ttl_for_resource(resource_key)
+        expect(remaining_ttl).to be_nil
+      end
+    end
+
+    context 'when server goes away' do
+      after(:each) { lock_manager.unlock(@lock_info) if @lock_info }
+
+      it 'does not raise an error on connection issues' do
+        @lock_info = lock_manager.lock(resource_key, ttl)
+
+        # Replace redis with unreachable instance
+        redis_instance = lock_manager.instance_variable_get(:@servers).first
+        old_redis = redis_instance.instance_variable_get(:@redis)
+        redis_instance.instance_variable_set(:@redis, unreachable_redis)
+
+        expect {
+          remaining_ttl = lock_manager.get_remaining_ttl_for_resource(resource_key)
+          expect(remaining_ttl).to be_nil
+        }.to_not raise_error
+      end
+    end
+
+    context 'when a server comes back' do
+      after(:each) { lock_manager.unlock(@lock_info) if @lock_info }
+
+      it 'recovers from connection issues' do
+        @lock_info = lock_manager.lock(resource_key, ttl)
+
+        # Replace redis with unreachable instance
+        redis_instance = lock_manager.instance_variable_get(:@servers).first
+        old_redis = redis_instance.instance_variable_get(:@redis)
+        redis_instance.instance_variable_set(:@redis, unreachable_redis)
+
+        expect(lock_manager.get_remaining_ttl_for_resource(resource_key)).to be_nil
+
+        # Restore redis
+        redis_instance.instance_variable_set(:@redis, old_redis)
+        expect(lock_manager.get_remaining_ttl_for_resource(resource_key)).to be_truthy
+      end
+    end
+  end
+
+  describe 'get_remaining_ttl_for_lock' do
+    context 'when lock is valid' do
+      it 'gets the remaining ttl of a lock' do
+        ttl = 20_000
+        lock_info = lock_manager.lock(resource_key, ttl)
+        remaining_ttl = lock_manager.get_remaining_ttl_for_lock(lock_info)
+        expect(remaining_ttl).to be_within(300).of(ttl)
+        lock_manager.unlock(lock_info)
+      end
+    end
+
+    context 'when lock is not valid' do
+      it 'returns nil' do
+        lock_info = lock_manager.lock(resource_key, ttl)
+        lock_manager.unlock(lock_info)
+        remaining_ttl = lock_manager.get_remaining_ttl_for_lock(lock_info)
+        expect(remaining_ttl).to be_nil
+      end
+    end
+  end
+
+  describe 'locked?' do
+    context 'when lock is available' do
+      after(:each) { lock_manager.unlock(@lock_info) if @lock_info }
+
+      it 'returns true' do
+        @lock_info = lock_manager.lock(resource_key, ttl)
+        expect(lock_manager).to be_locked(resource_key)
+      end
+    end
+
+    context 'when lock is not available' do
+      it 'returns false' do
+        lock_info = lock_manager.lock(resource_key, ttl)
+        lock_manager.unlock(lock_info)
+        expect(lock_manager).not_to be_locked(resource_key)
+      end
+    end
+  end
+
+  describe 'valid_lock?' do
+    context 'when lock is available' do
+      after(:each) { lock_manager.unlock(@lock_info) if @lock_info }
+
+      it 'returns true' do
+        @lock_info = lock_manager.lock(resource_key, ttl)
+        expect(lock_manager).to be_valid_lock(@lock_info)
+      end
+    end
+
+    context 'when lock is not available' do
+      it 'returns false' do
+        lock_info = lock_manager.lock(resource_key, ttl)
+        lock_manager.unlock(lock_info)
+        expect(lock_manager).not_to be_valid_lock(lock_info)
+      end
+    end
+  end
+
+  describe '#default_time_source' do
+    context 'when CLOCK_MONOTONIC is available (MRI, JRuby)' do
+      it 'returns a callable using Process.clock_gettime()' do
+        skip 'CLOCK_MONOTONIC not defined' unless defined?(Process::CLOCK_MONOTONIC)
+        expect(Process).to receive(:clock_gettime).with(Process::CLOCK_MONOTONIC).and_call_original
+        Redlock::Client.default_time_source.call()
+      end
+    end
+
+    context 'when CLOCK_MONOTONIC is not available' do
+      it 'returns a callable using Time.now()' do
+        cm = Process.send(:remove_const, :CLOCK_MONOTONIC)
+        expect(Time).to receive(:now).and_call_original
+        Redlock::Client.default_time_source.call()
+        Process.const_set(:CLOCK_MONOTONIC, cm) if cm
+      end
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -41,3 +41,11 @@ RSpec::Matchers.define :be_lockable do |lock_manager, ttl|
     "expected that #{resource_key} would be lockable"
   end
 end
+
+RSpec.configure do |c|
+  # NOTE: this protects against erroneous "focus: true" commits
+  unless ENV['CI'] == 'true'
+    c.filter_run focus: true
+    c.run_all_when_everything_filtered = true
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redlock
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 1.2.1
 platform: ruby
 authors:
 - Leandro Moreira
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-22 00:00:00.000000000 Z
+date: 2020-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -31,39 +31,73 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: coveralls
+  name: connection_pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.13
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.13
+        version: '2.2'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: coveralls
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.1'
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 11.1.2
+        version: 2.3.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 11.1.2
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.1'
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: 11.1.2
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -96,7 +130,6 @@ files:
 - ".travis.yml"
 - CONTRIBUTORS
 - Gemfile
-- Gemfile.lock
 - LICENSE
 - Makefile
 - README.md
@@ -130,8 +163,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2.1
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Distributed lock using Redis written in Ruby.

data/Gemfile.lock

@@ -1,54 +0,0 @@
-PATH
-  remote: .
-  specs:
-    redlock (0.2.2)
-      redis (>= 3.0.0, < 5.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    coveralls (0.8.19)
-      json (>= 1.8, < 3)
-      simplecov (~> 0.12.0)
-      term-ansicolor (~> 1.3)
-      thor (~> 0.19.1)
-      tins (~> 1.6)
-    diff-lcs (1.3)
-    docile (1.1.5)
-    json (2.0.3)
-    rake (11.3.0)
-    redis (4.0.1)
-    rspec (3.5.0)
-      rspec-core (~> 3.5.0)
-      rspec-expectations (~> 3.5.0)
-      rspec-mocks (~> 3.5.0)
-    rspec-core (3.5.4)
-      rspec-support (~> 3.5.0)
-    rspec-expectations (3.5.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-mocks (3.5.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-support (3.5.0)
-    simplecov (0.12.0)
-      docile (~> 1.1.0)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.0)
-    term-ansicolor (1.4.0)
-      tins (~> 1.0)
-    thor (0.19.4)
-    tins (1.13.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  coveralls (~> 0.8.13)
-  rake (~> 11.1, >= 11.1.2)
-  redlock!
-  rspec (~> 3, >= 3.0.0)
-
-BUNDLED WITH
-   1.16.0