hotkv 1.0.0

data/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in this SDK, please
+report it privately by emailing **security@hotkv.com** rather than opening
+a public issue.
+
+Please include, where possible:
+
+- A description of the vulnerability and its potential impact.
+- Steps to reproduce it, including the SDK version and Ruby version.
+- Any proof-of-concept code or logs that help demonstrate the issue.
+
+We will acknowledge your report, investigate, and follow up with next
+steps and, once a fix is available, a coordinated disclosure timeline.
+Please give us a reasonable amount of time to address the issue before any
+public disclosure.
+
+## Supported Versions
+
+Security fixes are provided for the latest 1.x release of this package.
+Older versions may not receive fixes; please upgrade to the latest release
+before reporting an issue that might already be resolved.
+
+## Scope
+
+This policy covers the `hotkv` Ruby gem itself (this repository).
+For vulnerabilities in the HotKV server or HotKV Cloud, please also use
+security@hotkv.com so the report reaches the right team.

data/lib/hotkv/ai/call_result.rb

@@ -0,0 +1,25 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module AI
+    # Shared by PromptCache/SemanticCache: the block given to #get_or_call
+    # may return either just the response, or a [response, usage] pair, so
+    # a real model call can report its actual token usage only once it has
+    # run.
+    module CallResult
+      module_function
+
+      # Detected by the second element's type alone (never just "is a
+      # 2 element Array"), so it stays unambiguous no matter what the
+      # response itself looks like.
+      def split_usage(result)
+        if result.is_a?(Array) && result.length == 2 && result[1].is_a?(TokenUsage)
+          result
+        else
+          [result, nil]
+        end
+      end
+    end
+  end
+end

data/lib/hotkv/ai/prompt_cache.rb

