protocol-redis 0.9.0 → 0.11.0

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

@@ -3,13 +3,16 @@
 # Released under the MIT License.
 # Copyright, 2019-2023, by Samuel Williams.
 
-require_relative 'error'
+require_relative "error"
 
 module Protocol
 	module Redis
+		# Represents a Redis protocol connection handling low-level communication.
 		class Connection
 			CRLF = "\r\n".freeze
 			
+			# Initialize a new connection with the provided stream.
+			# @parameter stream [IO] The underlying stream for communication.
 			def initialize(stream)
 				@stream = stream
 				
@@ -22,18 +25,23 @@ module Protocol
 			# @attr [Integer] Number of requests sent.
 			attr :count
 			
+			# Close the underlying stream connection.
 			def close
 				@stream.close
 			end
 			
 			class << self
+				# Create a new client connection instance.
 				alias client new
 			end
 			
+			# Flush any buffered data to the stream.
 			def flush
 				@stream.flush
 			end
 			
+			# Check if the connection is closed.
+			# @returns [Boolean] True if the connection is closed.
 			def closed?
 				@stream.closed?
 			end
@@ -51,6 +59,8 @@ module Protocol
 				end
 			end
 			
+			# Write a Redis object to the stream.
+			# @parameter object [Object] The object to write (String, Array, Integer, or object with to_redis method).
 			def write_object(object)
 				case object
 				when String
@@ -59,11 +69,26 @@ module Protocol
 					write_array(object)
 				when Integer
 					write_lines(":#{object}")
+				when nil
+					write_lines("$-1")
 				else
 					write_object(object.to_redis)
 				end
 			end
 			
+			# Write a Redis array to the stream.
+			# @parameter array [Array] The array to write.
+			def write_array(array)
+				write_lines("*#{array.size}")
+				
+				array.each do |element|
+					write_object(element)
+				end
+			end
+			
+			# Read data of specified length from the stream.
+			# @parameter length [Integer] The number of bytes to read.
+			# @returns [String] The data read from the stream.
 			def read_data(length)
 				buffer = @stream.read(length) or @stream.eof!
 				
@@ -73,13 +98,17 @@ module Protocol
 				return buffer
 			end
 			
+			# Read and parse a Redis object from the stream.
+			# @returns [Object] The parsed Redis object (String, Array, Integer, or nil).
+			# @raises [ServerError] If the server returns an error response.
+			# @raises [EOFError] If the stream reaches end of file.
 			def read_object
 				line = read_line or raise EOFError
 				
 				token = line.slice!(0, 1)
 				
 				case token
-				when '$'
+				when "$"
 					length = line.to_i
 					
 					if length == -1
@@ -87,7 +116,7 @@ module Protocol
 					else
 						return read_data(length)
 					end
-				when '*'
+				when "*"
 					count = line.to_i
 					
 					# Null array (https://redis.io/topics/protocol#resp-arrays):
@@ -96,28 +125,28 @@ module Protocol
 					array = Array.new(count) {read_object}
 					
 					return array
-				when ':'
+				when ":"
 					return line.to_i
-				
-				when '-'
+					
+				when "-"
 					raise ServerError.new(line)
-				
-				when '+'
+					
+				when "+"
 					return line
-				
+					
 				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.
 			end
 			
 			alias read_response read_object
-
+			
 			private
-
+			
 			# In the case of Redis, we do not want to perform a flush in every line,
 			# because each Redis command contains several lines. Flushing once per
 			# command is more efficient because it avoids unnecessary writes to the

data/lib/protocol/redis/error.rb

@@ -5,10 +5,16 @@
 
 module Protocol
 	module Redis
+		# Represents a general Redis protocol error.
 		class Error < StandardError
 		end
 		
+		# 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/cluster.rb

@@ -2,25 +2,27 @@
 
 # Released under the MIT License.
 # Copyright, 2023, by Nick Burwell.
+# Copyright, 2024, by Samuel Williams.
 
 module Protocol
 	module Redis
 		module Methods
