solid-redis 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e045fb206c3adbf1aa208bfdbae97821b8cc6e1b755b18fe280bc4b80d15454
-  data.tar.gz: 33ae5396c81305ac6c79cd0677a5ecb2dd0ff24621d7ceddef621264a4f3ea01
+  metadata.gz: aa178f3f726a1fe71f54af0aacebb6bb93890c86c4068e518acf1bbb7de16a67
+  data.tar.gz: 2b834a7e586b947cc39486bc0107614e7faa9db2aa3b3c91ab365c58db9b314e
 SHA512:
-  metadata.gz: c2218d4ff1b85617a1e36f77a1ecdf68a23ae0ff3c0313060c834a2e0313c039eebeb4a0e05f1aae498ab25cbe0ffe7fbac2869a8e5a461b714d8e2308c0201d
-  data.tar.gz: 2c3759624b31328cc78fb33038730b0c046ca7f1f6e15953605b971222d378df8f001f4865c07842d4e6d105cb5b60036acbf06c32428897405a97d7c152dc70
+  metadata.gz: cc25f3b1e2ee529877e39f3da367ad966fcdeb35283732f7ad2d144ce4d78b8c3e1476203f6910525e80bceb7cf6a9f3bc7916c4dc1ac401ea9b97130f80937e
+  data.tar.gz: cd5472d06a641f06bfe1a13d7bfd50b530bfc8126ce07cfb34484f19ae3842da24dedc36e51863225603861b0b23057b923164db817087667d91f86caa1aece9

data/README.md