@@ -0,0 +1,135 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require "json"
+require "digest"
+
+module HotKV
+  module AI
+    # Deterministic LLM prompt/response cache. Builds a cache key from
+    # provider, model, the normalized messages/system prompt and
+    # generation parameters, and wraps #get_or_call so the wrapped LLM
+    # call only ever runs on a cache miss. Built on HotKV::Client#pcache.
+    #
+    # The key is the lowercase hex SHA-256 digest of a canonical, compact
+    # JSON encoding of {provider, model, system, messages, params}. This
+    # exact encoding (key order, compact separators, UTF-8 kept literal,
+    # params sorted by byte value) is shared byte for byte by every
+    # official HotKV SDK, so two different SDKs given the same logical
+    # call always agree on the key.
+    class PromptCache
+      DEFAULT_NAMESPACE = "default"
+
+      attr_reader :namespace, :stats_bucket
+
+      # +stats_bucket+, if given, is used by #record_usage to push real
+      # token/cost/latency numbers (which only the caller's LLM
+      # integration knows) into LLMSTATS.
+      def initialize(client, namespace: DEFAULT_NAMESPACE, stats_bucket: nil)
+        @client = client
+        @namespace = namespace
+        @stats_bucket = stats_bucket
+        @namespace_ready = false
+        @bucket_ready = false
+      end
+
+      # Computes the canonical cache key without touching the server.
+      def self.cache_key(provider:, model:, messages:, system: "", params: {})
+        Digest::SHA256.hexdigest(canonical_json(provider: provider, model: model, messages: messages,
+                                                 system: system, params: params))
+      end
+
+      def self.canonical_json(provider:, model:, messages:, system: "", params: {})
+        JSON.generate(
+          "provider" => provider.to_s,
+          "model" => model.to_s,
+          "system" => system.to_s,
+          "messages" => messages.map { |m| canonical_message(m) },
+          "params" => canonical_params(params)
+        )
+      end
+
+      def self.canonical_message(message)
+        { "role" => fetch_field(message, :role).to_s, "content" => fetch_field(message, :content).to_s }
+      end
+      private_class_method :canonical_message
+
+      def self.fetch_field(message, key)
+        message[key] || message[key.to_s]
+      end
+      private_class_method :fetch_field
+
+      # Params must already be string valued (callers format numbers
+      # themselves, e.g. "0.7"), sorted ascending by byte value.
+      def self.canonical_params(params)
+        sorted = params.map { |k, v| [k.to_s, v] }.sort_by { |k, _v| k }.to_h
+        sorted.each_value do |v|
+          next if v.is_a?(String)
+
+          raise Error::ArgumentError,
+                "PromptCache params must be string valued (got #{v.class}); format numbers yourself so " \
+                "the encoding never differs between SDKs"
+        end
+        sorted
+      end
+      private_class_method :canonical_params
+
+      # Looks up the cache for this exact call. On a hit, returns the
+      # cached response and never calls the block. On a miss, calls the
+      # block (which should perform the real LLM call and return the text
+      # to cache), stores it, and returns it. Always returns
+      # {response:, cache_hit:, cache_key:}.
+      #
+      # The block may return either just the response, or a
+      # [response, usage] pair (a HotKV::TokenUsage); when it does,
+      # +usage+ is stored with the cache entry (see HotKV::Namespaces::PCache#set)
+      # so a later hit attributes its savings through #stats.
+      def get_or_call(provider:, model:, messages:, system: "", params: {}, ttl: nil, meta: nil)
+        ensure_namespace!
+        key = self.class.cache_key(provider: provider, model: model, messages: messages, system: system,
+                                    params: params)
+        cached = @client.pcache.get(@namespace, key)
+        return { response: cached, cache_hit: true, cache_key: key } unless cached.nil?
+
+        response, usage = CallResult.split_usage(yield)
+        @client.pcache.set(@namespace, key, response, ttl: ttl, meta: meta, usage: usage)
+        { response: response, cache_hit: false, cache_key: key }
+      end
+
+      # Hit/miss counts and cost saved are already tracked server side;
+      # see #stats. This pushes real per call token/cost/latency numbers
+      # (which only the caller knows) into LLMSTATS, optionally priced
+      # from the LLMSTATS.PRICE table via +model+. A no-op unless
+      # :stats_bucket was configured or +bucket+ is given here.
+      def record_usage(input_tokens:, output_tokens:, cached_tokens: 0, cost_usd: 0.0, latency_ms: 0, error: false,
+                        model: nil, cache_write_5m_tokens: nil, cache_write_1h_tokens: nil, bucket: @stats_bucket)
+        return unless bucket
+
+        @client.llmstats.bucket(bucket) unless @bucket_ready
+        @bucket_ready = true
+        @client.llmstats.record(bucket, input_tokens, output_tokens, cached_tokens, cost_usd, latency_ms,
+                                 error: error, model: model, cache_write_5m_tokens: cache_write_5m_tokens,
+                                 cache_write_1h_tokens: cache_write_1h_tokens)
+      end
+
+      # entries, hits, misses, evictions, memory_bytes, hit_rate, p50_ns,
+      # p95_ns, p99_ns, cost_saved_usd and the usage_saved_* savings
+      # counters (attributed from any +usage+ stored with an entry) for
+      # this namespace.
+      def stats
+        @client.pcache.stats(@namespace)
+      end
+
+      private
+
+      def ensure_namespace!
+        return if @namespace_ready
+
+        @client.pcache.create(@namespace)
+        @namespace_ready = true
+      rescue Error::ServerError
+        @namespace_ready = true
+      end
+    end
+  end
+end

data/lib/hotkv/ai/semantic_cache.rb

@@ -0,0 +1,66 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module AI
+    # Embedding based answer cache: looks up the nearest cached answer
+    # above a similarity threshold for a caller supplied embedding vector,
+    # and stores new answers. Provider neutral: the SDK never computes
+    # embeddings itself; +vector+ is whatever a caller's own embedding
+    # model produced. Built on HotKV::Client#scache.
+    class SemanticCache
+      DEFAULT_NAMESPACE = "default"
+
+      attr_reader :namespace
+
+      def initialize(client, dims:, namespace: DEFAULT_NAMESPACE, metric: nil, threshold: nil, ttl: nil)
+        @client = client
+        @namespace = namespace
+        @dims = dims
+        @metric = metric
+        @threshold = threshold
+        @ttl = ttl
+        @namespace_ready = false
+      end
+
+      # Looks up +vector+ in the cache. On a hit (similarity above the
+      # configured, or overridden, threshold) returns
+      # {response:, similarity:, cache_hit: true} without calling the
+      # block. On a miss, calls the block (which should compute the real
+      # answer and return it), stores it under +query_text+/+vector+, and
+      # returns {response:, cache_hit: false}.
+      #
+      # The block may return either just the response, or a
+      # [response, usage] pair (a HotKV::TokenUsage); when it does,
+      # +usage+ is stored with the cache entry (see HotKV::Namespaces::SCache#set)
+      # so a later hit attributes its savings through #stats.
+      def get_or_call(query_text, vector, threshold: nil)
+        ensure_namespace!
+        hit = @client.scache.get(@namespace, vector, threshold: threshold)
+        return hit.merge(cache_hit: true) if hit
+
+        response, usage = CallResult.split_usage(yield)
+        @client.scache.set(@namespace, query_text, response, vector, ttl: @ttl, usage: usage)
+        { response: response, cache_hit: false }
+      end
+
+      # entries, hits, misses, hit_rate, p50_us and the usage_saved_*
+      # savings counters (attributed from any +usage+ stored with an
+      # entry) for this namespace.
+      def stats
+        @client.scache.stats(@namespace)
+      end
+
+      private
+
+      def ensure_namespace!
+        return if @namespace_ready
+
+        @client.scache.create(@namespace, @dims, metric: @metric, threshold: @threshold, ttl: @ttl)
+        @namespace_ready = true
+      rescue Error::ServerError
+        @namespace_ready = true
+      end
+    end
+  end
+end

