redis 5.4.1 → 6.0.0

data/lib/redis/commands/modules/search.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "redis/commands/modules/search/dialect"
+require "redis/commands/modules/search/index_definition"
+require "redis/commands/modules/search/field"
+require "redis/commands/modules/search/schema"
+require "redis/commands/modules/search/query"
+require "redis/commands/modules/search/index"
+require "redis/commands/modules/search/result"
+require "redis/commands/modules/search/miscellaneous"
+require "redis/commands/modules/search/hybrid"
+require "redis/commands/modules/search/aggregation"
+
+class Redis
+  module Commands
+    module Search
+    end
+  end
+end

data/lib/redis/commands/sets.rb

@@ -135,6 +135,26 @@ class Redis
         send_command([:sdiffstore, destination].concat(keys))
       end
 
+      # Get the number of members in the difference between the first set and
+      # all successive sets.
+      #
+      # @example
+      #   redis.sadd("foo", ["s1", "s2", "s3"])
+      #   redis.sadd("bar", "s3")
+      #   redis.sdiffcard("foo", "bar")
+      #     # => 2
+      #
+      # @param [String, Array<String>] keys keys pointing to sets to subtract
+      # @param [Integer] limit stop counting once the difference reaches `limit`
+      #   members (`0` means unlimited)
+      # @return [Integer] number of members in the difference
+      def sdiffcard(*keys, limit: nil)
+        keys.flatten!(1)
+        args = [:sdiffcard, keys.size].concat(keys)
+        args << "LIMIT" << Integer(limit) if limit
+        send_command(args)
+      end
+
       # Intersect multiple sets.
       #
       # @param [String, Array<String>] keys keys pointing to sets to intersect
@@ -173,6 +193,27 @@ class Redis
         send_command([:sunionstore, destination].concat(keys))
       end
 
+      # Get the number of distinct members in the union of multiple sets.
+      #
+      # @example
+      #   redis.sadd("foo", ["s1", "s2", "s3"])
+      #   redis.sadd("bar", ["s3", "s4"])
+      #   redis.sunioncard("foo", "bar")
+      #     # => 4
+      #
+      # @param [String, Array<String>] keys keys pointing to sets to unify
+      # @param [Boolean] approx return an approximate cardinality computed with HyperLogLog
+      # @param [Integer] limit stop counting once the union reaches `limit`
+      #   members (`0` means unlimited)
+      # @return [Integer] number of distinct members in the union
+      def sunioncard(*keys, approx: false, limit: nil)
+        keys.flatten!(1)
+        args = [:sunioncard, keys.size].concat(keys)
+        args << "APPROX" if approx
+        args << "LIMIT" << Integer(limit) if limit
+        send_command(args)
+      end
+
       # Scan a set
       #
       # @example Retrieve the first batch of keys in a set

data/lib/redis/commands/sorted_sets.rb

@@ -366,7 +366,6 @@ class Redis
       #   - when `:with_scores` is specified, an array with `[member, score]` pairs
       def zrange(key, start, stop, byscore: false, by_score: byscore, bylex: false, by_lex: bylex,
                  rev: false, limit: nil, withscores: false, with_scores: withscores)
-
         if by_score && by_lex
           raise ArgumentError, "only one of :by_score or :by_lex can be specified"
         end

data/lib/redis/commands/streams.rb

@@ -44,10 +44,11 @@ class Redis
       # @option opts [Integer] :maxlen      max length of entries to keep
       # @option opts [Integer] :minid       min id of entries to keep
       # @option opts [Boolean] :approximate whether to add `~` modifier of maxlen/minid or not
+      # @option opts [Integer] :limit       maximum count of entries to be evicted, requires approximate trimming
       # @option opts [Boolean] :nomkstream  whether to add NOMKSTREAM, default is not to add
       #
       # @return [String] the entry id
-      def xadd(key, entry, approximate: nil, maxlen: nil, minid: nil, nomkstream: nil, id: '*')
+      def xadd(key, entry, approximate: nil, maxlen: nil, minid: nil, limit: nil, nomkstream: nil, id: '*')
         args = [:xadd, key]
         args << 'NOMKSTREAM' if nomkstream
         if maxlen
