redis_cluster 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f4e3f46f9197fb5e41afea6d2b4e0f41af7defbc
-  data.tar.gz: 21e8e6613f409e4d2ea6942cac0c5a44dc855bff
+  metadata.gz: e10ed9adf21d43959b884dd43b59474b469c84cf
+  data.tar.gz: dfab801d69bf40c1d92fdb3f123ba980cc7aeade
 SHA512:
-  metadata.gz: d01fd2610f8e69cec1344105227b0ae007aa60fd066d4f5bc9d77320dbd6eb0b8af6bd524bc4fb9771a3a125cf43b686c4838ac3ec85d414dd7aa9d41a1fdab3
-  data.tar.gz: e8006dabb95bfc9ff141fdf0b8120b308b649e65f3183fe6400ff77c4b655f00d91db5ceb5e4131ebfa48d343afe9dc1ca2f2382db0fb77a84acf379626ef3cf
+  metadata.gz: e0e96edb02ff52f9a4eda36d1e922288a4459669d645ac736a8856a35a4cdbc2ca10b0cc37ab6560b4302eabb2270fe1ead8d9fa4cfb4bea53360ffaab8cae8e
+  data.tar.gz: 80706f7728f362931760c1473bf7f01b68ee7e95953d85da47126170c43d30af0e138e5116179f8e11fd54544e451f8714351a5148b6c17cc071e4a70a42b741

data/.travis.yml

@@ -1,10 +1,10 @@
 language: ruby
 rvm:
+  - 2.4.0
   - 2.3.3
   - 2.2
   - 2.1
   - 2.0
-  - 1.9.3
   - jruby
 before_install:
   - gem update bundler

data/README.md

