redis-cluster-client 0.16.5 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee5d5f4c7bb89d0899ef2c3aec48503580d01a1e84a369f1e9ee0c1f60011f15
-  data.tar.gz: b17966f3f4c74ce89005b49188d769c4e8b6e399d6d65e0c4d68e14868cee9c7
+  metadata.gz: 7df1ba6006c9d3c3e7c242e9406f6443a95aa371c7e77244b73565058f476435
+  data.tar.gz: 5613bf92dc543482c1bcb2e74d61096092c299ef84877b8c06da1174db82c6d4
 SHA512:
-  metadata.gz: 580dbda062e93296be5869169a3f8f4d389f7bc7aba34cb473cc1a1877cd8a552a29617bf6e09cc2bea8e372cbf895f28ffd086bf75ce986a2dd448bd7170dae
-  data.tar.gz: d3abefad63034a97613319637fe617b66f64b2053f67ed8c6de7d81350976645c0eec250037fd100b0a4d5e518c3674c96e07fb043c56ffd327a8e918626405d
+  metadata.gz: 58e9ecaa1aecf6bfb298cba78e08d349f742439a2f5a53e19cd55bb49c8a600b4e4f47a54af1798ef0afe51cb56cf5cf292eda3bdf75e522ed180fa065e37954
+  data.tar.gz: c158336f83f4453e27798a2521c4e282a867db446dfa7e74e988af9e568567235b321b59386bf79ac5d0e32dee0698137755e9c416ceeb3acb150ebfc60d5208

data/lib/redis_client/cluster/command.rb

@@ -9,15 +9,24 @@ class RedisClient
     class Command
       EMPTY_STRING = ''
       EMPTY_HASH = {}.freeze
+      REQUEST_POLICY_PREFIX = 'request_policy:'
+      RESPONSE_POLICY_PREFIX = 'response_policy:'
+      SUBCOMMAND_DELIMITER = '|'
 
-      private_constant :EMPTY_HASH
+      private_constant :EMPTY_HASH, :REQUEST_POLICY_PREFIX,
+                       :RESPONSE_POLICY_PREFIX, :SUBCOMMAND_DELIMITER
 
+      # @see https://redis.io/docs/latest/commands/command/ The reply of the COMMAND command
+      # @see https://redis.io/docs/latest/develop/reference/command-tips/ Command tips
       Spec = Struct.new(
         'RedisCommandSpec',
         :first_key_position,
         :key_step,
         :write?,
         :readonly?,
+        :request_policy,
+        :response_policy,
+        :subcommands,
         keyword_init: true
       ) do
         def extract_first_key(command)
@@ -86,40 +95,80 @@ class RedisClient
 
         private
 
-        def parse_command_reply(rows) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+        def parse_command_reply(rows)
           rows&.each_with_object({}) do |row, acc|
             next if row.first.nil?
 
-            # TODO: in redis 7.0 or later, subcommand information included in the command reply
-
-            pos = case row.first
-                  when 'eval', 'evalsha', 'zinterstore', 'zunionstore' then 3
-                  when 'object', 'xgroup' then 2
-                  when 'migrate', 'xread', 'xreadgroup' then 0
-                  else row[3]
-                  end
-
-            writable = case row.first
-                       when 'xgroup' then true
-                       else row[2].include?('write')
-                       end
-
-            acc[row.first] = ::RedisClient::Cluster::Command::Spec.new(
-              first_key_position: pos,
-              key_step: row[5],
-              write?: writable,
-              readonly?: row[2].include?('readonly')
-            ).freeze
+            acc[row.first] = build_spec(row)
           end.freeze || EMPTY_HASH
         end