@@ -6,17 +6,20 @@
 [![Documentation Status](https://img.shields.io/badge/docs-RubyDoc.info-blue.svg)](https://www.rubydoc.info/gems/solid-redis)
 
 `solid-redis` is a dependency-free Redis client designed around Ractor
-isolation. Its Redis and Sentinel specifications are immutable and shareable;
-every Ractor creates and retains its own resolution state, mutex, pool,
-clients, and sockets.
+isolation. Its Redis, Sentinel, and Cluster specifications are immutable and
+shareable; every Ractor creates and retains its own resolution state, slot
+table, mutex, pool, clients, and sockets.
 
-It does not depend on or patch `redis-client`.
+It supports standalone Redis, Sentinel failover, Redis Cluster routing,
+pipelines, blocking commands, and Pub/Sub. It does not depend on or patch
+`redis-client`.
 
 The implementation intentionally composes two small gems from the same
 author:
 
 - [`base-service`](https://github.com/nicolasva/base-service) executes each
-  Sentinel resolution and returns its immutable result and endpoint errors;
+  Sentinel resolution and Cluster topology discovery and returns its immutable
+  result and endpoint errors;
 - [`callback-collection`](https://github.com/nicolasva/callback-collection)
   provides immutable lifecycle event handlers.
 
@@ -175,6 +178,109 @@ The pool may be shared by threads in its owning Ractor. It must not be sent to
 another Ractor. Create a separate pool inside every Ractor, as in the example
 above.
 
+## Blocking commands
+
+`blocking_call(timeout, *command)` runs BLPOP, BRPOP, BZPOPMIN, XREAD BLOCK
+and similar commands. The socket read timeout becomes `timeout` plus the
+configured `read_timeout`; pass `nil` or `0` when Redis blocks indefinitely.
+
+```ruby
+pool.blocking_call(5, "BLPOP", "jobs", 5)   # => ["jobs", "payload"] or nil
+pool.blocking_call(nil, "BLPOP", "jobs", 0) # waits forever
+```
+
+A blocking command is never retried after a connection error, because the
+element may already have been consumed. While it waits, its connection stays
+checked out: size pools with room for concurrent blocking waiters plus regular
+traffic, and keep the pool `timeout` short so other threads fail fast instead
+of freezing.
+
+## Pub/Sub
+
+`new_subscription` opens a dedicated connection that belongs to the calling
+Ractor and is never taken from a pool.
+
+```ruby
+subscription = config.new_subscription
+subscription.subscribe("events").psubscribe("alerts.*")
+
+subscription.each_message(timeout: 1.0) do |message|
+  next if message.nil?          # timeout elapsed: check a stop flag here
+  next unless message.message?  # skip subscribe/unsubscribe/pong events
+
+  puts "#{message.channel}: #{message.payload}"
+end
+```
+
+`Message` is a frozen struct with `type` (`:message`, `:pmessage`,
+`:smessage`, `:subscribe`, `:psubscribe`, `:ssubscribe`, `:unsubscribe`,
+`:punsubscribe`, `:sunsubscribe`, `:pong`), `channel`, `pattern`, and
+`payload`. `next_message(timeout:)` returns one message or `nil`; `ping`
+sends a keepalive answered by a `:pong` message. Sharded channels use
+`ssubscribe`/`sunsubscribe`.
+
+After a connection loss the subscription reconnects according to
+`reconnect_attempts` and re-issues its tracked channels and patterns; the
+confirmations flow back as `:subscribe`/`:psubscribe` messages. Regular
+commands raise `SolidRedis::Error` on a subscription.
+
+The natural Ractor pattern is one listener Ractor fanning out plain Strings to
+workers:
+
+```ruby
+port = Ractor::Port.new # Ruby >= 4.0; use Ractor.yield/take on 3.x
+
+listener = Ractor.new(CONFIG, port) do |config, port|
+  subscription = config.new_subscription
+  subscription.subscribe("events")
+  subscription.each_message do |message|
+    port << [message.channel, message.payload].freeze if message&.message?
+  end
+end
+
+loop do
+  channel, payload = port.receive
+  # dispatch to application Ractors
+end
+```
+
+## Redis Cluster
+
+`SolidRedis.cluster` builds an immutable, shareable specification from seed
+nodes. Each Ractor discovers the slot table with `CLUSTER SLOTS` on first use
+and keeps it, together with one connection per node, in Ractor-local state.
+
+```ruby
+CLUSTER = SolidRedis.cluster(
+  nodes: ["redis://10.0.0.1:7000", "10.0.0.2:7000"],
+  password: ENV["REDIS_PASSWORD"],
+  timeout: 1.0,
+  max_redirections: 5
+)
+
+Ractor.shareable?(CLUSTER) # => true
+
+client = CLUSTER.new_client
+client.call("SET", "user:1", "Ada")
+client.call("GET", "user:1")
+client.call("MGET", "{user:1}.name", "{user:1}.email") # same slot via hash tag
+
+client.pipelined do |pipeline|
+  pipeline.call("GET", "a")   # commands are grouped per node,
+  pipeline.call("GET", "b")   # sent in parallel pipelines,
+  pipeline.call("PING")       # and results come back in order
+end
+
+pool = CLUSTER.new_pool(size: 5) # a pool of cluster clients
+```
+
+Routing uses CRC16 hash slots with `{hash tag}` support and knows the key
+position of EVAL/FCALL, XREAD/XREADGROUP, ZUNION-style and keyless commands.
+`MOVED` updates the local slot table; `ASK` is followed once with `ASKING`;
+`TRYAGAIN`/`CLUSTERDOWN` trigger a topology refresh. `CROSSSLOT` errors from
+Redis are raised as `SolidRedis::CommandError`. Cluster only supports database
+`0`; `blocking_call` is routed like any other command.
+
 ## Configuration
 
 Direct Redis options:
@@ -200,6 +306,10 @@ Sentinel additionally requires `name` and `sentinels`, and accepts `role`,
 `sentinel_username`, `sentinel_password`, `sentinel_ssl`, and
 `sentinel_ssl_params`. Sentinel defaults to two reconnect attempts.
 
+Cluster requires `nodes` (host:port strings, `redis://` URLs, or hashes) and
+accepts `max_redirections` (default `5`) plus the direct Redis options above
+except `db`, which must be `0`.
+
 All configuration is copied and deeply frozen. Proc credentials and mutable
 objects such as `OpenSSL::X509::Store` are rejected because Ruby cannot make
 them Ractor-shareable. Prefer immutable values and paths in TLS parameters.
@@ -237,7 +347,7 @@ config = SolidRedis.sentinel(
 | `connected` | resolved server URL |
 | `disconnected` | resolved server URL |
 | `connection_error` | exception class name and message |
-| `resolved` | Sentinel name and resolved server URL |
+| `resolved` | Sentinel name and resolved server URL, or `"cluster"` and the node list |
 
 Method registration is required for a Ractor-shareable callback collection.
 Block callbacks retain mutable lexical context and are therefore rejected.
@@ -426,16 +536,21 @@ SolidRedis.config(
 
 ## Semantics and current scope
 
-- Clients, pools, sockets, mutexes, and Sentinel runtime state are never
-  shared between Ractors.
-- Multiple threads in one Ractor share one protected Sentinel resolution.
+- Clients, pools, sockets, mutexes, Sentinel runtime state, and Cluster slot
+  tables are never shared between Ractors.
+- Multiple threads in one Ractor share one protected Sentinel resolution or
+  Cluster topology.
 - Redis command errors are never retried.
 - Connection errors may retry a command according to `reconnect_attempts`.
   Applications requiring strict at-most-once semantics should set it to `0`.
+  Blocking commands and Pub/Sub never replay a command.
 - A pool waits up to its checkout timeout and then raises
   `SolidRedis::CheckoutTimeoutError`.
-- Pub/Sub, transactions, blocking-call helpers, cluster routing, middleware,
-  and an asynchronous actor pool are not part of version `0.1`.
+- Cluster clients follow up to `max_redirections` MOVED/ASK redirections and
+  refresh the topology on TRYAGAIN/CLUSTERDOWN, then raise
+  `SolidRedis::FailoverError`.
+- Transactions helpers (MULTI/EXEC/WATCH), Cluster replica reads, middleware,
+  and an asynchronous actor pool are not part of version `1.0`.
 
 ### Known CRuby limitation
 

data/lib/solid_redis/client.rb

@@ -26,6 +26,34 @@ module SolidRedis
       end
     end
 
+    # Runs a blocking command such as BLPOP, BRPOP, BZPOPMIN or XREAD BLOCK.
+    #
+    # +timeout+ is the number of seconds Redis was asked to block for; the
+    # socket read timeout becomes +timeout+ plus the configured read timeout.
+    # Pass +nil+ or +0+ when Redis blocks indefinitely: the read then waits
+    # forever. The command is never retried after a connection error because
+    # the element may already have been consumed.
+    def blocking_call(timeout, *command)
+      blocking_call_v(timeout, command)
+    end
+
+    def blocking_call_v(timeout, command)
+      with_reconnect { connect unless connected? }
+
+      read_timeout = timeout && timeout.positive? ? timeout + @target.read_timeout : nil
+      begin
+        write(RESP.encode(command))
+        @reader.with_timeout(read_timeout) { @reader.read }
+      rescue ConnectionError, IO::WaitReadable, IO::WaitWritable, SystemCallError => error
+        close
+        config.reset if config.sentinel?
+        config.notify(:connection_error, error.class.name, error.message)
+        raise error if error.is_a?(Error)
+
+        raise ConnectionError, error.message, cause: error
+      end
+    end
+
     def pipelined(exception: true)
       pipeline = Pipeline.new
       yield pipeline

data/lib/solid_redis/cluster/command_key.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SolidRedis
+  module Cluster
+    # Extracts the routing key of a command. Most Redis commands carry their
+    # first key as the second argument; the exceptions are listed here.
+    module CommandKey
+      KEYLESS = Ractor.make_shareable(
+        %w[
+          ACL ASKING AUTH BGREWRITEAOF BGSAVE CLIENT CLUSTER COMMAND CONFIG DBSIZE DEBUG DISCARD ECHO EXEC
+          FAILOVER FLUSHALL FLUSHDB FUNCTION HELLO INFO LASTSAVE LATENCY LOLWUT MEMORY MODULE MONITOR MULTI PING
+          PSUBSCRIBE PUBLISH PUBSUB PUNSUBSCRIBE QUIT RANDOMKEY READONLY READWRITE REPLICAOF RESET ROLE SAVE
+          SCAN SCRIPT SELECT SHUTDOWN SLAVEOF SLOWLOG SUBSCRIBE SWAPDB SYNC TIME UNSUBSCRIBE UNWATCH WAIT
+        ].to_h { |name| [name, true] },
+      )
+
+      # Commands whose keys are announced by a "numkeys" argument.
+      NUMKEYS_AT = Ractor.make_shareable({
+        "EVAL" => 2, "EVALSHA" => 2, "EVAL_RO" => 2, "EVALSHA_RO" => 2,
+        "FCALL" => 2, "FCALL_RO" => 2, "ZUNIONSTORE" => 2, "ZINTERSTORE" => 2, "ZDIFFSTORE" => 2,
+        "ZUNION" => 1, "ZINTER" => 1, "ZDIFF" => 1, "SINTERCARD" => 1, "ZINTERCARD" => 1, "LMPOP" => 1, "ZMPOP" => 1,
+        "BLMPOP" => 2, "BZMPOP" => 2,
+      })
+
+      STREAMS_COMMANDS = Ractor.make_shareable({ "XREAD" => true, "XREADGROUP" => true })
+
+      module_function
+
+      # Returns the first key of +command+, or nil for keyless commands.
+      def for(command)
+        name = command[0].to_s.upcase
+        return if KEYLESS[name]
+
+        if (index = NUMKEYS_AT[name])
+          count = Integer(command[index], exception: false) || 0
+          return count.positive? ? command[index + 1] : nil
+        end
+
+        if STREAMS_COMMANDS[name]
+          streams = command.index { |argument| argument.to_s.casecmp?("STREAMS") }
+          return streams && command[streams + 1]
+        end
+
+        case name
+        when "XGROUP", "XINFO", "OBJECT" then command[2]
+        when "MIGRATE" then command[3].to_s.empty? ? nil : command[3]
+        else command[1]
+        end
+      end
+    end
+  end
+end

data/lib/solid_redis/cluster/discover_service.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SolidRedis
+  module Cluster
+    # Queries CLUSTER SLOTS on the first reachable node and returns the slot
+    # table as a list of ranges:
+    #
+    #   { ranges: [{ from:, to:, master: { host:, port: }, replicas: [...] }], endpoint: }
+    class DiscoverService < Service::Base
+      def call
+        @endpoints.each do |endpoint|
+          client = Config.new(**@specification.redis_client_options, **endpoint).new_client
+          ranges = client.call("CLUSTER", "SLOTS").map { |entry| range(entry, endpoint) }
+          if ranges.empty?
+            append_error(:empty_topology, "#{endpoint_label(endpoint)} returned no slots")
+            next
+          end
+
+          return { ranges: ranges, endpoint: endpoint }
+        rescue SolidRedis::Error, KeyError, ArgumentError, TypeError => error
+          append_error(:node_unavailable, "#{endpoint_label(endpoint)}: #{error.message}")
+        ensure
+          client&.close
+        end
+
+        nil
+      end
+
+      private
+
+      def range(entry, endpoint)
+        from, to, master, *replicas = entry
+        {
+          from: Integer(from),
+          to: Integer(to),
+          master: node(master, endpoint),
+          replicas: replicas.map { |replica| node(replica, endpoint) },
+        }
+      end
+
+      # A node may announce an empty host, meaning "the address you used".
+      def node(entry, endpoint)
+        host, port = entry
+        host = endpoint[:host] if host.nil? || host.to_s.empty?
+        { host: host, port: Integer(port) }
+      end
+
+      def endpoint_label(endpoint)
+        "#{endpoint[:host]}:#{endpoint[:port]}"
+      end
+    end
+  end
+end

data/lib/solid_redis/cluster/key_slot.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SolidRedis
+  module Cluster
+    # Maps a Redis key to one of the 16384 cluster hash slots using CRC16
+    # (XMODEM) and the +{hash tag}+ rule from the Redis Cluster specification.
+    module KeySlot
+      SLOTS = 16_384
+
+      # CRC16 XMODEM lookup table (polynomial 0x1021).
+      TABLE = Ractor.make_shareable(
+        Array.new(256) do |byte|
+          crc = byte << 8
+          8.times { crc = (crc & 0x8000).zero? ? (crc << 1) & 0xFFFF : ((crc << 1) ^ 0x1021) & 0xFFFF }
+          crc
+        end,
+      )
+
+      module_function
+
+      def for(key)
+        crc16(hash_tag(key.to_s)) % SLOTS
+      end
+
+      def hash_tag(key)
+        open = key.index("{")
+        return key unless open
+
+        close = key.index("}", open + 1)
+        return key unless close && close > open + 1
+
+        key[(open + 1)...close]
+      end
+
+      def crc16(string)
+        string.each_byte.reduce(0) do |crc, byte|
+          ((crc << 8) & 0xFFFF) ^ TABLE[((crc >> 8) ^ byte) & 0xFF]
+        end
+      end
+    end
+  end
+end

data/lib/solid_redis/cluster_client.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module SolidRedis
+  # Routes commands to the cluster node owning their key slot and follows
+  # MOVED/ASK redirections. Holds one Client per node; all of them belong to
+  # the Ractor that created this object.
+  class ClusterClient
+    REDIRECTION = /\A(MOVED|ASK) (\d+) (\S+):(\d+)\z/
+    RETRY_DELAY = 0.05
+
+    attr_reader :config
+
+    def initialize(config, name: nil)
+      @config = config
+      @name = name
+      @clients = {}
+    end
+
+    def call(*command)
+      call_v(command)
+    end
+
+    def call_v(command)
+      route(command) { |client| client.call_v(command) }
+    end
+
+    def blocking_call(timeout, *command)
+      blocking_call_v(timeout, command)
+    end
+
+    def blocking_call_v(timeout, command)
+      route(command, retry_connection: false) { |client| client.blocking_call_v(timeout, command) }
+    end
+
+    # Groups commands by node, runs one pipeline per node and restores the
+    # original order. Redirected commands are replayed individually.
+    def pipelined(exception: true)
+      pipeline = Client::Pipeline.new
+      yield pipeline
+      commands = pipeline.commands
+      return [] if commands.empty?
+
+      results = Array.new(commands.length)
+      commands.each_with_index.group_by { |command, _| node_for(command) }.each do |node, group|
+        replies = client_for(node).pipelined(exception: false) do |batch|
+          group.each { |command, _| batch.call_v(command) }
+        end
+        group.each_with_index { |(_, index), position| results[index] = replies[position] }
+      end
+
+      results.each_with_index do |result, index|
+        next unless result.is_a?(CommandError) && result.message.match?(REDIRECTION)
+
+        results[index] = begin
+          call_v(commands[index])
+        rescue CommandError => error
+          error
+        end
+      end
+
+      if exception && (error = results.find { |result| result.is_a?(CommandError) })
+        raise error
+      end
+
+      results
+    end
+
+    def connected?
+      @clients.values.any?(&:connected?)
+    end
+
+    def close
+      clients = @clients.values
+      @clients = {}
+      clients.each(&:close)
+      self
+    end
+
+    def server_url
+      @clients.keys.join(",")
+    end
+
+    private
+
+    def route(command, retry_connection: true)
+      node = node_for(command)
+      redirections = 0
+      attempts = 0
+      asking = false
+
+      loop do
+        client = client_for(node)
+        client.call_v(["ASKING"]) if asking
+        return yield(client)
+      rescue CommandError => error
+        redirection = error.message.match(REDIRECTION)
+        if redirection
+          redirections += 1
+          raise FailoverError, "Too many cluster redirections: #{error.message}" if redirections > config.max_redirections
+
+          slot = Integer(redirection[2])
+          host = redirection[3]
+          port = Integer(redirection[4])
+          asking = redirection[1] == "ASK"
+          node = asking ? config.state.node(host, port) : config.state.move(slot, host, port)
+        elsif error.message.start_with?("TRYAGAIN", "CLUSTERDOWN")
+          redirections += 1
+          raise FailoverError, "Cluster unavailable: #{error.message}" if redirections > config.max_redirections
+
+          sleep RETRY_DELAY
+          config.state.refresh
+          node = node_for(command)
+        else
+          raise
+        end
+      rescue ConnectionError => error
+        drop(node)
+        raise unless retry_connection && attempts < config.reconnect_attempts
+
+        attempts += 1
+        config.notify(:connection_error, error.class.name, error.message)
+        config.state.refresh
+        node = node_for(command)
+      end
+    end
+
+    def node_for(command)
+      key = Cluster::CommandKey.for(command)
+      key ? config.state.node_for_slot(Cluster::KeySlot.for(key)) : config.state.any_node
+    end
+
+    def client_for(node)
+      @clients[node.server_key] ||= node.new_client(name: @name)
+    end
+
+    def drop(node)
+      @clients.delete(node.server_key)&.close
+    end
+  end
+end

data/lib/solid_redis/cluster_config.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module SolidRedis
+  # Immutable, Ractor-shareable description of a Redis Cluster: seed nodes and
+  # per-node client options. Slot tables, node clients and sockets live in a
+  # per-Ractor ClusterState, exactly like SentinelConfig/SentinelState.
+  class ClusterConfig
+    LOCAL_STATE_KEY = :solid_redis_cluster_states
+    DEFAULT_PORT = 6379
+    DEFAULT_MAX_REDIRECTIONS = 5
+
+    attr_reader :node_endpoints, :redis_client_options, :reconnect_attempts, :max_redirections
+
+    def initialize(nodes:, max_redirections: DEFAULT_MAX_REDIRECTIONS, **redis_options)
+      endpoints = Array(nodes).map { |endpoint| normalize_endpoint(endpoint) }
+      @node_endpoints = Shareable.copy(endpoints, label: "nodes")
+      raise ArgumentError, "At least one cluster node is required" if @node_endpoints.empty?
+
+      @max_redirections = Integer(max_redirections)
+      raise ArgumentError, "max_redirections must not be negative" if @max_redirections.negative?
+
+      @reconnect_attempts = Integer(redis_options.fetch(:reconnect_attempts, 1))
+      raise ArgumentError, "reconnect_attempts must not be negative" if @reconnect_attempts.negative?
+      raise ArgumentError, "Redis Cluster only supports database 0" if redis_options.fetch(:db, 0) != 0
+
+      @redis_client_options = Shareable.copy(redis_options, label: "Redis options")
+      Ractor.make_shareable(self)
+    end
+
+    def sentinel?
+      false
+    end
+
+    def cluster?
+      true
+    end
+
+    def discovered?
+      state.discovered?
+    end
+
+    def nodes
+      state.nodes
+    end
+
+    def reset
+      state.reset
+      self
+    end
+
+    def refresh
+      state.refresh
+      self
+    end
+
+    def new_client(**options)
+      ClusterClient.new(self, **options)
+    end
+
+    def new_pool(**options)
+      Pool.new(self, **options)
+    end
+
+    def notify(event, *arguments)
+      callbacks = redis_client_options[:callbacks]
+      return unless callbacks&.respond_to?(event)
+
+      callbacks.respond_with(event, *arguments)
+    end
+
+    def inspect
+      "#<#{self.class.name} nodes=#{node_endpoints.length}>"
+    end
+
+    # Per-Ractor runtime state, created on first use in each Ractor.
+    def state
+      registry = Ractor.current[LOCAL_STATE_KEY]
+      unless registry
+        registry = { mutex: Mutex.new, states: {} }
+        Ractor.current[LOCAL_STATE_KEY] = registry
+      end
+
+      registry[:mutex].synchronize do
+        registry[:states][self] ||= ClusterState.new(self)
+      end
+    end
+
+    private
+
+    def normalize_endpoint(endpoint)
+      unless endpoint.is_a?(String)
+        endpoint = endpoint.transform_keys(&:to_sym)
+        return { host: endpoint.fetch(:host), port: Integer(endpoint.fetch(:port, DEFAULT_PORT)) }
+      end
+
+      uri = URI.parse(endpoint.include?("://") ? endpoint : "redis://#{endpoint}")
+      unless %w[redis rediss].include?(uri.scheme)
+        raise ArgumentError, "Unsupported cluster URL scheme: #{uri.scheme.inspect}"
+      end
+
+      { host: uri.host || "127.0.0.1", port: uri.port || DEFAULT_PORT }
+    rescue URI::InvalidURIError => error
+      raise ArgumentError, "Invalid cluster node: #{error.message}", cause: error
+    end
+  end
+end

data/lib/solid_redis/cluster_state.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module SolidRedis
+  # Per-Ractor Cluster runtime: the slot table, the node configurations and
+  # the mutex protecting them. Never shared between Ractors.
+  class ClusterState
+    def initialize(specification)
+      @specification = specification
+      @mutex = Mutex.new
+      @slots = Array.new(Cluster::KeySlot::SLOTS)
+      @nodes = {}
+      @discovered = false
+    end
+
+    def discovered?
+      @mutex.synchronize { @discovered }
+    end
+
+    # Returns the master Config owning +slot+, discovering the topology when
+    # it is not known yet.
+    def node_for_slot(slot)
+      @mutex.synchronize do
+        discover unless @discovered
+        key = @slots[slot]
+        if key.nil?
+          discover
+          key = @slots[slot]
+        end
+        @nodes[key] || raise(ConnectionError, "No cluster node serves slot #{slot}")
+      end
+    end
+
+    def nodes
+      @mutex.synchronize do
+        discover unless @discovered
+        @nodes.values
+      end
+    end
+
+    def any_node
+      nodes.first
+    end
+
+    # Applies a MOVED redirection locally without a full topology refresh.
+    def move(slot, host, port)
+      @mutex.synchronize do
+        key = node_key(host, port)
+        @nodes[key] ||= node_config(host, port)
+        @slots[slot] = key
+        @nodes[key]
+      end
+    end
+
+    def node(host, port)
+      @mutex.synchronize { @nodes[node_key(host, port)] ||= node_config(host, port) }
+    end
+
+    def reset
+      @mutex.synchronize do
+        @discovered = false
+        @slots.fill(nil)
+        @nodes.clear
+      end
+    end
+
+    def refresh
+      @mutex.synchronize { discover }
+    end
+
+    private
+
+    # Must be called with the mutex held.
+    def discover
+      endpoints = @nodes.values.map { |config| { host: config.host, port: config.port } }
+      endpoints |= @specification.node_endpoints
+      result = Cluster::DiscoverService.call(specification: @specification, endpoints: endpoints)
+      unless result.successful? && result.result
+        details = result.errors.map(&:message).join("; ")
+        raise ConnectionError, "No cluster node reachable: #{details}"
+      end
+
+      @slots.fill(nil)
+      @nodes.clear
+      result.result[:ranges].each do |range|
+        key = node_key(range[:master][:host], range[:master][:port])
+        @nodes[key] ||= node_config(range[:master][:host], range[:master][:port])
+        (range[:from]..range[:to]).each { |slot| @slots[slot] = key }
+      end
+      @discovered = true
+      @specification.notify(:resolved, "cluster", @nodes.keys.join(","))
+    end
+
+    def node_key(host, port)
+      "#{host}:#{port}"
+    end
+
+    # Node clients never retry on their own: ClusterClient owns the retry so
+    # that a topology refresh happens between attempts.
+    def node_config(host, port)
+      Config.new(**@specification.redis_client_options, host: host, port: port, reconnect_attempts: 0)
+    end
+  end
+end

data/lib/solid_redis/config.rb

@@ -89,6 +89,10 @@ module SolidRedis
       Pool.new(self, **options)
     end
 
+    def new_subscription(**options)
+      Subscription.new(self, **options)
+    end
+
     def notify(event, *arguments)
       return unless @callbacks&.respond_to?(event)
 

data/lib/solid_redis/pool.rb

@@ -37,6 +37,14 @@ module SolidRedis
       with { |client| client.call_v(command) }
     end
 
+    def blocking_call(timeout, *command)
+      with { |client| client.blocking_call_v(timeout, command) }
+    end
+
+    def blocking_call_v(timeout, command)
+      with { |client| client.blocking_call_v(timeout, command) }
+    end
+
     def pipelined(exception: true, &block)
       with { |client| client.pipelined(exception: exception, &block) }
     end

data/lib/solid_redis/resp.rb

@@ -34,6 +34,29 @@ module SolidRedis
         @buffer = +""
       end
 
+      # Temporarily overrides the read timeout. +nil+ waits forever, which is
+      # what blocking commands such as BLPOP with a 0 timeout require.
+      def with_timeout(timeout)
+        previous = @read_timeout
+        @read_timeout = timeout
+        yield
+      ensure
+        @read_timeout = previous
+      end
+
+      # Waits until at least one byte is available without consuming it.
+      # Returns +false+ on timeout. Unlike a timed-out +read+, this never
+      # leaves a partially consumed frame behind, so it is the safe way to
+      # poll for the next Pub/Sub message.
+      def wait_readable(timeout)
+        return true unless @buffer.empty?
+        return true unless @io.respond_to?(:to_io)
+
+        !IO.select([@io], nil, nil, timeout).nil?
+      rescue IOError, SystemCallError => error
+        raise ConnectionError, error.message, cause: error
+      end
+
       def read(exception: true)
         case (type = read_bytes(1))
         when "+" then read_line

data/lib/solid_redis/sentinel_config.rb

@@ -90,6 +90,10 @@ module SolidRedis
       Pool.new(self, **options)
     end
 
+    def new_subscription(**options)
+      Subscription.new(self, **options)
+    end
+
     def notify(event, *arguments)
       callbacks = redis_client_options[:callbacks]
       return unless callbacks&.respond_to?(event)

data/lib/solid_redis/subscription.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module SolidRedis
+  # A dedicated Pub/Sub connection.
+  #
+  # Once SUBSCRIBE has been sent, a Redis connection stops answering regular
+  # commands and turns into a stream of push messages. A Subscription therefore
+  # owns its own socket, is never taken from a pool, and belongs to the Ractor
+  # that created it. Channel and pattern lists are tracked locally so that the
+  # connection can be re-established and re-subscribed after a network error.
+  class Subscription < Client
+    Message = Struct.new(:type, :channel, :pattern, :payload) do
+      def message?
+        %i[message pmessage smessage].include?(type)
+      end
+    end
+
+    SUBSCRIBE_COMMANDS = Ractor.make_shareable({
+      channels: %w[SUBSCRIBE UNSUBSCRIBE],
+      patterns: %w[PSUBSCRIBE PUNSUBSCRIBE],
+      shards: %w[SSUBSCRIBE SUNSUBSCRIBE],
+    })
+
+    def initialize(config, name: nil)
+      super
+      @channels = []
+      @patterns = []
+      @shards = []
+    end
+
+    def subscribe(*channels)
+      change(:channels, 0, channels)
+    end
+
+    def psubscribe(*patterns)
+      change(:patterns, 0, patterns)
+    end
+
+    def ssubscribe(*channels)
+      change(:shards, 0, channels)
+    end
+
+    def unsubscribe(*channels)
+      change(:channels, 1, channels)
+    end
+
+    def punsubscribe(*patterns)
+      change(:patterns, 1, patterns)
+    end
+
+    def sunsubscribe(*channels)
+      change(:shards, 1, channels)
+    end
+
+    def ping(payload = nil)
+      transmit { payload ? ["PING", payload] : ["PING"] }
+      self
+    end
+
+    def subscriptions
+      { channels: @channels.dup, patterns: @patterns.dup, shards: @shards.dup }
+    end
+
+    def subscribed?
+      !(@channels.empty? && @patterns.empty? && @shards.empty?)
+    end
+
+    # Returns the next Message, or +nil+ when +timeout+ seconds elapse without
+    # one. A +nil+ timeout waits forever. Connection errors trigger a reconnect
+    # and a re-subscription according to +reconnect_attempts+.
+    def next_message(timeout: nil)
+      attempts = 0
+      loop do
+        ensure_connected
+        return unless @reader.wait_readable(timeout)
+
+        return decode(@reader.read)
+      rescue ConnectionError, IO::WaitReadable, IO::WaitWritable, SystemCallError => error
+        handle_error(error)
+        raise error if attempts >= config.reconnect_attempts
+
+        attempts += 1
+      end
+    end
+
+    # Yields every incoming Message. When +timeout+ is given, yields +nil+
+    # each time it elapses so the caller can check a stop condition.
+    def each_message(timeout: nil)
+      return enum_for(__method__, timeout: timeout) unless block_given?
+
+      loop { yield next_message(timeout: timeout) }
+    end
+
+    def call(*)
+      raise Error, "Regular commands are not available on a Pub/Sub connection"
+    end
+    alias_method :call_v, :call
+    alias_method :pipelined, :call
+    alias_method :blocking_call, :call
+    alias_method :blocking_call_v, :call
+
+    private
+
+    # The tracked list is updated only once a connection exists, so a fresh
+    # connection re-subscribes to the previous list and the new command is
+    # then sent exactly once.
+    def change(kind, direction, names)
+      names = names.flatten.map(&:to_s)
+      transmit do
+        list = instance_variable_get(:"@#{kind}")
+        if direction.zero?
+          names.each { |name| list << name unless list.include?(name) }
+        else
+          names.empty? ? list.clear : list.delete_if { |name| names.include?(name) }
+        end
+        [SUBSCRIBE_COMMANDS[kind][direction], *names]
+      end
+      self
+    end
+
+    def transmit
+      attempts = 0
+      loop do
+        ensure_connected
+        return write(RESP.encode(yield))
+      rescue ConnectionError, IO::WaitReadable, IO::WaitWritable, SystemCallError => error
+        handle_error(error)
+        raise error if attempts >= config.reconnect_attempts
+
+        attempts += 1
+      end
+    end
+
+    def ensure_connected
+      return if connected?
+
+      connect
+      resubscribe
+    end
+
+    # Re-issues the tracked subscriptions on a fresh connection. Confirmation
+    # events flow back to the caller as :subscribe/:psubscribe/:ssubscribe.
+    def resubscribe
+      write(RESP.encode(["SUBSCRIBE", *@channels])) unless @channels.empty?
+      write(RESP.encode(["PSUBSCRIBE", *@patterns])) unless @patterns.empty?
+      write(RESP.encode(["SSUBSCRIBE", *@shards])) unless @shards.empty?
+    end
+
+    def handle_error(error)
+      close
+      config.reset if config.sentinel?
+      config.notify(:connection_error, error.class.name, error.message)
+      raise ConnectionError, error.message, cause: error unless error.is_a?(Error)
+    end
+
+    def decode(reply)
+      unless reply.is_a?(Array) && reply.first.is_a?(String)
+        raise ProtocolError, "Unexpected Pub/Sub reply: #{reply.inspect}"
+      end
+
+      type = reply[0].to_sym
+      case type
+      when :message, :smessage
+        Message.new(type, reply[1], nil, reply[2])
+      when :pmessage
+        Message.new(type, reply[2], reply[1], reply[3])
+      when :pong
+        Message.new(type, nil, nil, reply[1])
+      when :psubscribe, :punsubscribe
+        Message.new(type, nil, reply[1], reply[2])
+      else
+        Message.new(type, reply[1], nil, reply[2])
+      end.freeze
+    end
+  end
+end

data/lib/solid_redis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidRedis
-  VERSION = "0.2.1"
+  VERSION = "1.0.0"
 end

data/lib/solid_redis.rb

@@ -9,9 +9,16 @@ require_relative "solid_redis/shareable"
 require_relative "solid_redis/config"
 require_relative "solid_redis/resp"
 require_relative "solid_redis/client"
+require_relative "solid_redis/subscription"
 require_relative "solid_redis/sentinel/resolve_service"
 require_relative "solid_redis/sentinel_state"
 require_relative "solid_redis/sentinel_config"
+require_relative "solid_redis/cluster/key_slot"
+require_relative "solid_redis/cluster/command_key"
+require_relative "solid_redis/cluster/discover_service"
+require_relative "solid_redis/cluster_state"
+require_relative "solid_redis/cluster_config"
+require_relative "solid_redis/cluster_client"
 require_relative "solid_redis/pool"
 
 module SolidRedis
@@ -24,4 +31,8 @@ module SolidRedis
   def sentinel(**options)
     SentinelConfig.new(**options)
   end
+
+  def cluster(**options)
+    ClusterConfig.new(**options)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid-redis
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Nicolas Vandenbogaerde
@@ -71,8 +71,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Use immutable Redis configuration with isolated Sentinel state, pools,
-  and sockets per Ractor.
+description: Immutable, shareable Redis, Sentinel and Cluster configuration with isolated
+  runtime state, pools, and sockets per Ractor. Supports pipelines, blocking commands,
+  and Pub/Sub.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -81,6 +82,12 @@ files:
 - README.md
 - lib/solid_redis.rb
 - lib/solid_redis/client.rb
+- lib/solid_redis/cluster/command_key.rb
+- lib/solid_redis/cluster/discover_service.rb
+- lib/solid_redis/cluster/key_slot.rb
+- lib/solid_redis/cluster_client.rb
+- lib/solid_redis/cluster_config.rb
+- lib/solid_redis/cluster_state.rb
 - lib/solid_redis/config.rb
 - lib/solid_redis/errors.rb
 - lib/solid_redis/pool.rb
@@ -89,13 +96,14 @@ files:
 - lib/solid_redis/sentinel_config.rb
 - lib/solid_redis/sentinel_state.rb
 - lib/solid_redis/shareable.rb
+- lib/solid_redis/subscription.rb
 - lib/solid_redis/version.rb
 homepage: https://github.com/nicolasva/solid-redis
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-  documentation_uri: https://www.rubydoc.info/gems/solid-redis/0.2.1
+  documentation_uri: https://www.rubydoc.info/gems/solid-redis/1.0.0
   source_code_uri: https://github.com/nicolasva/solid-redis
 rdoc_options: []
 require_paths:
@@ -113,5 +121,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: A Ractor-aware Redis client with Sentinel support
+summary: A Ractor-aware Redis client with Sentinel, Cluster, Pub/Sub and blocking
+  command support
 test_files: []