data/lib/hotkv/client.rb

@@ -0,0 +1,201 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # Thread safe HotKV client: a bounded connection pool in front of the
+  # typed command methods (every family in Commands::All), pipelines,
+  # transactions, pub/sub and the raw #command/#execute escape hatch.
+  #
+  #   client = HotKV::Client.new(url: "hotkv://localhost:6379")
+  #   client.set("k", "v")
+  #   client.get("k") # => "v"
+  #   client.close
+  class Client
+    include Commands::All
+
+    DEFAULTS = {
+      host: "127.0.0.1",
+      port: 6379,
+      path: nil,
+      username: nil,
+      password: nil,
+      db: 0,
+      client_name: nil,
+      connect_timeout: 5.0,
+      command_timeout: nil,
+      pool_size: 5,
+      idle_timeout: 300,
+      pool_timeout: 5.0,
+      ssl: false,
+      insecure_skip_verify: false,
+      ca_file: nil,
+      cert_file: nil,
+      key_file: nil,
+      server_name: nil
+    }.freeze
+
+    # Best effort allowlist of read only commands safe to retry once after
+    # a connection loss. Never includes a write (the container
+    # commands CONFIG, CLIENT and SCRIPT are included only because their
+    # state changing subcommands are idempotent).
+    READONLY_COMMANDS = %w[
+      GET MGET STRLEN EXISTS TYPE TTL PTTL EXPIRETIME PEXPIRETIME GETRANGE GETBIT
+      BITCOUNT BITPOS LLEN LRANGE LINDEX LPOS SMEMBERS SISMEMBER SMISMEMBER SCARD SINTER SUNION
+      SDIFF SINTERCARD SRANDMEMBER HGET HMGET HGETALL HKEYS HVALS HLEN HSTRLEN HEXISTS HRANDFIELD
+      HTTL HPTTL HEXPIRETIME HPEXPIRETIME ZSCORE ZMSCORE ZCARD ZRANK ZREVRANK ZCOUNT ZLEXCOUNT
+      ZRANGE ZRANGEBYSCORE ZRANGEBYLEX ZREVRANGE ZREVRANGEBYSCORE ZREVRANGEBYLEX ZRANDMEMBER
+      ZUNION ZINTER ZDIFF ZINTERCARD KEYS SCAN HSCAN SSCAN ZSCAN RANDOMKEY DUMP OBJECT DBSIZE
+      XRANGE XREVRANGE XLEN XREAD XINFO XPENDING GEOPOS GEODIST GEOHASH GEOSEARCH PFCOUNT PING
+      ECHO TIME INFO CONFIG LASTSAVE CLIENT SCRIPT COMMAND
+      LCS DIGEST SUBSTR SORT_RO GEORADIUS_RO GEORADIUSBYMEMBER_RO EVAL_RO EVALSHA_RO FCALL_RO ROLE
+      BF.EXISTS BF.MEXISTS BF.CARD BF.INFO CMS.QUERY CMS.INFO TOPK.QUERY TOPK.COUNT TOPK.LIST TOPK.INFO
+      VSIM.GET VSIM.SEARCH VSIM.INFO
+      TAG.GET TAG.MEMBERS TAG.INTER TAG.COUNT TAG.EXISTS NTTL HOTKEYS
+      OBSERVE
+    ].freeze
+    private_constant :READONLY_COMMANDS
+
+    # +url+ ("hotkv://", "hotkvs://", or a redis:// equivalent) supplies
+    # any options it encodes; explicit keyword options always win over
+    # whatever the URL carried for the same setting.
+    def initialize(url: nil, **options)
+      merged = url ? URL.parse(url).merge(options) : options
+      @options = DEFAULTS.merge(merged)
+      @pool = Pool.new(@options, size: @options[:pool_size], idle_timeout: @options[:idle_timeout],
+                                  pool_timeout: @options[:pool_timeout])
+    end
+
+    # Runs a command immediately and returns its decoded reply.
+    def invoke(*args)
+      raw = send_command(args)
+      block_given? ? yield(raw) : raw
+    end
+
+    # Generic escape hatch: sends any command as given.
+    def command(*args)
+      invoke(*args)
+    end
+    alias_method :execute, :command
+
+    # Batches every command queued inside the block into one round trip.
+    # See HotKV::Pipeline.
+    def pipelined
+      raise Error::ArgumentError, "pipelined requires a block" unless block_given?
+
+      @pool.with_connection do |conn|
+        pipeline = Pipeline.new(conn)
+        yield pipeline
+        pipeline.execute
+      end
+    end
+
+    # Runs a MULTI/EXEC transaction. See HotKV::Transaction. Returns the
+    # Array of results, or nil if the transaction was aborted.
+    def multi
+      raise Error::ArgumentError, "multi requires a block" unless block_given?
+
+      @pool.with_connection do |conn|
+        conn.call("MULTI")
+        tx = Transaction.new(conn)
+        begin
+          yield tx
+        rescue StandardError
+          conn.call("DISCARD", raise_on_error: false)
+          raise
+        end
+        tx.exec
+      end
+    end
+
+    # Watches +keys+ for changes, on one connection held for the whole
+    # block. The yielded HotKV::WatchSession runs ordinary commands
+    # immediately (to decide what to do) and offers #multi to start the
+    # actual transaction once you are ready. UNWATCH is sent automatically
+    # if the block never calls #multi.
+    def watch(*keys)
+      raise Error::ArgumentError, "watch requires a block" unless block_given?
+
+      flat_keys = keys.flatten
+      @pool.with_connection do |conn|
+        conn.call("WATCH", *flat_keys) unless flat_keys.empty?
+        session = WatchSession.new(conn)
+        begin
+          yield session
+        ensure
+          conn.call("UNWATCH", raise_on_error: false) unless session.multi_started?
+        end
+      end
+    end
+
+    # Subscribes to +channels+ on a dedicated (non pooled) connection and
+    # blocks the calling thread, dispatching frames to the callbacks
+    # registered on the HotKV::PubSub yielded to the block, until every
+    # subscription ends. See HotKV::PubSub.
+    def subscribe(*channels, &block)
+      pubsub_loop("SUBSCRIBE", channels.flatten, &block)
+    end
+
+    def psubscribe(*patterns, &block)
+      pubsub_loop("PSUBSCRIBE", patterns.flatten, &block)
+    end
+
+    def ssubscribe(*channels, &block)
+      pubsub_loop("SSUBSCRIBE", channels.flatten, &block)
+    end
+
+    # Closes every pooled connection. The client can keep being used
+    # afterward; new connections are opened on demand.
+    def close
+      @pool.shutdown
+    end
+
+    private
+
+    def send_command(args)
+      attempts = 0
+      begin
+        @pool.with_connection { |conn| conn.call(*args) }
+      rescue Error::ConnectionError, Error::TimeoutError
+        attempts += 1
+        retry if attempts == 1 && READONLY_COMMANDS.include?(args[0].to_s.upcase)
+        raise
+      end
+    end
+
+    CONFIRM_KINDS = %w[subscribe unsubscribe psubscribe punsubscribe ssubscribe sunsubscribe].freeze
+    private_constant :CONFIRM_KINDS
+
+    def pubsub_loop(wire_cmd, targets)
+      raise Error::ArgumentError, "#{wire_cmd} requires a block" unless block_given?
+      raise Error::ArgumentError, "#{wire_cmd} needs at least one channel or pattern" if targets.empty?
+
+      conn = Connection.new(@options).connect
+      on = PubSub.new.bind(conn)
+      yield on
+      conn.write_command([wire_cmd, *targets])
+      count = -1
+      begin
+        count = read_pubsub_frame(conn, on, count) while count != 0
+      ensure
+        conn.close
+      end
+      nil
+    end
+
+    def read_pubsub_frame(conn, on, count)
+      frame = RESP.read_reply(conn.io, raise_on_error: false)
+      kind = frame[0].to_s
+      case kind
+      when "message" then on.dispatch(:message, frame[1], frame[2])
+      when "pmessage" then on.dispatch(:pmessage, frame[1], frame[2], frame[3])
+      when "smessage" then on.dispatch(:smessage, frame[1], frame[2])
+      else
+        if CONFIRM_KINDS.include?(kind)
+          on.dispatch(kind.to_sym, frame[1], frame[2])
+          count = frame[2]
+        end
+      end
+      count
+    end
+  end
+end