+
+        def build_spec(row)
+          ::RedisClient::Cluster::Command::Spec.new(
+            first_key_position: parse_first_key_position(row),
+            key_step: row[5],
+            write?: parse_writability(row),
+            readonly?: row[2].include?('readonly'),
+            request_policy: parse_policy_tip(row[7], REQUEST_POLICY_PREFIX),
+            response_policy: parse_policy_tip(row[7], RESPONSE_POLICY_PREFIX),
+            subcommands: parse_subcommands(row[9])
+          ).freeze
+        end
+
+        # The redis 6.2 or earlier doesn't include the information of the subcommands in the reply.
+        # These hard-coded positions are the fallback for such old versions.
+        def parse_first_key_position(row)
+          case row.first
+          when 'eval', 'evalsha', 'zinterstore', 'zunionstore' then 3
+          when 'object', 'xgroup' then 2
+          when 'migrate', 'xread', 'xreadgroup' then 0
+          else row[3]
+          end
+        end
+
+        def parse_writability(row)
+          case row.first
+          when 'xgroup' then true
+          else row[2].include?('write')
+          end
+        end
+
+        # The command tips are available in the redis 7.0 or later.
+        # It returns a single value instead of a pair to avoid the allocation of the array.
+        def parse_policy_tip(tips, prefix)
+          tip = tips&.find { |t| t.start_with?(prefix) }
+          tip.nil? ? nil : -tip.delete_prefix(prefix)
+        end
+
+        # The information of the subcommands is available in the redis 7.0 or later.
+        # A container command such as XINFO reports its key positions per subcommand.
+        def parse_subcommands(rows)
+          return if rows.nil? || rows.empty?
+
+          rows.each_with_object({}) do |row, acc|
+            name = row.first
+            next if name.nil?
+
+            # The server replies with a full name of the subcommand such as `xinfo|stream`.
+            i = name.index(SUBCOMMAND_DELIMITER)
+            acc[i.nil? ? name : name[i + 1, name.size]] = build_spec(row)
+          end.freeze
+        end
       end
 
       def initialize(commands)
         @commands = commands || EMPTY_HASH
       end
 
-      def get_spec(name)
-        @commands[name] || @commands[name.to_s.downcase(:ascii)]
+      def get_spec(command) # rubocop:disable Metrics/AbcSize
+        name = command.first
+        spec = @commands[name] || @commands[name.to_s.downcase(:ascii)]
+        return spec if spec.nil? || spec.subcommands.nil?
+
+        subcommand = command[1]
+        return spec if subcommand.nil?
+
+        spec.subcommands[subcommand] || spec.subcommands[subcommand.to_s.downcase(:ascii)] || spec
       end
 
       def exists?(name)

data/lib/redis_client/cluster/node.rb

@@ -141,6 +141,16 @@ class RedisClient
         call_multiple_nodes!(@topology.replica_clients, method, command, args, &block)
       end
 
+      # for the `response_policy:one_succeeded` command tip
+      def call_all_leniently(method, command, args, &block)
+        call_multiple_nodes_leniently(@topology.clients, method, command, args, &block)
+      end
+
+      # for the `response_policy:one_succeeded` command tip
+      def call_primaries_leniently(method, command, args, &block)
+        call_multiple_nodes_leniently(@topology.primary_clients, method, command, args, &block)
+      end
+
       def send_ping(method, command, args, &block)
         result_values, errors = call_multiple_nodes(@topology.clients, method, command, args, &block)
         return result_values if errors.nil? || errors.empty?
@@ -265,6 +275,13 @@ class RedisClient
         raise ::RedisClient::Cluster::ErrorCollection.with_errors(errors)
       end
 
+      def call_multiple_nodes_leniently(clients, method, command, args, &block)
+        result_values, errors = call_multiple_nodes(clients, method, command, args, &block)
+        return result_values unless result_values.nil? || result_values.empty?
+
+        raise ::RedisClient::Cluster::ErrorCollection.with_errors(errors)
+      end
+
       def try_map(clients, &block) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         return [{}, {}] if clients.empty?
 
@@ -403,7 +420,7 @@ class RedisClient
           shard = shard.each_slice(2).to_h if resp2
           nodes = shard.fetch('nodes')
           nodes = nodes.map { |n| n.each_slice(2).to_h } if resp2