+			# Methods for managing Redis clusters.
 			module Cluster
 				# Sends the `CLUSTER *` command to random node and returns its reply.
-				# @see https://redis.io/commands/cluster-addslots/
-				# @param subcommand [String, Symbol] the subcommand of cluster command
+				# See <https://redis.io/commands/cluster-addslots/> for more details.
+				# @parameter subcommand [String, Symbol] the subcommand of cluster command
 				#   e.g. `:addslots`, `:delslots`, `:nodes`, `:replicas`, `:info`
 				#
-				# @return [Object] depends on the subcommand provided
-				def cluster(subcommand, *args)
-					call("CLUSTER", subcommand.to_s, *args)
+				# @returns [Object] depends on the subcommand provided
+				def cluster(subcommand, *arguments)
+					call("CLUSTER", subcommand.to_s, *arguments)
 				end
 				
 				# Sends `ASKING` command to random node and returns its reply.
-				# @see https://redis.io/commands/asking/
+				# See <https://redis.io/commands/asking/> for more details.
 				#
-				# @return [String] `'OK'`
+				# @returns [String] `'OK'`
 				def asking
 					call("ASKING")
 				end

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

@@ -6,31 +6,32 @@
 module Protocol
 	module Redis
 		module Methods
+			# Methods for managing Redis connections.
 			module Connection
 				# Authenticate to the server.
-				# @see https://redis.io/commands/auth
-				# @param username [String] Optional username, if Redis ACLs are used.
-				# @param password [String] Required password.
+				# See <https://redis.io/commands/auth> for more details.
+				# @parameter username [String] Optional username, if Redis ACLs are used.
+				# @parameter password [String] Required password.
 				def auth(*arguments)
 					call("AUTH", *arguments)
 				end
 				
 				# Echo the given string.
-				# @see https://redis.io/commands/echo
-				# @param message [String]
+				# See <https://redis.io/commands/echo> for more details.
+				# @parameter message [String]
 				def echo(message)
 					call("ECHO", message)
 				end
 				
 				# Ping the server.
-				# @see https://redis.io/commands/ping
-				# @param message [String]
+				# See <https://redis.io/commands/ping> for more details.
+				# @parameter message [String]
 				def ping(message)
 					call("PING", message)
 				end
 				
 				# Close the connection.
-				# @see https://redis.io/commands/quit
+				# See <https://redis.io/commands/quit> for more details.
 				def quit
 					call("QUIT")
 				end

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

@@ -6,26 +6,27 @@
 module Protocol
 	module Redis
 		module Methods
+			# Methods for managing Redis HyperLogLogs.
 			module Counting
 				# Adds the specified elements to the specified HyperLogLog. O(1) to add every element.
-				# @see https://redis.io/commands/pfadd
-				# @param key [Key]
-				# @param element [String]
+				# See <https://redis.io/commands/pfadd> for more details.
+				# @parameter key [Key]
+				# @parameter element [String]
 				def pfadd(key, element, *elements)
 					call("PFADD", key, element, *elements)
 				end
 				
 				# Return the approximated cardinality of the set(s) observed by the HyperLogLog at key(s). O(1) with a very small average constant time when called with a single key. O(N) with N being the number of keys, and much bigger constant times, when called with multiple keys.
-				# @see https://redis.io/commands/pfcount
-				# @param key [Key]
+				# See <https://redis.io/commands/pfcount> for more details.
+				# @parameter key [Key]
 				def pfcount(key, *keys)
 					call("PFCOUNT", key, *keys)
 				end
 				
 				# Merge N different HyperLogLogs into a single one. O(N) to merge N HyperLogLogs, but with high constant times.
-				# @see https://redis.io/commands/pfmerge
-				# @param destkey [Key]
-				# @param sourcekey [Key]
+				# See <https://redis.io/commands/pfmerge> for more details.
+				# @parameter destkey [Key]
+				# @parameter sourcekey [Key]
 				def pfmerge(destkey, sourcekey, *sourcekeys)
 					call("PFMERGE", destkey, sourcekey, *sourcekeys)
 				end