@@ -61,6 +62,7 @@ class Redis
           args << "~" if approximate
           args << minid
         end
+        args.concat(['LIMIT', limit]) if limit
         args << id
         args.concat(entry.flatten)
         send_command(args)
@@ -181,18 +183,28 @@ class Redis
       #   redis.xread(%w[mystream1 mystream2], %w[0-0 0-0])
       # @example With count option
       #   redis.xread('mystream', '0-0', count: 2)
+      # @example With max_count option
+      #   redis.xread(%w[mystream1 mystream2], %w[0-0 0-0], max_count: 10)
       # @example With block option
       #   redis.xread('mystream', '$', block: 1000)
       #
-      # @param keys  [Array<String>] one or multiple stream keys
-      # @param ids   [Array<String>] one or multiple entry ids
-      # @param count [Integer]       the number of entries as limit per stream
-      # @param block [Integer]       the number of milliseconds as blocking timeout
+      # @param keys      [Array<String>] one or multiple stream keys
+      # @param ids       [Array<String>] one or multiple entry ids
+      # @param count     [Integer]       the number of entries as limit per stream
+      # @param max_count [Integer]       the total number of entries as limit across all streams
+      #   combined, must be greater than or equal to `count` when both are given (Redis 8.10+).
+      #   Defaults to unlimited.
+      # @param max_size  [Integer]       soft cap on the total reply size in bytes across all
+      #   streams combined, measured on the serialized server reply including protocol overhead;
+      #   a single oversized first entry can still be returned (Redis 8.10+). Defaults to unlimited.
+      # @param block     [Integer]       the number of milliseconds as blocking timeout
       #
       # @return [Hash{String => Hash{String => Hash}}] the entries
-      def xread(keys, ids, count: nil, block: nil)
+      def xread(keys, ids, count: nil, max_count: nil, max_size: nil, block: nil)
         args = [:xread]
         args << 'COUNT' << count if count
+        args << 'MAXCOUNT' << Integer(max_count) if max_count
+        args << 'MAXSIZE' << Integer(max_size) if max_size
         args << 'BLOCK' << block.to_i if block
         _xread(args, keys, ids, block)
       end
@@ -243,14 +255,22 @@ class Redis
       # @param ids      [Array<String>] one or multiple entry ids
       # @param opts     [Hash]          several options for `XREADGROUP` command
       #
-      # @option opts [Integer] :count the number of entries as limit
+      # @option opts [Integer] :count the number of entries as limit per stream
+      # @option opts [Integer] :max_count the total number of entries as limit across all streams
+      #   combined, must be greater than or equal to `count` when both are given (Redis 8.10+).
+      #   Defaults to unlimited.
+      # @option opts [Integer] :max_size soft cap on the total reply size in bytes across all
+      #   streams combined, measured on the serialized server reply including protocol overhead;
+      #   a single oversized first entry can still be returned (Redis 8.10+). Defaults to unlimited.
       # @option opts [Integer] :block the number of milliseconds as blocking timeout
       # @option opts [Boolean] :noack whether message loss is acceptable or not
       #
       # @return [Hash{String => Hash{String => Hash}}] the entries
-      def xreadgroup(group, consumer, keys, ids, count: nil, block: nil, noack: nil)
+      def xreadgroup(group, consumer, keys, ids, count: nil, max_count: nil, max_size: nil, block: nil, noack: nil)
         args = [:xreadgroup, 'GROUP', group, consumer]
         args << 'COUNT' << count if count
+        args << 'MAXCOUNT' << Integer(max_count) if max_count
+        args << 'MAXSIZE' << Integer(max_size) if max_size
         args << 'BLOCK' << block.to_i if block
         args << 'NOACK' if noack
         _xread(args, keys, ids, block)

data/lib/redis/commands.rb

@@ -8,8 +8,10 @@ require "redis/commands/hashes"
 require "redis/commands/hyper_log_log"
 require "redis/commands/keys"
 require "redis/commands/lists"
+require "redis/commands/modules/json"
 require "redis/commands/pubsub"
 require "redis/commands/scripting"