-          primary_id = nodes.find { |n| n.fetch('role') == 'master' }.fetch('id')
+          primary_id = nodes.find { |n| n.fetch('role') == 'master' }&.fetch('id') || EMPTY_STRING
 
           nodes.each do |node|
             host = pick_shard_host(node)

data/lib/redis_client/cluster/node_key.rb

@@ -26,7 +26,7 @@ class RedisClient
         pos = node_key.rindex(DELIMITER, -1)
         return [node_key, nil] if pos.nil?
 
-        [node_key[0, pos], node_key[(pos + 1)..]]
+        [node_key[0, pos], node_key[pos + 1, node_key.size]]
       end
 
       def split_bracketed(node_key)
@@ -36,7 +36,7 @@ class RedisClient
         return nil if end_bracket.nil?
 
         host = node_key[1, end_bracket - 1]
-        remainder = node_key[(end_bracket + 1)..]
+        remainder = node_key[end_bracket + 1, node_key.size]
         port = remainder.start_with?(DELIMITER) ? remainder[1..] : nil
         [host, port]
       end

data/lib/redis_client/cluster/router/routing_table.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'redis_client/cluster/errors'
+
+class RedisClient
+  class Cluster
+    class Router
+      # The routing table for the commands which shouldn't be routed by their keys.
+      # The built-in entries can be overridden with the `command_routings` option of the config.
+      class RoutingTable
+        BuildError = Class.new(::RedisClient::Cluster::Error)
+        RoutingAction = Struct.new('RedisCommandRoutingAction', :method_name, :reply_transformer, keyword_init: true)
+        PICK_FIRST = ->(reply) { reply.first } # rubocop:disable Style/SymbolProc
+        FLATTEN_STRINGS = ->(reply) { reply.flatten.sort_by(&:to_s) }
+        SUM_NUM = ->(reply) { reply.select { |e| e.is_a?(Integer) }.sum }
+        SORT_NUMBERS = ->(reply) { reply.sort_by(&:to_i) }
+        if Object.const_defined?(:Ractor, false) && Ractor.respond_to?(:make_shareable)
+          Ractor.make_shareable(PICK_FIRST)
+          Ractor.make_shareable(FLATTEN_STRINGS)
+          Ractor.make_shareable(SUM_NUM)
+          Ractor.make_shareable(SORT_NUMBERS)
+        end
+        DEDICATED_ACTIONS = lambda do # rubocop:disable Metrics/BlockLength
+          multiple_key_action = RoutingAction.new(method_name: :send_multiple_keys_command)
+          all_node_first_action = RoutingAction.new(method_name: :send_command_to_all_nodes, reply_transformer: PICK_FIRST)
+          primary_first_action = RoutingAction.new(method_name: :send_command_to_primaries, reply_transformer: PICK_FIRST)
+          not_supported_action = RoutingAction.new(method_name: :fail_not_supported_command)
+          keyless_action = RoutingAction.new(method_name: :fail_keyless_command)
+          single_node_action = RoutingAction.new(method_name: :assign_node_and_send_command)
+          {
+            'ping' => RoutingAction.new(method_name: :send_ping_command, reply_transformer: PICK_FIRST),
+            'wait' => RoutingAction.new(method_name: :send_wait_command),
+            'keys' => RoutingAction.new(method_name: :send_command_to_replicas, reply_transformer: FLATTEN_STRINGS),
+            'dbsize' => RoutingAction.new(method_name: :send_command_to_replicas, reply_transformer: SUM_NUM),
+            'scan' => RoutingAction.new(method_name: :send_scan_command),
+            'lastsave' => RoutingAction.new(method_name: :send_command_to_all_nodes, reply_transformer: SORT_NUMBERS),
+            'role' => RoutingAction.new(method_name: :send_command_to_all_nodes),
+            'config' => RoutingAction.new(method_name: :send_config_command),
+            'client' => RoutingAction.new(method_name: :send_client_command),
+            'cluster' => RoutingAction.new(method_name: :send_cluster_command),
+            'memory' => RoutingAction.new(method_name: :send_memory_command),
+            'script' => RoutingAction.new(method_name: :send_script_command),
+            'pubsub' => RoutingAction.new(method_name: :send_pubsub_command),
+            'watch' => RoutingAction.new(method_name: :send_watch_command),
+            'mget' => multiple_key_action,
+            'mset' => multiple_key_action,
+            'del' => multiple_key_action,
+            'acl' => all_node_first_action,
+            'auth' => all_node_first_action,
+            'bgrewriteaof' => all_node_first_action,
+            'bgsave' => all_node_first_action,
+            'quit' => all_node_first_action,
+            'save' => all_node_first_action,
+            'select' => all_node_first_action,
+            'flushall' => primary_first_action,
+            'flushdb' => primary_first_action,
+            # The redis 7.0 tags RANDOMKEY with `request_policy:all_shards` but without any response policy.
+            # It was corrected to `response_policy:special` in the redis 7.2.
+            # This entry keeps the historical single node routing for the redis 7.0.
+            'randomkey' => single_node_action,
+            'readonly' => not_supported_action,
+            'readwrite' => not_supported_action,
+            'shutdown' => not_supported_action,
+            'discard' => keyless_action,
+            'exec' => keyless_action,
+            'multi' => keyless_action,
+            'unwatch' => keyless_action
+          }.each_with_object({}) do |(k, v), acc|
+            acc[k] = v.freeze
+            acc[k.upcase] = v.freeze
+          end
+        end.call.freeze
+
+        # The routing which the command tips of the COMMAND command reply instruct.
+        # The `multi_shard` and the `special` request policies are out of scope.
+        # The `special` response policy is also out of scope because the aggregation is undefined,
+        # and the fan-out would change the return value of commands such as INFO.
+        # The `agg_min`, `agg_max` and `agg_logical_*` response policies are out of scope too:
+        # the only reachable command with them today is WAITAOF, whose reply is an array,
+        # and the aggregation of array replies is undefined. Such a command falls back to
+        # the single node routing until a command with a settled semantics appears.
+        # The entries of the DEDICATED_ACTIONS take precedence over these to keep the existing behavior.
+        # @see https://redis.io/docs/latest/develop/reference/command-tips/
+        POLICY_ACTIONS = {
+          'all_shards' => {
+            nil => RoutingAction.new(method_name: :send_command_to_primaries).freeze,
+            'all_succeeded' => RoutingAction.new(method_name: :send_command_to_primaries, reply_transformer: PICK_FIRST).freeze,
+            'one_succeeded' => RoutingAction.new(method_name: :send_command_to_primaries_leniently, reply_transformer: PICK_FIRST).freeze,
+            'agg_sum' => RoutingAction.new(method_name: :send_command_to_primaries, reply_transformer: SUM_NUM).freeze
+          }.freeze,
+          'all_nodes' => {
+            nil => RoutingAction.new(method_name: :send_command_to_all_nodes).freeze,
+            'all_succeeded' => RoutingAction.new(method_name: :send_command_to_all_nodes, reply_transformer: PICK_FIRST).freeze,
+            'one_succeeded' => RoutingAction.new(method_name: :send_command_to_all_nodes_leniently, reply_transformer: PICK_FIRST).freeze,
+            'agg_sum' => RoutingAction.new(method_name: :send_command_to_all_nodes, reply_transformer: SUM_NUM).freeze
+          }.freeze
+        }.freeze
+
+        private_constant :RoutingAction, :PICK_FIRST, :FLATTEN_STRINGS, :SUM_NUM, :SORT_NUMBERS,
+                         :DEDICATED_ACTIONS, :POLICY_ACTIONS
+
+        class << self
+          # Builds the routing table: the built-in entries overridden by the command routings
+          # which the config validated and normalized. A nil routing removes the built-in entry
+          # of the command, so that the command follows the default resolution: the command tips
+          # which the server reports, or the routing by its key.
+          # It raises a BuildError for an unnormalized input as a defense, e.g. an unsupported policy.
+          def build(routings)
+            return DEDICATED_ACTIONS if routings.nil? || routings.empty?
+
+            routings.each_with_object(DEDICATED_ACTIONS.dup) do |(key, policies), acc|
+              merge_action(acc, key, fetch_action(key, policies))
+            end.freeze
+          end
+
+          def find_policy_action(request_policy, response_policy)
+            POLICY_ACTIONS.dig(request_policy, response_policy)
+          end
+
+          private
+
+          # Stores both the lowercase and the uppercase keys to avoid a per-call case conversion.
+          def merge_action(table, key, action)
+            if action.nil?
+              table.delete(key)
+              table.delete(key.upcase)
+            else
+              table[key] = action
+              table[key.upcase] = action
+            end
+          end
+
+          def fetch_action(key, policies)
+            return if policies.nil?
+
+            action = POLICY_ACTIONS.dig(policies[:request_policy], policies[:response_policy])
+            return action unless action.nil?
+
+            raise BuildError, "the policies of the #{key} command are unsupported: #{policies.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/redis_client/cluster/router.rb