@@ -2,79 +2,158 @@
 
 ![travis ci](https://travis-ci.org/zhchsf/redis_cluster.svg?branch=master)
 
-First see: [https://redis.io/topics/cluster-tutorial](https://redis.io/topics/cluster-tutorial)
+Support: Ruby 2.0+
 
-RedisCluster for ruby is rewrited from [https://github.com/antirez/redis-rb-cluster](https://github.com/antirez/redis-rb-cluster)
+Redis Cluster is a Redis configuration that allows data to be automatically
+sharded across a number of different nodes. You can find its main documentation
+at https://redis.io/topics/cluster-tutorial.
 
+[`redis-rb`](https://github.com/redis/redis-rb), the most common Redis gem for
+Ruby, doesn't offer Redis Cluster support. This gem works in conjunction with
+redis-rb to add the missing functionality. It's based on [antirez's prototype
+reference implementation](https://github.com/antirez/redis-rb-cluster) (which
+is not maintained).
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add it to your `Gemfile`:
 
 ```ruby
 gem 'redis_cluster'
 ```
 
-And then execute:
+## Usage
 
-    $ bundle
+Initialize `RedisCluster` with an array of Redis Cluster host nodes:
 
-Or install it yourself as:
+```ruby
+rs = RedisCluster.new([
+  {host: '127.0.0.1', port: 7000},
+  {host: '127.0.0.1', port: 7001}
+])
+rs.set "test", 1
+rs.get "test"
+```
 
-    $ gem install redis_cluster
+The library will issue the `CLUSTER SLOTS` command to configured hosts it it
+receives a `MOVED` response, so it's safe to configure it with only a subset of
+the total nodes in the cluster.
 
-## Usage
+### Other options
 
-First you need to configure redis cluster with some nodes! Please see: [https://redis.io/topics/cluster-tutorial](https://redis.io/topics/cluster-tutorial)
+Most options are forwarded onto underlying `Redis` clients. If for example
+`masterauth` and `requirepass` are enabled, the password can be set like this:
 
 ```ruby
-# Don't need all, gem can auto detect all nodes, and process failover if some master nodes down
-hosts = [{host: '127.0.0.1', port: 7000}, {host: '127.0.0.1', port: 7001}]
-rs = RedisCluster.new hosts
-rs.set "test", 1
-rs.get "test"
+RedisCluster.new(hosts, password: 'password')
+```
+
+### Standalone Redis
+
+If initialized with a host hash instead of an array, the library will assume
+that it's operating on a standalone Redis, and cluster functionality will be
+disabled:
+
+```ruby
+rs = RedisCluster.new({host: '127.0.0.1', port: 7000})
 ```
 
-At development environment with single redis node, you can set hosts a hash value: {host: 'xx', port: 6379}.
+When configured with an array of hosts the library normally requires that they
+be part of a Redis Cluster, but that check can be disabled by setting
+`force_cluster: false`. This may be useful for development or test environments
+where a full cluster isn't available, but where a standalone Redis will do just
+as well.
 
-If masterauth & requirepass configed, you can initialize below:
 ```ruby
-RedisCluster.new hosts, password: 'password'
+rs = RedisCluster.new([
+  {host: '127.0.0.1', port: 7000},
+], force_cluster: false)
 ```
 
-now support keys command with scanning all nodes:
+### Logging
+
+A logger can be specified with the `logger` option. It should be compatible
+with the interface of Ruby's `Logger` from the standard library.
+
+```ruby
+require 'logger'
+logger = Logger.new(STDOUT)
+logger.level = Logger::WARN
+RedisCluster.new(hosts, logger: logger)
+```
+
+### `KEYS`
+
+The `KEYS` command will scan all nodes:
+
 ```ruby
 rs.keys 'test*'
 ```
 
-limited support commands: pipelined, multi
+### Pipelining, `MULTI`
+
+There is limited support for pipelining and `MULTI`:
+
 ```ruby
-# Only support pipeline commands to one redis node once
-# You must ensure keys at one slot: use same key or hash tags
-# If you don't, not raise any errors now
 rs.pipelined do
   rs.set "{foo}one", 1
   rs.set "{foo}two", 2
 end
 ```
 
-script, eval, evalsha
+Note that all keys used in a pipeline must map to the same Redis node. This is
+possible through the use of Redis Cluster "hash tags" where only the section of
+a key name wrapped in `{}` when calculating a key's hash.
+
+#### `EVAL`, `EVALSHA`, `SCRIPT`
+
+`EVAL` and `EVALSHA` must only rely on keys that map to a single slot (again,
+possible with hash tags). `KEYS` should be used to retrieve keys in Lua
+scripts.
+
+```ruby
+rs.eval "return redis.call('get', KEYS[1]) + ARGV[1]", [:test], [3]
+rs.evalsha '727fc2fb7c0f11ec134d998654e3dadaacf31a97', [:test], [5]
+
+# Even if a Lua script doesn't need any keys or argvs, you'll still need to
+specify a dummy key.
+rs.eval "return 'hello redis!'", [:foo]
+```
+
+`SCRIPT` commands will run on all nodes:
+
 ```ruby
 # script commands will run on all nodes
 rs.script :load, "return redis.call('get', KEYS[1])"
 rs.script :exists, '4e6d8fc8bb01276962cce5371fa795a7763657ae'
 rs.script :flush
+```
 
-# eval/evalsha must executed at one node with hash tag keys in same slot
-# and must use KEYS to fetch keys in lua script
-rs.eval "return redis.call('get', KEYS[1]) + ARGV[1]", [:test], [3]
-rs.evalsha '727fc2fb7c0f11ec134d998654e3dadaacf31a97', [:test], [5]
+## Development
 
-# if lua script don't depend on any keys and argvs, you also need execute with a key
-rs.eval "return 'hello redis!'", [:foo]
+Clone the repository and then install dependencies:
+
+```sh
+bin/setup
 ```
 
-## Benchmark test
+Run tests:
+
+```sh
+rake spec
+```
+
+`bin/console` will bring up an interactive prompt for other experimentation.
+
+### Releases
+
+To release a new version, update the version number in `version.rb` and run
+`bundle exec rake release`. This will create a Git tag for the version, push
+Git commits and tags to GitHub, and push the `.gem` file to Rubygems.
+
+The gem can be installed locally with `bundle exec rake install`.
+
+### Benchmark test
 
 ```ruby
 Benchmark.bm do |x|
@@ -96,19 +175,18 @@ Benchmark.bm do |x|
 end
 ```
 
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/zhchsf/redis_cluster. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
+Bug reports and pull requests are welcome on GitHub. This project is intended
+to be a safe, welcoming space for collaboration, and contributors are expected
+to adhere to the [Contributor Covenant](http://contributor-covenant.org) code
+of conduct.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT
+License](http://opensource.org/licenses/MIT).
 
+<!--
+# vim: set tw=79:
+-->

data/lib/redis_cluster/client.rb

@@ -4,8 +4,9 @@ module RedisCluster
 
   class Client
 
-    def initialize(startup_hosts, configs = {})
-      @startup_hosts = startup_hosts
+    def initialize(hosts, configs = {})
+      @hosts = hosts.dup
+      @initial_hosts = hosts.dup
 
       # Extract configuration options relevant to Redis Cluster.
 
@@ -13,65 +14,98 @@ module RedisCluster
       # the option existed
       @force_cluster = configs.delete(:force_cluster) { |_key| true }
 
-      # The number of times to retry a failed execute. Redis errors, `MOVE`, or
-      # `ASK` are all considered failures that will count towards this tally. A
-      # count of at least 2 is probably sensible because if a node disappears
-      # the first try will be a Redis error, the second try retry will probably
-      # be a `MOVE` (whereupon the node pool is reloaded), and it will take
-      # until the third try to succeed.
-      @retry_count = configs.delete(:retry_count) { |_key| 3 }
+      # An optional logger. Should respond like the standard Ruby `Logger`:
+      #
+      # http://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html
+      @logger = configs.delete(:logger) { |_key| nil }
+
+      # The number of times to retry when it detects a failure that looks like
+      # it might be intermittent.
+      #
+      # It might be worth setting this to `0` if you'd like full visibility
+      # around what kinds of errors are occurring. Possibly in conjunction with
+      # your own out-of-library retry loop and/or circuit breaker.
+      @retry_count = configs.delete(:retry_count) { |_key| 2 }
 
       # Any leftover configuration goes through to the pool and onto individual
       # Redis clients.
       @pool = Pool.new(configs)
       @mutex = Mutex.new
 
-      reload_pool_nodes(true)
+      reload_pool_nodes
     end
 
     def execute(method, args, &block)
       asking = false
-      last_error = nil
-      retries_left = @retry_count
-      try_random_node = false
-
-      # We use `>= 0` instead of `> 0` because we decrement this counter on the
-      # first run.
-      while retries_left >= 0
-        retries_left -= 1
-
-        begin
-          return @pool.execute(method, args, {asking: asking, random_node: try_random_node}, &block)
-
-        rescue Errno::ECONNREFUSED, Redis::TimeoutError, Redis::CannotConnectError, Errno::EACCES => e
-          last_error = e
-
+      retried = false
+
+      # Note that there are two levels of retry loops here.
+      #
+      # The first is for intermittent failures like "host unreachable" or
+      # timeouts. These are retried a number of times equal to @retry_count.
+      #
+      # The second is when it receives an `ASK` or `MOVED` error response from
+      # Redis. In this case the client will complete re-enter its execution
+      # loop and retry the command after any necessary prework (if `MOVED`, it
+      # will attempt to reload the node pool first). This will only ever be
+      # retried one time (see notes below). This loop uses Ruby's `retry`
+      # syntax for blocks, so keep an eye out for that in the code below.
+      #
+      # It's worth noting that if these conditions ever combine, you could see
+      # more network attempts than @retry_count. An initial execution attempt
+      # might fail intermittently a couple times before sending a `MOVED`. The
+      # client will then attempt to reload the node pool, an operation which is
+      # also retried for intermittent failures. It could then return to the
+      # main execution and fail another couple of times intermittently. This
+      # should be an extreme edge case, but it's worth considering if you're
+      # running at large scale.
+      begin
+        retry_intermittent_loop do |attempt|
           # Getting an error while executing may be an indication that we've
           # lost the node that we were talking to and in that case it makes
           # sense to try a different node and maybe reload our node pool (if
           # the new node issues a `MOVE`).
-          try_random_node = true
+          try_random_node = attempt > 0
 
-        rescue => e
-          last_error = e
+          return @pool.execute(method, args, {asking: asking, random_node: try_random_node}, &block)
+        end
+      rescue Redis::CommandError => e
+        unless @logger.nil?
+          @logger.error("redis_cluster: Received error: #{e}")
+        end
+
+        # This is a special condition to protect against a misbehaving library
+        # or server. After we've gotten one ASK or MOVED and retried once,
+        # we'll never do so a second time. Receiving two of any operations in a
+        # row is probably indicative of a problem and we don't want to get
+        # stuck in an infinite retry loop.
+        raise if retried
+        retried = true
+
+        err_code = e.to_s.split.first
+        case err_code
+        when 'ASK'
+          unless @logger.nil?
+            @logger.info("redis_cluster: Received ASK; retrying operation (#{e})")
+          end
 
-          err_code = e.to_s.split.first
-          raise e unless %w(MOVED ASK).include?(err_code)
+          asking = true
+          retry
 
-          if err_code == 'ASK'
-            asking = true
-          else
-            # `MOVED` indicates a permanent redirect which means that our slot
-            # mappings are stale: reload them.
-            reload_pool_nodes(false)
+        when 'MOVED'
+          unless @logger.nil?
+            @logger.info("redis_cluster: Received MOVED; retrying operation (#{e})")
           end
+
+          # `MOVED` indicates a permanent redirect which means that our slot
+          # mappings are stale: reload them then try what we were doing again
+          reload_pool_nodes
+          retry
+
+        else
+          raise
         end
       end
-
-      # If we ran out of retries (the maximum number may have been set to 0),
-      # surface any error that was thrown back to the caller. We'd otherwise
-      # suppress the error, which would return something quite unexpected.
-      raise last_error
     end
 
     Configuration.method_names.each do |method_name|
@@ -84,13 +118,31 @@ module RedisCluster
       execute(method, args, &block)
     end
 
+    # Closes all open connections and reloads the client pool.
+    #
+    # Normally host information from the last time the node pool was reloaded
+    # is used, but if the `use_initial_hosts` is set to `true`, then the client
+    # is completely refreshed and the hosts that were specified when creating
+    # it originally are set instead.
+    def reconnect(options = {})
+      use_initial_hosts = options.fetch(:use_initial_hosts, false)
+
+      @hosts = @initial_hosts.dup if use_initial_hosts
+
+      @mutex.synchronize do
+        @pool.nodes.each{|node| node.connection.close}
+        @pool.nodes.clear
+        reload_pool_nodes_unsync
+      end
+    end
+
     private
 
     # Adds only a single node to the client pool and sets it result for the
     # entire space of slots. This is useful when running either a standalone
     # Redis or a single-node Redis Cluster.
     def create_single_node_pool
-      host = @startup_hosts
+      host = @hosts
       if host.is_a?(Array)
         if host.length > 1
           raise ArgumentError, "Can only create single node pool for single host"
@@ -102,15 +154,22 @@ module RedisCluster
       end
 
       @pool.add_node!(host, [(0..Configuration::HASH_SLOTS)])
+
+      unless @logger.nil?
+        @logger.info("redis_cluster: Initialized single node pool: #{host}")
+      end
     end
 
-    def create_multi_node_pool(raise_error)
-      unless @startup_hosts.is_a?(Array)
+    def create_multi_node_pool
+      unless @hosts.is_a?(Array)
         raise ArgumentError, "Can only create multi-node pool for multiple hosts"
       end
 
-      @startup_hosts.each do |options|
-        begin
+      begin
+        retry_intermittent_loop do |attempt|
+          # Try a random host from our seed pool.
+          options = @hosts.sample
+
           redis = Node.redis(@pool.global_configs.merge(options))
           slots_mapping = redis.cluster("slots").group_by{|x| x[2]}
           @pool.delete_except!(slots_mapping.keys)
@@ -118,32 +177,27 @@ module RedisCluster
             slots_ranges = infos.map {|x| x[0]..x[1] }
             @pool.add_node!({host: host[0], port: host[1]}, slots_ranges)
           end
-        rescue Redis::CommandError => e
-          if e.message =~ /cluster\ support\ disabled$/
-            if !@force_cluster
-              # We're running outside of cluster-mode -- just create a
-              # single-node pool and move on. The exception is if we've been
-              # asked for force Redis Cluster, in which case we assume this is
-              # a configuration problem and maybe raise an error.
-              create_single_node_pool
-              return
-            elsif raise_error
-              raise e
-            end
-          end
-
-          raise e if e.message =~ /NOAUTH\ Authentication\ required/
+        end
+      rescue Redis::CommandError => e
+        unless @logger.nil?
+          @logger.error("redis_cluster: Received error: #{e}")
+        end
 
-          # TODO: log error for visibility
-          next
-        rescue
-          # TODO: log error for visibility
-          next
+        if e.message =~ /cluster\ support\ disabled$/ && !@force_cluster
+          # We're running outside of cluster-mode -- just create a single-node
+          # pool and move on. The exception is if we've been asked for force
+          # Redis Cluster, in which case we assume this is a configuration
+          # problem and maybe raise an error.
+          create_single_node_pool
+          return
         end
 
-        # We only need to see a `CLUSTER SLOTS` result from a single host, so
-        # break after one success.
-        break
+        raise
+      end
+
+      unless @logger.nil?
+        mappings = @pool.nodes.map{|node| "#{node.slots} -> #{node.options}"}
+        @logger.info("redis_cluster: Initialized multi-node pool: #{mappings}")
       end
     end
 
@@ -151,23 +205,56 @@ module RedisCluster
     # SLOTS` or just adding a node directly if running on standalone. Clients
     # are "upserted" so that we don't necessarily drop clients that are still
     # relevant.
-    def reload_pool_nodes(raise_error)
+    def reload_pool_nodes
       @mutex.synchronize do
-        if @startup_hosts.is_a?(Array)
-          create_multi_node_pool(raise_error)
-          refresh_startup_nodes
-        else
-          create_single_node_pool
-        end
+        reload_pool_nodes_unsync
       end
     end
 
-    # Refreshes the contents of @startup_hosts based on the hosts currently in
+    # The same as `#reload_pool_nodes`, but doesn't attempt to synchronize on
+    # the mutex. Use this only if you've already got a lock on it.
+    def reload_pool_nodes_unsync
+      if @hosts.is_a?(Array)
+        create_multi_node_pool
+        refresh_startup_nodes
+      else
+        create_single_node_pool
+      end
+    end
+
+    # Refreshes the contents of @hosts based on the hosts currently in
     # the client pool. This is useful because we may have been told about new
     # hosts after running `CLUSTER SLOTS`.
     def refresh_startup_nodes
-      @pool.nodes.each {|node| @startup_hosts.push(node.host_hash) }
-      @startup_hosts.uniq!
+      @pool.nodes.each {|node| @hosts.push(node.host_hash) }
+      @hosts.uniq!
+    end
+
+    # Retries an operation @retry_count times for intermittent connection
+    # errors. After exhausting retries, the error that was received on the last
+    # attempt is raised to the user.
+    def retry_intermittent_loop
+      last_error = nil
+
+      for attempt in 0..(@retry_count) do
+        begin
+          yield(attempt)
+
+          # Fall through on any success.
+          return
+        rescue Errno::EACCES, Redis::TimeoutError, Redis::CannotConnectError => e
+          last_error = e
+
+          unless @logger.nil?
+            @logger.error("redis_cluster: Received error: #{e} retries_left=#{@retry_count - attempt}")
+          end
+        end
+      end
+
+      # If we ran out of retries (the maximum number may have been set to 0),
+      # surface any error that was thrown back to the caller. We'd otherwise
+      # suppress the error, which would return something quite unexpected.
+      raise last_error
     end
 
   end # end client

data/lib/redis_cluster/node.rb

@@ -1,6 +1,8 @@
 module RedisCluster
 
   class Node
+    attr_accessor :options
+
     # slots is a range array: [1..100, 300..500]
     attr_accessor :slots
 
@@ -35,7 +37,7 @@ module RedisCluster
     end
 
     def connection
-      @connection ||= self.class.redis(@options)
+      @connection ||= self.class.redis(options)
     end
 
     def self.redis(options)

data/lib/redis_cluster/version.rb

@@ -1,3 +1,3 @@
 module RedisCluster
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_cluster
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - wangzc
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-16 00:00:00.000000000 Z
+date: 2018-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -142,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
 summary: redis cluster client