protocol-redis 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77a3cf15694be52495a873fe8e807a5fb96909bdf0642a6619d26281b14a5aa8
-  data.tar.gz: fd4602f3b11bbf724a863a1012e1105add29017a8e4e6b6f7ae50be502df9cd8
+  metadata.gz: b39632c3f7210dd4eea7d4b561a74c94442434a3e9ae9220d44303ea51aba2af
+  data.tar.gz: 6a930186fd89b24a6469a79025de532bd638a8e942228dffe25c4a4752561731
 SHA512:
-  metadata.gz: b9e1310a24336a7aff3d5d23d3f43adbb18cbc70089a1daae360f9c835fc843ad886d81da80b34f5140f1bc58cde08630855fbc5e81486512a75944cd9c72b3e
-  data.tar.gz: 888798d1c44e1f8b8883c3f016ef00f0f47b13113b5a8cc5d087b1039d340d4196c3bcb54064d3e9526b86a80139eeb0178592df30df731cbc8c53f9e38cd89d
+  metadata.gz: cdeeba41310895026b7e5f7c0f79c382ab91d63a4a27a3e3131adb593f71b2bf780a4974b6b08a9c7fa163f1223acadece21a8d08bc652d45962269226958c94
+  data.tar.gz: 53859905dfad6b1b1e4944aff3357c13ec1fdcd0e1635962ce5d83811d7c625b08efa5da46c5eef76c22f0cf66cf5ac477a01796fff47499b6849a1fb3118fe2