@@ -11,75 +11,20 @@ require 'redis_client/cluster/transaction'
 require 'redis_client/cluster/optimistic_locking'
 require 'redis_client/cluster/pipeline'
 require 'redis_client/cluster/error_identification'
+require 'redis_client/cluster/router/routing_table'
 
 class RedisClient
   class Cluster
     class Router
       ZERO_CURSOR_FOR_SCAN = '0'
       TSF = ->(f, x) { f.nil? ? x : f.call(x) }.curry
-      DEDICATED_ACTIONS = lambda do # rubocop:disable Metrics/BlockLength
-        action = Struct.new('RedisCommandRoutingAction', :method_name, :reply_transformer, keyword_init: true)
-        pick_first = ->(reply) { reply.first } # rubocop:disable Style/SymbolProc
-        flatten_strings = ->(reply) { reply.flatten.sort_by(&:to_s) }
-        sum_num = ->(reply) { reply.select { |e| e.is_a?(Integer) }.sum }
-        sort_numbers = ->(reply) { reply.sort_by(&:to_i) }
-        if Object.const_defined?(:Ractor, false) && Ractor.respond_to?(:make_shareable)
-          Ractor.make_shareable(pick_first)
-          Ractor.make_shareable(flatten_strings)
-          Ractor.make_shareable(sum_num)
-          Ractor.make_shareable(sort_numbers)
-        end
-        multiple_key_action = action.new(method_name: :send_multiple_keys_command)
-        all_node_first_action = action.new(method_name: :send_command_to_all_nodes, reply_transformer: pick_first)
-        primary_first_action = action.new(method_name: :send_command_to_primaries, reply_transformer: pick_first)
-        not_supported_action = action.new(method_name: :fail_not_supported_command)
-        keyless_action = action.new(method_name: :fail_keyless_command)
-        {
-          'ping' => action.new(method_name: :send_ping_command, reply_transformer: pick_first),
-          'wait' => action.new(method_name: :send_wait_command),
-          'keys' => action.new(method_name: :send_command_to_replicas, reply_transformer: flatten_strings),
-          'dbsize' => action.new(method_name: :send_command_to_replicas, reply_transformer: sum_num),
-          'scan' => action.new(method_name: :send_scan_command),
-          'lastsave' => action.new(method_name: :send_command_to_all_nodes, reply_transformer: sort_numbers),
-          'role' => action.new(method_name: :send_command_to_all_nodes),
-          'config' => action.new(method_name: :send_config_command),
-          'client' => action.new(method_name: :send_client_command),
-          'cluster' => action.new(method_name: :send_cluster_command),
-          'memory' => action.new(method_name: :send_memory_command),
-          'script' => action.new(method_name: :send_script_command),
-          'pubsub' => action.new(method_name: :send_pubsub_command),
-          'watch' => action.new(method_name: :send_watch_command),
-          'mget' => multiple_key_action,
-          'mset' => multiple_key_action,
-          'del' => multiple_key_action,
-          'acl' => all_node_first_action,
-          'auth' => all_node_first_action,
-          'bgrewriteaof' => all_node_first_action,
-          'bgsave' => all_node_first_action,
-          'quit' => all_node_first_action,
-          'save' => all_node_first_action,
-          'select' => all_node_first_action,
-          'flushall' => primary_first_action,
-          'flushdb' => primary_first_action,
-          'readonly' => not_supported_action,
-          'readwrite' => not_supported_action,
-          'shutdown' => not_supported_action,
-          'discard' => keyless_action,
-          'exec' => keyless_action,
-          'multi' => keyless_action,
-          'unwatch' => keyless_action
-        }.each_with_object({}) do |(k, v), acc|
-          acc[k] = v.freeze
-          acc[k.upcase] = v.freeze
-        end
-      end.call.freeze
-
-      private_constant :ZERO_CURSOR_FOR_SCAN, :TSF, :DEDICATED_ACTIONS
+      private_constant :ZERO_CURSOR_FOR_SCAN, :TSF
 
       attr_reader :config
 
       def initialize(config, concurrent_worker, pool: nil, **kwargs)
         @config = config