data/lib/hotkv/cluster/crc16.rb

@@ -0,0 +1,43 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  class Cluster
+    # CRC16/XMODEM (poly 0x1021, init 0, no reflection, no final xor) and the
+    # cluster key slot algorithm built on it: hash only the part of a
+    # key between the first "{" and the next non-empty "}", when present.
+    module CRC16
+      SLOT_COUNT = 16_384
+
+      module_function
+
+      def crc16(bytes)
+        crc = 0
+        bytes.b.each_byte do |byte|
+          crc = (crc ^ (byte << 8)) & 0xFFFF
+          8.times do
+            crc = ((crc & 0x8000) != 0) ? ((crc << 1) ^ 0x1021) & 0xFFFF : (crc << 1) & 0xFFFF
+          end
+        end
+        crc
+      end
+
+      def key_slot(key)
+        crc16(hash_tag(key)) % SLOT_COUNT
+      end
+
+      # Returns the substring of +key+ that participates in hashing: the
+      # text strictly between the first "{" and the next "}" after it, or
+      # the whole key when there is no such non-empty tag.
+      def hash_tag(key)
+        s = key.index("{")
+        return key unless s
+
+        e = key.index("}", s + 1)
+        return key if e.nil? || e == s + 1
+
+        key[(s + 1)...e]
+      end
+    end
+  end
+end