data/lib/protocol/redis/cluster/methods/generic.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Protocol
+	module Redis
+		module Cluster
+			module Methods
+				# Provides generic Redis commands for cluster environments.
+				# These methods distribute operations across cluster nodes based on key slots.
+				module Generic
+					# Delete one or more keys from the cluster.
+					# Uses the appropriate client(s) for each key's slot.
+					# @parameter keys [Array(String)] The keys to delete.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @parameter options [Hash] Additional options passed to the client.
+					# @returns [Integer] The number of keys deleted.
+					def del(*keys, role: :master, **options)
+						return 0 if keys.empty?
+						
+						count = 0
+						
+						clients_for(*keys, role: role) do |client, grouped_keys|
+							count += client.call("DEL", *grouped_keys)
+						end
+						
+						return count
+					end
+					
+					# Check existence of one or more keys in the cluster.
+					# @parameter keys [Array(String)] The keys to check.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @parameter options [Hash] Additional options passed to the client.
+					# @returns [Integer] The number of keys existing.
+					def exists(*keys, role: :master, **options)
+						return 0 if keys.empty?
+						
+						count = 0
+						
+						clients_for(*keys, role: role) do |client, grouped_keys|
+							count += client.call("EXISTS", *grouped_keys)
+						end
+						
+						return count
+					end
+					
+					# Get the values of multiple keys from the cluster.
+					# @parameter keys [Array(String)] The keys to fetch.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @parameter options [Hash] Additional options passed to the client.
+					# @returns [Array] The values for the given keys, in order.
+					def mget(*keys, role: :master, **options)
+						return [] if keys.empty?
+						
+						results = Array.new(keys.size)
+						key_to_index = keys.each_with_index.to_h
+						
+						clients_for(*keys, role: role) do |client, grouped_keys|
+							values = client.call("MGET", *grouped_keys)
+							grouped_keys.each_with_index do |key, i|
+								results[key_to_index[key]] = values[i]
+							end
+						end
+						
+						return results
+					end
+					
+					# Get the value of a single key from the cluster.
+					# @parameter key [String] The key to fetch.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @parameter options [Hash] Additional options passed to the client.
+					# @returns [Object] The value for the given key.
+					def get(key, role: :master, **options)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("GET", key)
+					end
+					
+					# Set the value of a single key in the cluster.
+					# @parameter key [String] The key to set.
+					# @parameter value [Object] The value to set.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @parameter options [Hash] Additional options passed to the client.
+					# @returns [String | Boolean] Status reply or `true`/`false` depending on client implementation.
+					def set(key, value, role: :master, **options)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("SET", key, value)
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/redis/cluster/methods/pubsub.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Protocol
+	module Redis
+		module Cluster
+			module Methods
+				# Provides Redis Pub/Sub commands for cluster environments.
+				# Uses sharded pub/sub by default for optimal cluster performance.
+				module Pubsub
+					# Post a message to a channel using cluster-optimized sharded publish.
+					# Routes the message directly to the appropriate shard based on the channel name.
+					# @parameter channel [String] The channel name.
+					# @parameter message [String] The message to publish.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The number of clients that received the message.
+					def publish(channel, message, role: :master)
+						# Route to the correct shard based on channel name:
+						slot = slot_for(channel)
+						client = client_for(slot, role)
+						
+						return client.call("SPUBLISH", channel, message)
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/redis/cluster/methods/scripting.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+module Protocol
+	module Redis
+		module Cluster
+			module Methods
+				# Methods for managing Redis scripting in cluster environments.
+				# 
+				# Scripting operations in Redis clusters require careful consideration of key distribution.
+				# EVAL and EVALSHA operations are routed based on the keys they access, while SCRIPT
+				# management commands may need to be executed on specific nodes or all nodes.
+				module Scripting
+					# Execute a Lua script server side in a cluster environment.
+					# 
+					# The script will be executed on the node determined by the first key's slot.
+					# Redis will return a CROSSSLOT error if keys span multiple slots.
+					# 
+					# @parameter script [String] The Lua script to execute.
+					# @parameter key_count [Integer] Number of keys that follow.
+					# @parameter keys [Array[String]] The keys the script will access.
+					# @parameter args [Array[String]] Additional arguments to the script.
+					# @parameter role [Symbol] The role of the cluster node (:master or :slave).
+					# @returns [Object] The result of the script execution.
+					def eval(script, key_count = 0, *keys_and_args, role: :master)
+						if key_count == 0
+							# No keys, can execute on any client
+							any_client(role).call("EVAL", script, key_count, *keys_and_args)
+						else
+							# Extract keys for routing
+							keys = keys_and_args[0, key_count]
+							args = keys_and_args[key_count..-1] || []
+							
+							# Route to appropriate cluster node based on first key
+							# Redis will handle CROSSSLOT validation
+							slot = slot_for(keys.first)
+							client_for(slot, role).call("EVAL", script, key_count, *keys, *args)
+						end
+					end
+					
+					# Execute a cached Lua script by SHA1 digest in a cluster environment.
+					# 
+					# The script will be executed on the node determined by the first key's slot.
+					# Redis will return a CROSSSLOT error if keys span multiple slots.
+					# The script must already be loaded on the target node via SCRIPT LOAD.
+					# 
+					# @parameter sha1 [String] The SHA1 digest of the script to execute.
+					# @parameter key_count [Integer] Number of keys that follow.
+					# @parameter keys [Array[String]] The keys the script will access.
+					# @parameter args [Array[String]] Additional arguments to the script.
+					# @parameter role [Symbol] The role of the cluster node (:master or :slave).
+					# @returns [Object] The result of the script execution.
+					def evalsha(sha1, key_count = 0, *keys_and_args, role: :master)
+						if key_count == 0
+							# No keys, can execute on any client
+							any_client(role).call("EVALSHA", sha1, key_count, *keys_and_args)
+						else
+							# Extract keys for routing
+							keys = keys_and_args[0, key_count]
+							args = keys_and_args[key_count..-1] || []
+							
+							# Route to appropriate cluster node based on first key
+							# Redis will handle CROSSSLOT validation
+							slot = slot_for(keys.first)
+							client_for(slot, role).call("EVALSHA", sha1, key_count, *keys, *args)
+						end
+					end
+					
+					# Execute script management commands in a cluster environment.
+					# 
+					# Supported script subcommands:
+					# - DEBUG: Set the debug mode for executed scripts on the target node.
+					# - EXISTS: Check if scripts exist in the script cache on the target node.
+					# - FLUSH: Remove all scripts from the script cache (propagates cluster-wide when executed on master).
+					# - KILL: Kill the currently executing script on the target node.
+					# - LOAD: Load a script into the script cache (propagates cluster-wide when executed on master).
+					#
+					# It is unlikely that DEBUG, EXISTS and KILL are useful when run on a cluster node at random.
+					#
+					# @parameter subcommand [String|Symbol] The script subcommand (debug, exists, flush, load, kill).
+					# @parameter arguments [Array] Additional arguments for the subcommand.
+					# @parameter role [Symbol] The role of the cluster node (:master or :slave).
+					# @returns [Object] The result of the script command.
+					def script(subcommand, *arguments, role: :master)
+						any_client(role).call("SCRIPT", subcommand.to_s, *arguments)
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/redis/cluster/methods/streams.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Protocol
+	module Redis
+		module Cluster
+			module Methods
+				# Provides Redis Streams commands for cluster environments.
+				# Stream operations are routed to the appropriate shard based on the stream key.
+				module Streams
+					# Get information on streams and consumer groups.
+					# @parameter arguments [Array] XINFO command arguments (subcommand and stream key).
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Array] Stream information.
+					def xinfo(*arguments, role: :master)
+						# Extract stream key (usually the second argument after subcommand):
+						stream_key = arguments[1] if arguments.length > 1
+						
+						if stream_key
+							slot = slot_for(stream_key)
+							client = client_for(slot, role)
+						else
+							# Fallback for commands without a specific key:
+							client = any_client(role)
+						end
+						
+						return client.call("XINFO", *arguments)
+					end
+					
+					# Append a new entry to a stream.
+					# @parameter key [String] The stream key.
+					# @parameter arguments [Array] Additional XADD arguments (ID and field-value pairs).
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String] The ID of the added entry.
+					def xadd(key, *arguments, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XADD", key, *arguments)
+					end
+					
+					# Trim the stream to a certain size.
+					# @parameter key [String] The stream key.
+					# @parameter arguments [Array] Trim strategy and parameters.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] Number of entries removed.
+					def xtrim(key, *arguments, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XTRIM", key, *arguments)
+					end
+					
+					# Remove specified entries from the stream.
+					# @parameter key [String] The stream key.
+					# @parameter arguments [Array] Entry IDs to remove.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] Number of entries actually deleted.
+					def xdel(key, *arguments, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XDEL", key, *arguments)
+					end
+					
+					# Return a range of elements in a stream.
+					# @parameter key [String] The stream key.
+					# @parameter arguments [Array] Range parameters (start, end, optional COUNT).
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Array] Stream entries in the specified range.
+					def xrange(key, *arguments, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XRANGE", key, *arguments)
+					end
+					
+					# Return a range of elements in a stream in reverse order.
+					# @parameter key [String] The stream key.
+					# @parameter arguments [Array] Range parameters (end, start, optional COUNT).
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Array] Stream entries in reverse order.
+					def xrevrange(key, *arguments, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XREVRANGE", key, *arguments)
+					end
+					
+					# Return the number of entries in a stream.
+					# @parameter key [String] The stream key.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] Number of entries in the stream.
+					def xlen(key, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XLEN", key)
+					end
+					
+					# Read new entries from multiple streams.
+					# Note: In cluster mode, all streams in a single XREAD must be on the same shard.
+					# @parameter arguments [Array] XREAD arguments including STREAMS keyword and stream keys/IDs.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Array] New entries from the specified streams.
+					def xread(*arguments, role: :master)
+						# Extract first stream key to determine shard:
+						streams_index = arguments.index("STREAMS")
+						
+						if streams_index && streams_index + 1 < arguments.length
+							first_stream_key = arguments[streams_index + 1]
+							slot = slot_for(first_stream_key)
+							client = client_for(slot, role)
+						else
+							# Fallback if STREAMS keyword not found:
+							client = any_client(role)
+						end
+						
+						return client.call("XREAD", *arguments)
+					end
+					
+					# Create, destroy, and manage consumer groups.
+					# @parameter arguments [Array] XGROUP command arguments.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String | Integer] Command result.
+					def xgroup(*arguments, role: :master)
+						# Extract stream key (usually third argument for CREATE, second for others):
+						stream_key = case arguments[0]&.upcase
+																			when "CREATE", "SETID"
+																				arguments[1] # CREATE stream group id, SETID stream group id
+																			when "DESTROY", "DELCONSUMER"
+																				arguments[1] # DESTROY stream group, DELCONSUMER stream group consumer
+																			else
+																				arguments[1] if arguments.length > 1
+						end
+						
+						if stream_key
+							slot = slot_for(stream_key)
+							client = client_for(slot, role)
+						else
+							client = any_client(role)
+						end
+						
+						return client.call("XGROUP", *arguments)
+					end
+					
+					# Read new entries from streams using a consumer group.
+					# @parameter arguments [Array] XREADGROUP arguments.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Array] Entries for the consumer group.
+					def xreadgroup(*arguments, role: :master)
+						# Extract first stream key to determine shard:
+						streams_index = arguments.index("STREAMS")
+						
+						if streams_index && streams_index + 1 < arguments.length
+							first_stream_key = arguments[streams_index + 1]
+							slot = slot_for(first_stream_key)
+							client = client_for(slot, role)
+						else
+							client = any_client(role)
+						end
+						
+						return client.call("XREADGROUP", *arguments)
+					end
+					
+					# Acknowledge processed messages in a consumer group.
+					# @parameter key [String] The stream key.
+					# @parameter arguments [Array] Group name and message IDs.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] Number of messages acknowledged.
+					def xack(key, *arguments, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XACK", key, *arguments)
+					end
+					
+					# Change ownership of messages in a consumer group.
+					# @parameter key [String] The stream key.
+					# @parameter arguments [Array] Group, consumer, min-idle-time, and message IDs.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Array] Claimed messages.
+					def xclaim(key, *arguments, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XCLAIM", key, *arguments)
+					end
+					
+					# Get information about pending messages in a consumer group.
+					# @parameter key [String] The stream key.
+					# @parameter arguments [Array] Group name and optional consumer/range parameters.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Array] Pending message information.
+					def xpending(key, *arguments, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("XPENDING", key, *arguments)
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/redis/cluster/methods/strings.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module Protocol
+	module Redis
+		module Cluster
+			module Methods
+				# Provides Redis String commands for cluster environments.
+				# String operations are routed to the appropriate shard based on the key.
+				module Strings
+					# Append a value to a key.
+					# @parameter key [String] The key to append to.
+					# @parameter value [String] The value to append.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The length of the string after the append operation.
+					def append(key, value, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("APPEND", key, value)
+					end
+					
+					# Count set bits in a string.
+					# @parameter key [String] The key to count bits in.
+					# @parameter range [Array] Optional start and end positions.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The number of set bits.
+					def bitcount(key, *range, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("BITCOUNT", key, *range)
+					end
+					
+					# Decrement the integer value of a key by one.
+					# @parameter key [String] The key to decrement.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The value after decrementing.
+					def decr(key, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("DECR", key)
+					end
+					
+					# Decrement the integer value of a key by the given number.
+					# @parameter key [String] The key to decrement.
+					# @parameter decrement [Integer] The amount to decrement by.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The value after decrementing.
+					def decrby(key, decrement, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("DECRBY", key, decrement)
+					end
+					
+					# Get the value of a key.
+					# @parameter key [String] The key to get.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String | nil] The value, or `nil` if key doesn't exist.
+					def get(key, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("GET", key)
+					end
+					
+					# Get the bit value at offset in the string value stored at key.
+					# @parameter key [String] The key to get bit from.
+					# @parameter offset [Integer] The bit offset.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The bit value (0 or 1).
+					def getbit(key, offset, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("GETBIT", key, offset)
+					end
+					
+					# Get a substring of the string stored at a key.
+					# @parameter key [String] The key to get range from.
+					# @parameter start_index [Integer] The start position.
+					# @parameter end_index [Integer] The end position.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String] The substring.
+					def getrange(key, start_index, end_index, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("GETRANGE", key, start_index, end_index)
+					end
+					
+					# Set the string value of a key and return its old value.
+					# @parameter key [String] The key to set.
+					# @parameter value [String] The new value.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String | nil] The old value, or `nil` if key didn't exist.
+					def getset(key, value, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("GETSET", key, value)
+					end
+					
+					# Increment the integer value of a key by one.
+					# @parameter key [String] The key to increment.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The value after incrementing.
+					def incr(key, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("INCR", key)
+					end
+					
+					# Increment the integer value of a key by the given amount.
+					# @parameter key [String] The key to increment.
+					# @parameter increment [Integer] The amount to increment by.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The value after incrementing.
+					def incrby(key, increment, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("INCRBY", key, increment)
+					end
+					
+					# Increment the float value of a key by the given amount.
+					# @parameter key [String] The key to increment.
+					# @parameter increment [Float] The amount to increment by.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String] The value after incrementing (as string).
+					def incrbyfloat(key, increment, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("INCRBYFLOAT", key, increment)
+					end
+					
+					# Get the values of all the given keys.
+					# Uses the cluster-aware multi-key handling from generic methods.
+					# @parameter keys [Array(String)] The keys to get.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Array] The values for the given keys, in order.
+					def mget(*keys, role: :master)
+						return [] if keys.empty?
+						
+						results = Array.new(keys.size)
+						key_to_index = keys.each_with_index.to_h
+						
+						clients_for(*keys, role: role) do |client, grouped_keys|
+							values = client.call("MGET", *grouped_keys)
+							grouped_keys.each_with_index do |key, i|
+								results[key_to_index[key]] = values[i]
+							end
+						end
+						
+						return results
+					end
+					
+					# Set multiple keys to multiple values.
+					# Redis will return a CROSSSLOT error if keys span multiple slots.
+					# @parameter pairs [Hash] The key-value pairs to set.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String] Status reply.
+					def mset(pairs, role: :master)
+						return if pairs.empty?
+						
+						if pairs.is_a?(Hash)
+							pairs = pairs.to_a.flatten
+						end
+						
+						slot = slot_for(pairs.first)
+						client = client_for(slot, role)
+						
+						return client.call("MSET", *pairs)
+					end
+					
+					# Set multiple keys to multiple values, only if none exist.
+					# Redis will return a CROSSSLOT error if keys span multiple slots.
+					# @parameter pairs [Hash] The key-value pairs to set.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] 1 if all keys were set, 0 otherwise.
+					def msetnx(pairs, role: :master)
+						keys = pairs.keys
+						return 0 if keys.empty?
+						
+						flattened_pairs = pairs.keys.zip(pairs.values).flatten
+						slot = slot_for(keys.first)
+						client = client_for(slot, role)
+						
+						return client.call("MSETNX", *flattened_pairs)
+					end
+					
+					# Set the value and expiration in milliseconds of a key.
+					# @parameter key [String] The key to set.
+					# @parameter milliseconds [Integer] The expiration time in milliseconds.
+					# @parameter value [String] The value to set.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String] Status reply.
+					def psetex(key, milliseconds, value, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("PSETEX", key, milliseconds, value)
+					end
+					
+					# Set the string value of a key.
+					# @parameter key [String] The key to set.
+					# @parameter value [String] The value to set.
+					# @parameter update [Boolean | nil] If `true`, only update existing keys. If `false`, only set new keys.
+					# @parameter seconds [Integer | nil] Expiration time in seconds.
+					# @parameter milliseconds [Integer | nil] Expiration time in milliseconds.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String] Status reply.
+					def set(key, value, update: nil, seconds: nil, milliseconds: nil, role: :master)
+						arguments = []
+						
+						if seconds
+							arguments << "EX" << seconds
+						end
+						
+						if milliseconds
+							arguments << "PX" << milliseconds
+						end
+						
+						if update == true
+							arguments << "XX"
+						elsif update == false
+							arguments << "NX"
+						end
+						
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("SET", key, value, *arguments)
+					end
+					
+					# Set or clear the bit at offset in the string value stored at key.
+					# @parameter key [String] The key to modify.
+					# @parameter offset [Integer] The bit offset.
+					# @parameter value [Integer] The bit value (0 or 1).
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The original bit value.
+					def setbit(key, offset, value, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("SETBIT", key, offset, value)
+					end
+					
+					# Set the value and expiration of a key.
+					# @parameter key [String] The key to set.
+					# @parameter seconds [Integer] The expiration time in seconds.
+					# @parameter value [String] The value to set.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [String] Status reply.
+					def setex(key, seconds, value, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("SETEX", key, seconds, value)
+					end
+					
+					# Set the value of a key, only if the key does not exist.
+					# @parameter key [String] The key to set.
+					# @parameter value [String] The value to set.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Boolean] `true` if the key was set, `false` otherwise.
+					def setnx(key, value, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("SETNX", key, value) == 1
+					end
+					
+					# Overwrite part of a string at key starting at the specified offset.
+					# @parameter key [String] The key to modify.
+					# @parameter offset [Integer] The offset to start overwriting at.
+					# @parameter value [String] The value to write.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The length of the string after modification.
+					def setrange(key, offset, value, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("SETRANGE", key, offset, value)
+					end
+					
+					# Get the length of the value stored in a key.
+					# @parameter key [String] The key to get length of.
+					# @parameter role [Symbol] The role of node to use (`:master` or `:slave`).
+					# @returns [Integer] The length of the string value, or 0 if key doesn't exist.
+					def strlen(key, role: :master)
+						slot = slot_for(key)
+						client = client_for(slot, role)
+						
+						return client.call("STRLEN", key)
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/redis/cluster/methods.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "methods/generic"
+require_relative "methods/pubsub"
+require_relative "methods/streams"
+require_relative "methods/strings"
+
+module Protocol
+	module Redis
+		# @namespace
+		module Cluster
+			# A collection of methods for interacting with Redis in cluster mode.
+			module Methods
+				# Includes all Redis methods into the given class.
+				def self.included(klass)
+					klass.include Methods::Generic
+					klass.include Methods::Pubsub
+					klass.include Methods::Streams
+					klass.include Methods::Strings
+				end
+			end
+		end
+	end
+end

data/lib/protocol/redis/connection.rb

@@ -137,7 +137,7 @@ module Protocol
 				else
 					@stream.flush
 					
-					raise NotImplementedError, "Implementation for token #{token} missing"
+					raise UnknownTokenError, token.inspect
 				end
 				
 				# TODO: If an exception (e.g. Async::TimeoutError) propagates out of this function, perhaps @stream should be closed? Otherwise it might be in a weird state.

data/lib/protocol/redis/error.rb

@@ -12,5 +12,9 @@ module Protocol
 		# Represents an error response from the Redis server.
 		class ServerError < Error
 		end
+		
+		# Represents an unknown token error in the Redis protocol.
+		class UnknownTokenError < Error
+		end
 	end
 end

data/lib/protocol/redis/methods/scripting.rb

@@ -7,32 +7,30 @@
 module Protocol
 	module Redis
 		module Methods
-			# Mehtods for managing Redis scripting.
+			# Methods for managing Redis scripting.
 			module Scripting
-				# Execute a Lua script server side. Depends on the script that is executed.
-				# See <https://redis.io/commands/eval> for more details.
-				# @parameter script [String]
-				# @parameter numkeys [Integer]
-				# @parameter key [Key] Multiple keys are supported, as long as the same number of values are also provided
-				# @parameter arg [String]
-				def eval(*arguments)
-					call("EVAL", *arguments)
+				# Execute a Lua script server side.
+				# @parameter script [String] The Lua script to execute.
+				# @parameter key_count [Integer] Number of keys that follow.
+				# @parameter keys_and_args [Array] Keys followed by arguments to the script.
+				# @returns [Object] The result of the script execution.
+				def eval(script, key_count = 0, *keys_and_args)
+					call("EVAL", script, key_count, *keys_and_args)
 				end
 				
-				# Execute a Lua script server side. Depends on the script that is executed.
-				# See <https://redis.io/commands/evalsha> for more details.
-				# @parameter sha1 [String]
-				# @parameter numkeys [Integer]
-				# @parameter key [Key]
-				# @parameter arg [String]
-				def evalsha(*arguments)
-					call("EVALSHA", *arguments)
+				# Execute a cached Lua script by SHA1 digest.
+				# @parameter sha1 [String] The SHA1 digest of the script to execute.
+				# @parameter key_count [Integer] Number of keys that follow.
+				# @parameter keys_and_args [Array] Keys followed by arguments to the script.
+				# @returns [Object] The result of the script execution.
+				def evalsha(sha1, key_count = 0, *keys_and_args)
+					call("EVALSHA", sha1, key_count, *keys_and_args)
 				end
 				
-				# Execute script management commands
-				# See <https://redis.io/commands/script/> for more details.
-				# @parameter subcommand [String] e.g. `debug`, `exists`, `flush`, `load`, `kill`
-				# @parameter [Array(String)] arguments depends on the subcommand provided
+				# Execute script management commands.
+				# @parameter subcommand [String|Symbol] The script subcommand (debug, exists, flush, load, kill).
+				# @parameter arguments [Array] Additional arguments for the subcommand.
+				# @returns [Object] The result of the script command.
 				def script(subcommand, *arguments)
 					call("SCRIPT", subcommand.to_s, *arguments)
 				end

data/lib/protocol/redis/methods/strings.rb

@@ -103,9 +103,11 @@ module Protocol
 				# Set multiple keys to multiple values. O(N) where N is the number of keys to set.
 				# See <https://redis.io/commands/mset> for more details.
 				def mset(pairs)
-					flattened_pairs = pairs.keys.zip(pairs.values).flatten
+					if pairs.is_a?(Hash)
+						pairs = pairs.to_a.flatten
+					end
 					
-					call("MSET", *flattened_pairs)
+					call("MSET", *pairs)
 				end
 				
 				# Set multiple keys to multiple values, only if none of the keys exist. O(N) where N is the number of keys to set.

data/lib/protocol/redis/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module Redis
-		VERSION = "0.10.0"
+		VERSION = "0.11.0"
 	end
 end

data/readme.md

@@ -14,6 +14,10 @@ Please see the [project documentation](https://socketry.github.io/protocol-redis
 
 Please see the [project releases](https://socketry.github.io/protocol-redis/releases/index) for all releases.
 
+### v0.11.0
+
+  - Introduce cluster methods, including `Strings`, `Streams`, `Scripting` and `Pubsub`.
+
 ### v0.10.0
 
   - Add agent context.
@@ -63,10 +67,6 @@ Please see the [project releases](https://socketry.github.io/protocol-redis/rele
   - Improve argument management.
   - Modernize testing infrastructure.
 
-### v0.4.2
-
-  - Prefer implicit returns and improve return value for `setnx`.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.11.0
+
+  - Introduce cluster methods, including `Strings`, `Streams`, `Scripting` and `Pubsub`.
+
 ## v0.10.0
 
   - Add agent context.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-redis
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -53,6 +53,12 @@ files:
 - context/getting-started.md
 - context/index.yaml
 - lib/protocol/redis.rb
+- lib/protocol/redis/cluster/methods.rb
+- lib/protocol/redis/cluster/methods/generic.rb
+- lib/protocol/redis/cluster/methods/pubsub.rb
+- lib/protocol/redis/cluster/methods/scripting.rb
+- lib/protocol/redis/cluster/methods/streams.rb
+- lib/protocol/redis/cluster/methods/strings.rb
 - lib/protocol/redis/connection.rb
 - lib/protocol/redis/error.rb
 - lib/protocol/redis/methods.rb