+        @dedicated_actions = RoutingTable.build(config.command_routings)
         @concurrent_worker = concurrent_worker
         @pool = pool
         @client_kwargs = kwargs
@@ -93,8 +38,13 @@ class RedisClient
       end
 
       def send_command(method, command, *args, &block) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        action = DEDICATED_ACTIONS[command.first]
-        return assign_node_and_send_command(method, command, args, &block) if action.nil?
+        action = @dedicated_actions[command.first]
+        if action.nil?
+          cmd_spec = @command.get_spec(command)
+          action = find_policy_action(cmd_spec)
+          return assign_node_and_send_command(method, command, args, cmd_spec: cmd_spec, &block) if action.nil?
+        end
+
         return send(action.method_name, method, command, args, &block) if action.reply_transformer.nil?
 
         reply = send(action.method_name, method, command, args)
@@ -124,8 +74,8 @@ class RedisClient
       end
 
       # @see https://redis.io/docs/reference/cluster-spec/#redirection-and-resharding Redirection and resharding
-      def assign_node_and_send_command(method, command, args, retry_count: 3, &block)
-        node = assign_node(command)
+      def assign_node_and_send_command(method, command, args, retry_count: 3, cmd_spec: nil, &block)
+        node = assign_node(command, cmd_spec: cmd_spec)
         send_command_to_node(node, method, command, args, retry_count: retry_count, &block)
       end
 