data/lib/hotkv/cluster.rb

@@ -0,0 +1,184 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require "monitor"
+
+module HotKV
+  # Cluster aware HotKV client. Discovers the slot map with CLUSTER SLOTS,
+  # routes each command to the node that owns its key's slot (CRC16 with
+  # {hash tag} support), refreshes the map and retries on MOVED, and
+  # follows ASK (sending ASKING first) without updating the map for the
+  # one off redirect. Exposes the same typed command methods as
+  # HotKV::Client, plus the #command/#execute escape hatch.
+  #
+  # Against a server that is not running in cluster mode (CLUSTER SLOTS
+  # comes back empty), every command is simply routed to the configured
+  # seed nodes in round robin, so the same client also works against a
+  # single standalone server.
+  class Cluster
+    include Commands::All
+
+    DEFAULT_MAX_REDIRECTS = 8
+
+    # +urls+: one or more "hotkv://host:port" seed addresses (or option
+    # Hashes with :host/:port). Remaining keyword options are the same
+    # connection options HotKV::Client accepts and apply to every node.
+    def initialize(urls:, **options)
+      seeds = Array(urls)
+      raise Error::ArgumentError, "Cluster.new requires at least one seed url" if seeds.empty?
+
+      @base_options = options
+      @seed_addrs = seeds.map { |u| seed_addr(u) }
+      @max_redirects = options[:max_redirects] || DEFAULT_MAX_REDIRECTS
+      # Reading from replicas (READONLY) is not supported: every command goes
+      # to the node that owns the key's slot. Refuse the option rather than
+      # silently ignore it.
+      if options.key?(:readonly) || options.key?(:read_from)
+        raise Error::ArgumentError, "HotKV::Cluster does not support reading from replicas (:readonly / :read_from)"
+      end
+
+      @lock = Monitor.new
+      @pools = {}
+      @slots = {}
+      @rr = 0
+      refresh_slots
+    end
+
+    def invoke(*args)
+      raw = dispatch(args)
+      block_given? ? yield(raw) : raw
+    end
+
+    # Generic escape hatch: sends any command, routed by its first argument.
+    def command(*args)
+      invoke(*args)
+    end
+    alias_method :execute, :command
+
+    # Forces a slot map refresh from CLUSTER SLOTS.
+    def refresh!
+      refresh_slots
+    end
+
+    def known_nodes
+      @lock.synchronize { @slots.values.uniq }
+    end
+
+    def close
+      @lock.synchronize { @pools.each_value(&:shutdown) }
+    end
+
+    private
+
+    KEYLESS_COMMANDS = %w[
+      PING ECHO INFO TIME DBSIZE FLUSHDB FLUSHALL CONFIG CLIENT CLUSTER COMMAND SELECT HELLO AUTH
+      SCAN SCRIPT EVAL EVALSHA FCALL FCALL_RO MULTI EXEC DISCARD WATCH UNWATCH SUBSCRIBE PSUBSCRIBE
+      SSUBSCRIBE UNSUBSCRIBE PSUNSUBSCRIBE SUNSUBSCRIBE PUBLISH PUBSUB WAIT SAVE BGSAVE BGREWRITEAOF
+      SHUTDOWN DEBUG MEMORY SLOWLOG LATENCY ACL
+      OBSERVE ALERTS HOTKEYS ASKING
+    ].freeze
+
+    def seed_addr(u)
+      opts = u.is_a?(String) ? URL.parse(u) : u
+      "#{opts[:host]}:#{opts[:port]}"
+    end
+
+    def pool_for(addr)
+      @lock.synchronize do
+        @pools[addr] ||= begin
+          host, _, port = addr.rpartition(":")
+          Pool.new(@base_options.merge(host: host, port: port.to_i),
+                    size: @base_options[:pool_size] || 5,
+                    idle_timeout: @base_options[:idle_timeout] || 300,
+                    pool_timeout: @base_options[:pool_timeout])
+        end
+      end
+    end
+
+    def next_seed
+      @lock.synchronize do
+        addr = @seed_addrs[@rr % @seed_addrs.size]
+        @rr += 1
+        addr
+      end
+    end
+
+    # Reloads the slot table from CLUSTER SLOTS, asking the nodes already
+    # known first and the seed urls after them; the first one that answers
+    # wins, so a dead node never blocks a refresh while another is up.
+    def refresh_slots
+      candidates = (@lock.synchronize { @slots.values.uniq } + @seed_addrs).uniq
+      last_error = nil
+      candidates.each do |addr|
+        begin
+          raw = pool_for(addr).with_connection { |c| c.call("CLUSTER", "SLOTS", raise_on_error: false) }
+        rescue Error::ConnectionError, Error::TimeoutError => e
+          last_error = e
+          next
+        end
+        return store_slots(raw, addr)
+      end
+      raise last_error if last_error
+    end
+
+    def store_slots(raw, answering_addr)
+      new_slots = {}
+      unless raw.is_a?(Error::ServerError) || raw.nil? || raw.empty?
+        default_host = answering_addr.rpartition(":").first
+        raw.each do |range|
+          start_slot, end_slot, master = range[0], range[1], range[2]
+          host = master[0].to_s.empty? ? default_host : master[0]
+          node_addr = "#{host}:#{master[1]}"
+          (start_slot..end_slot).each { |s| new_slots[s] = node_addr }
+        end
+      end
+      @lock.synchronize { @slots = new_slots }
+    end
+
+    def target_addr(args)
+      cmd = args[0].to_s.upcase
+      key = args[1]
+      return next_seed if key.nil? || KEYLESS_COMMANDS.include?(cmd)
+
+      slot = CRC16.key_slot(key.to_s)
+      @lock.synchronize { @slots[slot] } || next_seed
+    end
+
+    # "host:port" a MOVED/ASK points at. An empty host means "the node that
+    # answered", as in cluster mode.
+    def redirect_addr(reply, answering_addr)
+      host = reply.host.to_s.empty? ? answering_addr.rpartition(":").first : reply.host
+      "#{host}:#{reply.port}"
+    end
+
+    def dispatch(args, redirects: 0, asking_addr: nil)
+      raise Error::ClusterDownError.new("CLUSTERDOWN", "too many redirects for this command") if redirects > @max_redirects
+
+      addr = asking_addr || target_addr(args)
+      reply =
+        begin
+          pool_for(addr).with_connection do |conn|
+            conn.call("ASKING", raise_on_error: false) if asking_addr
+            conn.call(*args, raise_on_error: false)
+          end
+        rescue Error::ConnectionError, Error::TimeoutError
+          refresh_slots
+          return dispatch(args, redirects: redirects + 1)
+        end
+
+      case reply
+      when Error::MovedError
+        refresh_slots
+        moved_to = redirect_addr(reply, addr)
+        @lock.synchronize { @slots[reply.slot] = moved_to } # MOVED is authoritative for its slot
+        dispatch(args, redirects: redirects + 1)
+      when Error::AskError
+        dispatch(args, redirects: redirects + 1, asking_addr: redirect_addr(reply, addr))
+      when Error::ServerError
+        raise reply
+      else
+        reply
+      end
+    end
+  end
+end