+require "redis/commands/modules/search"
 require "redis/commands/server"
 require "redis/commands/sets"
 require "redis/commands/sorted_sets"
@@ -27,8 +29,10 @@ class Redis
     include HyperLogLog
     include Keys
     include Lists
+    include Json
     include Pubsub
     include Scripting
+    include Search
     include Server
     include Sets
     include SortedSets
@@ -55,7 +59,9 @@ class Redis
     }
 
     Hashify = lambda { |value|
-      if value.respond_to?(:each_slice)
+      if value.is_a?(Hash) # RESP3 already returns a map
+        value
+      elsif value.respond_to?(:each_slice) # RESP2 flat [k, v, k, v, ...]
         value.each_slice(2).to_h
       else
         value
@@ -63,10 +69,12 @@ class Redis
     }
 
     Pairify = lambda { |value|
-      if value.respond_to?(:each_slice)
-        value.each_slice(2).to_a
-      else
+      return value unless value.respond_to?(:each_slice)
+
+      if value.first.is_a?(Array) # RESP3 already returns [[k, v], ...]
         value
+      else # RESP2 flat [k, v, k, v, ...]
+        value.each_slice(2).to_a
       end
     }
 
@@ -90,7 +98,14 @@ class Redis
     FloatifyPairs = lambda { |value|
       return value unless value.respond_to?(:each_slice)
 
-      value.each_slice(2).map(&FloatifyPair)
+      if value.first.is_a?(Array) # RESP3 already returns [[member, score], ...]
+        # Scores arrive as native doubles, so the pairs are already in the final shape and
+        # re-mapping would only re-allocate identical arrays. Floatify only transforms Strings, so
+        # unless a score came back as one (it shouldn't under RESP3) return the parser's array as-is.
+        value.first.last.is_a?(String) ? value.map(&FloatifyPair) : value
+      else # RESP2 flat [member, score, member, score, ...]
+        value.each_slice(2).map(&FloatifyPair)
+      end
     }
 
     HashifyInfo = lambda { |reply|
@@ -217,14 +232,19 @@ class Redis
         when "get-master-addr-by-name"
           reply
         else
-          if reply.is_a?(Array)
-            if reply[0].is_a?(Array)
-              reply.map(&Hashify)
+          case reply
+          when Array
+            if reply.empty?
+              reply # empty list (e.g. sentinels/slaves with no entries) stays []; don't Hashify to {}
             else
-              Hashify.call(reply)
+              case reply[0]
+              when Array then reply.map(&Hashify) # RESP2: list of flat [k, v, ...] arrays
+              when Hash then reply                 # RESP3: list of maps (already hashes)
+              else Hashify.call(reply)             # RESP2: a single flat [k, v, ...] array
+              end
             end
           else
-            reply
+            reply # RESP3 single map, or a scalar reply
           end
         end
       end

data/lib/redis/distributed.rb

@@ -22,6 +22,10 @@ class Redis
       @ring = options[:ring] || HashRing.new
       @node_configs = node_configs.map(&:dup)
       @default_options = options.dup
+      # Schemas registered via himport_prepare, replayed to nodes that join the ring later (see
+      # #add_node) so ring membership changes don't leave nodes without the fieldsets that
+      # key-routed himport_set calls expect. Initialized before the add_node loop below.
+      @himport_fieldsets = {}
       node_configs.each { |node_config| add_node(node_config) }
       @subscribed_node = nil
       @watch_key = nil
@@ -43,7 +47,12 @@ class Redis
       options = @default_options.merge(options)
       options.delete(:tag)
       options.delete(:ring)
-      @ring.add_node Redis.new(options)
+      node = Redis.new(options)
+      # Replay registered fieldsets before the node can receive key-routed himport_set calls:
+      # a node joining after a himport_prepare fan-out has neither the server-side fieldset nor
+      # a populated registry to self-recover from "no such fieldset".
+      @himport_fieldsets.each { |name, fields| node.himport_prepare(name, fields) }
+      @ring.add_node node
     end
 
     # Change the selected database for the current connection.
@@ -340,6 +349,124 @@ class Redis
       node_for(key).getex(key, **options)
     end
 
+    # Set the JSON value at a path in the document stored under a key.
+    def json_set(key, path, value, **options)
+      node_for(key).json_set(key, path, value, **options)
+    end
+
+    # Get the JSON value(s) at one or more paths in the document stored under a key.
+    def json_get(key, *paths, **options)
+      node_for(key).json_get(key, *paths, **options)
+    end
+
+    # Set one or more JSON values. The keys may live on different nodes and the operation must be
+    # atomic, so it cannot be distributed.
+    def json_mset(*)
+      raise CannotDistribute, :json_mset
+    end
+
+    # Get the values at a path from several keys. Keys are grouped by node, queried per node, and
+    # reassembled in the original key order.
+    def json_mget(*keys, path, **options)
+      keys.flatten!(1)
+      values = keys.group_by { |key| node_for(key) }.each_with_object({}) do |(node, subkeys), acc|
+        node.json_mget(*subkeys, path, **options).each_with_index do |value, i|
+          acc[subkeys[i]] = value
+        end
+      end
+      keys.map { |key| values[key] }
+    end
+
+    # Delete the JSON value(s) at a path in the document stored under a key.
+    def json_del(key, path = nil)
+      node_for(key).json_del(key, path)
+    end
+
+    # Delete the JSON value(s) at a path in the document stored under a key (alias of json_del).
+    def json_forget(key, path = nil)
+      node_for(key).json_forget(key, path)
+    end
+
+    # Clear the container and numeric JSON value(s) at a path in the document stored under a key.
+    def json_clear(key, path = nil)
+      node_for(key).json_clear(key, path)
+    end
+
+    # Merge a JSON value into the document stored under a key at a path.
+    def json_merge(key, path, value, **options)
+      node_for(key).json_merge(key, path, value, **options)
+    end
+
+    # Append one or more values to the JSON array at a path in the document stored under a key.
+    def json_arrappend(key, path, *values, **options)
+      node_for(key).json_arrappend(key, path, *values, **options)
+    end
+
+    # Return the index of the first occurrence of a scalar in the JSON array at a path.
+    def json_arrindex(key, path, value, **options)
+      node_for(key).json_arrindex(key, path, value, **options)
+    end
+
+    # Insert one or more values into the JSON array at a path in the document stored under a key.
+    def json_arrinsert(key, path, index, *values, **options)
+      node_for(key).json_arrinsert(key, path, index, *values, **options)
+    end
+
+    # Return the length of the JSON array at a path in the document stored under a key.
+    def json_arrlen(key, path = nil)
+      node_for(key).json_arrlen(key, path)
+    end
+
+    # Remove and return an element from the JSON array at a path in the document stored under a key.
+    def json_arrpop(key, path = nil, index = nil, **options)
+      node_for(key).json_arrpop(key, path, index, **options)
+    end
+
+    # Trim the JSON array at a path in the document stored under a key to an inclusive range.
+    def json_arrtrim(key, path, start, stop)
+      node_for(key).json_arrtrim(key, path, start, stop)
+    end
+
+    # Increment the numeric JSON value(s) at a path in the document stored under a key.
+    def json_numincrby(key, path, number)
+      node_for(key).json_numincrby(key, path, number)
+    end
+
+    # Return the type name(s) of the JSON value(s) at a path in the document stored under a key.
+    def json_type(key, path = nil)
+      node_for(key).json_type(key, path)
+    end
+
+    # Return the key names of the JSON object(s) at a path in the document stored under a key.
+    def json_objkeys(key, path = nil)
+      node_for(key).json_objkeys(key, path)
+    end
+
+    # Return the number of keys in the JSON object(s) at a path in the document stored under a key.
+    def json_objlen(key, path = nil)
+      node_for(key).json_objlen(key, path)
+    end
+
+    # Return the length of the JSON string(s) at a path in the document stored under a key.
+    def json_strlen(key, path = nil)
+      node_for(key).json_strlen(key, path)
+    end
+
+    # Append a string to the JSON string(s) at a path in the document stored under a key.
+    def json_strappend(key, path, value, **options)
+      node_for(key).json_strappend(key, path, value, **options)
+    end
+
+    # Toggle the boolean JSON value(s) at a path in the document stored under a key.
+    def json_toggle(key, path)
+      node_for(key).json_toggle(key, path)
+    end
+
+    # Report the size in bytes of the JSON value(s) at a path in the document stored under a key.
+    def json_debug_memory(key, path = nil)
+      node_for(key).json_debug_memory(key, path)
+    end
+
     # Get the values of all the given keys as an Array.
     def mget(*keys)
       keys.flatten!(1)
@@ -427,6 +554,15 @@ class Redis
       end
     end
 
+    # Remove multiple elements from the head/tail of a list, append/prepend
+    # them to another list and return them.
+    def lmovem(source, destination, where_source, where_destination, count: nil, exactly: nil, order: nil)
+      ensure_same_node(:lmovem, [source, destination]) do |node|
+        node.lmovem(source, destination, where_source, where_destination,
+                    count: count, exactly: exactly, order: order)
+      end
+    end
+
     # Remove the first/last element in a list and append/prepend it
     # to another list and return it, or block until one is available.
     def blmove(source, destination, where_source, where_destination, timeout: 0)
@@ -435,6 +571,17 @@ class Redis
       end
     end
 
+    # Remove multiple elements from the head/tail of a list, append/prepend
+    # them to another list and return them; or block until the request can
+    # be satisfied or the timeout expires.
+    def blmovem(source, destination, where_source, where_destination, timeout: 0, count: nil, exactly: nil,
+                order: nil)
+      ensure_same_node(:blmovem, [source, destination]) do |node|
+        node.blmovem(source, destination, where_source, where_destination,
+                     timeout: timeout, count: count, exactly: exactly, order: order)
+      end
+    end
+
     # Prepend one or more values to a list.
     def lpush(key, value)
       node_for(key).lpush(key, value)
@@ -649,6 +796,15 @@ class Redis
       end
     end
 
+    # Get the number of members in the difference between the first set and
+    # all successive sets.
+    def sdiffcard(*keys, limit: nil)
+      keys.flatten!(1)
+      ensure_same_node(:sdiffcard, keys) do |node|
+        node.sdiffcard(keys, limit: limit)
+      end
+    end
+
     # Intersect multiple sets.
     def sinter(*keys)
       keys.flatten!(1)
@@ -681,6 +837,14 @@ class Redis
       end
     end
 
+    # Get the number of distinct members in the union of multiple sets.
+    def sunioncard(*keys, approx: false, limit: nil)
+      keys.flatten!(1)
+      ensure_same_node(:sunioncard, keys) do |node|
+        node.sunioncard(keys, approx: approx, limit: limit)
+      end
+    end
+
     # Get the number of members in a sorted set.
     def zcard(key)
       node_for(key).zcard(key)
@@ -918,6 +1082,112 @@ class Redis
       node_for(key).hgetall(key)
     end
 
+    def hexpire(key, ttl, *fields)
+      node_for(key).hexpire(key, ttl, *fields)
+    end
+
+    def httl(key, *fields)
+      node_for(key).httl(key, *fields)
+    end
+
+    # Scan a hash
+    def hscan(key, cursor, **options)
+      node_for(key).hscan(key, cursor, **options)
+    end
+
+    # Scan a hash and return an enumerator
+    def hscan_each(key, **options, &block)
+      node_for(key).hscan_each(key, **options, &block)
+    end
+
+    # Get the length of the value stored in a hash field
+    def hstrlen(key, field)
+      node_for(key).hstrlen(key, field)
+    end
+
+    def hpexpire(key, ttl, *fields, nx: nil, xx: nil, gt: nil, lt: nil)
+      node_for(key).hpexpire(key, ttl, *fields, nx: nx, xx: xx, gt: gt, lt: lt)
+    end
+
+    def hpttl(key, *fields)
+      node_for(key).hpttl(key, *fields)
+    end
+
+    # Register a fieldset on every ring node. Fieldsets are scoped to a physical
+    # connection, so every node that may receive an `himport_set` for a key it
+    # owns needs the fieldset on its own connection.
+    def himport_prepare(fieldset_name, *fields)
+      fields.flatten!(1)
+      results = on_each_node(:himport_prepare, fieldset_name, fields)
+      @himport_fieldsets[fieldset_name.to_s] = fields.dup.freeze
+      results
+    end
+
+    # Create or fully replace a hash from a fieldset prepared on the key's node.
+    def himport_set(key, fieldset_name, *values)
+      values.flatten!(1)
+      node_for(key).himport_set(key, fieldset_name, values)
+    end
+
+    # Remove a fieldset from every ring node.
+    def himport_discard(fieldset_name)
+      results = on_each_node(:himport_discard, fieldset_name)
+      @himport_fieldsets.delete(fieldset_name.to_s)
+      results
+    end
+
+    # Remove all fieldsets from every ring node.
+    def himport_discard_all
+      results = on_each_node(:himport_discard_all)
+      @himport_fieldsets.clear
+      results
+    end
+
+    # Add one or more geospatial items to a sorted set.
+    def geoadd(key, *member, **options)
+      node_for(key).geoadd(key, *member, **options)
+    end
+
+    # Get geohash strings representing the position of one or more members.
+    def geohash(key, member)
+      node_for(key).geohash(key, member)
+    end
+
+    # Get longitude and latitude of one or more members of a geospatial index.
+    def geopos(key, member)
+      node_for(key).geopos(key, member)
+    end
+
+    # Get the distance between two members of a geospatial index.
+    def geodist(key, member1, member2, unit = 'm')
+      node_for(key).geodist(key, member1, member2, unit)
+    end
+
+    # Query a geospatial index for members within a given radius from a point.
+    def georadius(*args, **geoptions)
+      key = args.first
+      node_for(key).georadius(*args, **geoptions)
+    end
+
+    # Query a geospatial index for members within a given radius from an existing member.
+    def georadiusbymember(*args, **geoptions)
+      key = args.first
+      node_for(key).georadiusbymember(*args, **geoptions)
+    end
+
+    # Search a geospatial index for members within a given shape from a center point.
+    def geosearch(key, **options)
+      node_for(key).geosearch(key, **options)
+    end
+
+    # Like #geosearch, but stores the result in a destination key.
+    # Destination and source must hash to the same node; use a key tag to ensure that.
+    def geosearchstore(destination, source, **options)
+      ensure_same_node(:geosearchstore, [destination, source]) do |node|
+        node.geosearchstore(destination, source, **options)
+      end
+    end
+
     # Post a message to a channel.
     def publish(channel, message)
       node_for(channel).publish(channel, message)

data/lib/redis/lib_identity.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "redis-client"
+require "redis/version"
+
+class Redis
+  # Reports `redis-rb` as the connecting library via `CLIENT SETINFO`.
+  #
+  # `redis-client` builds its own `LIB-NAME` as `redis-client(<driver_info>)` and always
+  # reports its own version as `LIB-VER`, which would identify `redis-client` rather than
+  # `redis-rb` to the server. We append a second pair of `CLIENT SETINFO` commands, which wins
+  # because the command is last-write-wins, so that `CLIENT LIST` / `CLIENT INFO` report
+  # `lib-name=redis-rb` and `lib-ver=<Redis::VERSION>`.
+  #
+  # Libraries built on top of `redis-rb` can still identify themselves by passing `driver_info`,
+  # in which case they are reported inside the parentheses, e.g. `lib-name=redis-rb(my-gem_v1.0.0)`.
+  # The official convention for such suffixes is `<name>_v<version>` (matching
+  # `(?<custom-name>[ -~]+)[ -~]v(?<custom-version>[\d\.]+)`), with `;` delimiting multiple
+  # suffixes and parentheses avoided inside them — see
+  # https://redis.io/docs/latest/commands/client-setinfo/. Passing `driver_info: false` disables
+  # `CLIENT SETINFO` entirely, for peers that can't tolerate unknown commands during the handshake
+  # (e.g. some proxies).
+  #
+  # Applications that use `redis-client` directly are left untouched: the override only applies
+  # to configurations whose `driver_info` was built by this module.
+  module LibIdentity
+    # Follows the official suffix convention, so that the transient pair `redis-client` itself
+    # builds from this value (`lib-name=redis-client(redis-rb_v<version>)`) is well-formed too.
+    MARKER = "redis-rb_v"
+    LIB_NAME = "redis-rb"
+    SEPARATOR = ";"
+    # Interpolated strings are not frozen by the magic comment; explicit freezes keep these
+    # constants Ractor-shareable (lazy module ivars here would raise Ractor::IsolationError).
+    OWN_INFO = "#{MARKER}#{Redis::VERSION}".freeze
+    OWN_PREFIX = "#{OWN_INFO}#{SEPARATOR}".freeze
+    # `CLIENT SETINFO` values must be printable ASCII with no spaces — the server rejects anything
+    # else, and `redis-client` swallows that error, which would silently leave `lib-name` empty.
+    # Parentheses are excluded as well: they delimit the suffix in `lib-name=redis-rb(<suffix>)`,
+    # so a suffix containing them would corrupt the reported name.
+    INVALID_CHARS = /(?:[^!-~]|[()])+/
+
+    class << self
+      # Combines redis-rb's own identity with the `driver_info` a downstream library passed in,
+      # so that both can be recovered when the connection prelude is built. `false` is passed
+      # through untouched and, being falsy, turns `CLIENT SETINFO` off wholesale (`redis-client`
+      # gates its own commands on `driver_info` too). Any other non-String, non-Array value is
+      # also passed through, leaving `redis-client` to reject it.
+      def driver_info(downstream = nil)
+        case downstream
+        when nil then OWN_INFO
+        when String then combine(downstream)
+        when Array then combine(downstream.join(SEPARATOR))
+        else downstream
+        end
+      end
+
+      # True only for values `driver_info` produced: exactly our own identity, or our identity
+      # followed by a downstream library's. Matching on the bare `MARKER` prefix instead would
+      # also capture a direct `redis-client` user whose own `driver_info` merely starts with
+      # `redis-rb_v` (say `redis-rb_viewer-1.0`) and would silently discard their identity.
+      def ours?(info)
+        info.is_a?(String) && (info == OWN_INFO || info.start_with?(OWN_PREFIX))
+      end
+
+      def setinfo_commands(info)
+        [
+          ["CLIENT", "SETINFO", "LIB-NAME", lib_name(info)].freeze,
+          ["CLIENT", "SETINFO", "LIB-VER", Redis::VERSION].freeze,
+        ].freeze
+      end
+
+      private
+
+      def combine(downstream)
+        downstream = downstream.scrub(" ") # invalid byte sequences would make gsub raise
+                               .gsub(/\A#{INVALID_CHARS}|#{INVALID_CHARS}\z/o, "")
+                               .gsub(INVALID_CHARS, "_")
+        downstream.empty? ? OWN_INFO : "#{OWN_PREFIX}#{downstream}"
+      end
+
+      def lib_name(info)
+        downstream = info == OWN_INFO ? nil : info.delete_prefix(OWN_PREFIX)
+        downstream.nil? || downstream.empty? ? LIB_NAME : "#{LIB_NAME}(#{downstream})".freeze
+      end
+    end
+
+    def connection_prelude
+      prelude = super
+      info = driver_info
+      return prelude unless LibIdentity.ours?(info)
+
+      # `CLIENT SETINFO` is last-write-wins, so appending after the commands `redis-client`
+      # already built overrides them, without having to recognise or remove them.
+      (prelude + LibIdentity.setinfo_commands(info)).freeze
+    end
+  end
+end
+
+# Prepended to the concrete config classes rather than to `RedisClient::Config::Common`, so that
+# the two `redis-client` entry points are covered without altering the shared module for anything
+# else that includes it. `RedisClient::SentinelConfig` is NOT a `RedisClient::Config` subclass, so
+# both lines are required. `RedisClient::Cluster::Node::Config` does subclass `RedisClient::Config`
+# and calls `super` in its own `connection_prelude`, so cluster nodes are covered by the first.
+RedisClient::Config.prepend(Redis::LibIdentity)
+RedisClient::SentinelConfig.prepend(Redis::LibIdentity)