@@ -218,9 +168,9 @@ class RedisClient
         end
       end
 
-      def assign_node(command)
+      def assign_node(command, cmd_spec: nil)
         handle_node_reload_error do
-          node_key = find_node_key(command)
+          node_key = find_node_key(command, cmd_spec: cmd_spec)
           @node.find_by(node_key)
         end
       end
@@ -246,8 +196,8 @@ class RedisClient
         end
       end
 
-      def find_node_key(command, seed: nil)
-        cmd_spec = @command.get_spec(command.first)
+      def find_node_key(command, seed: nil, cmd_spec: nil)
+        cmd_spec = @command.get_spec(command) if cmd_spec.nil?
         find_node_key_by_key(
           cmd_spec&.extract_first_key(command),
           seed: seed,
@@ -256,14 +206,14 @@ class RedisClient
       end
 
       def find_primary_node_key(command)
-        key = @command.get_spec(command.first)&.extract_first_key(command)
+        key = @command.get_spec(command)&.extract_first_key(command)
         return unless key&.size&.> 0
 
         find_node_key_by_key(key, primary: true)
       end
 
       def find_slot(command)
-        find_slot_by_key(@command.get_spec(command.first)&.extract_first_key(command))
+        find_slot_by_key(@command.get_spec(command)&.extract_first_key(command))
       end
 
       def find_slot_by_key(key)
@@ -308,6 +258,15 @@ class RedisClient
 
       private
 
+      def find_policy_action(cmd_spec)
+        return if cmd_spec.nil?
+
+        request_policy = cmd_spec.request_policy
+        return if request_policy.nil?
+
+        RoutingTable.find_policy_action(request_policy, cmd_spec.response_policy)
+      end
+
       def send_command_to_all_nodes(method, command, args, &block)
         @node.call_all(method, command, args, &block)
       end
@@ -316,6 +275,14 @@ class RedisClient
         @node.call_primaries(method, command, args, &block)
       end
 
+      def send_command_to_all_nodes_leniently(method, command, args, &block)
+        @node.call_all_leniently(method, command, args, &block)
+      end
+
+      def send_command_to_primaries_leniently(method, command, args, &block)
+        @node.call_primaries_leniently(method, command, args, &block)
+      end
+
       def send_command_to_replicas(method, command, args, &block)
         @node.call_replicas(method, command, args, &block)
       end

data/lib/redis_client/cluster_config.rb

@@ -6,6 +6,7 @@ require 'redis_client/cluster'
 require 'redis_client/cluster/errors'
 require 'redis_client/cluster/node_key'
 require 'redis_client/cluster/noop_command_builder'
+require 'redis_client/cluster/router/routing_table'
 require 'redis_client/command_builder'
 
 class RedisClient
@@ -25,10 +26,18 @@ class RedisClient
     SLOW_COMMAND_TIMEOUT = Float(ENV.fetch('REDIS_CLIENT_SLOW_COMMAND_TIMEOUT', -1))
     # Controls the balance between startup load and stability during initialization or cluster state changes.
     MAX_STARTUP_SAMPLE = Integer(ENV.fetch('REDIS_CLIENT_MAX_STARTUP_SAMPLE', 3))
+    VALID_COMMAND_ROUTING_KEYS = %i[request_policy response_policy].freeze
+    # Routing these could wedge the state of the connections in the pool,
+    # e.g. leave them inside a MULTI or a subscription.
+    UNSAFE_COMMAND_ROUTINGS = %w[
+      multi exec discard watch unwatch
+      subscribe unsubscribe psubscribe punsubscribe ssubscribe sunsubscribe
+    ].freeze
 
     private_constant :DEFAULT_HOST, :DEFAULT_PORT, :DEFAULT_SCHEME, :SECURE_SCHEME, :DEFAULT_NODES,
                      :VALID_SCHEMES, :VALID_NODES_KEYS, :MERGE_CONFIG_KEYS, :IGNORE_GENERIC_CONFIG_KEYS,
-                     :MAX_WORKERS, :SLOW_COMMAND_TIMEOUT, :MAX_STARTUP_SAMPLE
+                     :MAX_WORKERS, :SLOW_COMMAND_TIMEOUT, :MAX_STARTUP_SAMPLE,
+                     :VALID_COMMAND_ROUTING_KEYS, :UNSAFE_COMMAND_ROUTINGS
 
     InvalidClientConfigError = Class.new(::RedisClient::Cluster::Error)
 
@@ -39,9 +48,9 @@ class RedisClient
     private_constant :SENSITIVE_INSPECT_KEYS, :INSPECT_REDACTED_KEYS, :INSPECT_PLACEHOLDER
 
     attr_reader :command_builder, :client_config, :replica_affinity, :slow_command_timeout,
-                :connect_with_original_config, :startup_nodes, :max_startup_sample, :id
+                :connect_with_original_config, :startup_nodes, :max_startup_sample, :id, :command_routings
 
-    def initialize( # rubocop:disable Metrics/ParameterLists
+    def initialize( # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize
       nodes: DEFAULT_NODES,
       replica: false,
       replica_affinity: :random,
@@ -52,6 +61,7 @@ class RedisClient
       slow_command_timeout: SLOW_COMMAND_TIMEOUT,
       command_builder: ::RedisClient::CommandBuilder,
       max_startup_sample: MAX_STARTUP_SAMPLE,
+      command_routings: nil,
       **client_config
     )
       @replica = true & replica
@@ -67,6 +77,7 @@ class RedisClient
       @client_implementation = client_implementation
       @slow_command_timeout = slow_command_timeout
       @max_startup_sample = max_startup_sample
+      @command_routings = normalize_command_routings(command_routings)
       @id = client_config[:id]
     end
 
@@ -197,6 +208,52 @@ class RedisClient
       raise InvalidClientConfigError, e.message
     end
 
+    def normalize_command_routings(routings)
+      return if routings.nil? || (routings.is_a?(Hash) && routings.empty?)
+      raise InvalidClientConfigError, "`command_routings` option must be a Hash: #{routings.class}" unless routings.is_a?(Hash)
+
+      routings.each_with_object({}) do |(name, value), acc|
+        acc[normalize_command_routing_name(name)] = normalize_command_routing_value(name, value)
+      end.freeze
+    end
+
+    def normalize_command_routing_name(name)
+      raise InvalidClientConfigError, "`command_routings` option includes an invalid command name: #{name.inspect}" unless name.is_a?(String) || name.is_a?(Symbol)
+
+      key = name.to_s.downcase
+      raise InvalidClientConfigError, '`command_routings` option includes an empty command name' if key.empty?
+      raise InvalidClientConfigError, "`command_routings` option can route a command, not a subcommand: #{name.inspect}" if key.match?(/\s/)
+      raise InvalidClientConfigError, "`command_routings` option can't route the command which changes the state of a connection: #{key}" if UNSAFE_COMMAND_ROUTINGS.include?(key)
+
+      -key
+    end
+
+    def normalize_command_routing_value(name, value)
+      return if value.nil? || (value.is_a?(Hash) && value.empty?)
+      raise InvalidClientConfigError, "`command_routings` option includes an invalid routing of #{name}: #{value.inspect}" unless value.is_a?(Hash)
+
+      normalize_command_routing_policies(name, value.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k })
+    end
+
+    def normalize_command_routing_policies(name, policies)
+      unknown_keys = policies.keys - VALID_COMMAND_ROUTING_KEYS
+      raise InvalidClientConfigError, "`command_routings` option includes unknown keys of #{name}: #{unknown_keys.join(', ')}" unless unknown_keys.empty?
+      raise InvalidClientConfigError, "`command_routings` option needs the request_policy key of #{name}" if policies[:request_policy].nil?
+
+      build_command_routing_policies(name, policies[:request_policy], policies[:response_policy])
+    end
+
+    def build_command_routing_policies(name, request_policy, response_policy)
+      request_policy = -request_policy.to_s
+      response_policy = response_policy.nil? ? nil : -response_policy.to_s
+      if ::RedisClient::Cluster::Router::RoutingTable.find_policy_action(request_policy, response_policy).nil?
+        raise InvalidClientConfigError,
+              "`command_routings` option includes unsupported policies of #{name}: request_policy=#{request_policy}, response_policy=#{response_policy.inspect}"
+      end
+
+      { request_policy: request_policy, response_policy: response_policy }.freeze
+    end
+
     def merge_generic_config(client_config, node_configs)
       cfg = node_configs.first || {}
       client_config.reject { |k, _| IGNORE_GENERIC_CONFIG_KEYS.include?(k) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis-cluster-client
 version: !ruby/object:Gem::Version
-  version: 0.16.5
+  version: 0.17.0
 platform: ruby
 authors:
 - Taishi Kasuga
@@ -51,6 +51,7 @@ files:
 - lib/redis_client/cluster/pipeline.rb
 - lib/redis_client/cluster/pub_sub.rb
 - lib/redis_client/cluster/router.rb
+- lib/redis_client/cluster/router/routing_table.rb
 - lib/redis_client/cluster/transaction.rb
 - lib/redis_client/cluster_config.rb
 - lib/redis_cluster_client.rb
@@ -74,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Redis cluster-aware client for Ruby
 test_files: []