protocol-redis 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4eaf2e185b9e0b2f5a29527a83e803e56bd89470ebbd800519338db47c33ae8
-  data.tar.gz: 6954fa6365d178dca0ff302b5b1739e9d731dd72df61a9238f6d16a152640318
+  metadata.gz: b39632c3f7210dd4eea7d4b561a74c94442434a3e9ae9220d44303ea51aba2af
+  data.tar.gz: 6a930186fd89b24a6469a79025de532bd638a8e942228dffe25c4a4752561731
 SHA512:
-  metadata.gz: d85825ba053ca54ae00e329edef4ae7bcb0b06afc5c3752d777faa20439fff39d0a4bf9cd293f675a36859b5bb7fa8417c449fc6efe3fa0664892ad8f7b7593e
-  data.tar.gz: 503526c37e829a7272c0a43c458f514544d9b1514410f957c1b8ef669bab5701c0a892143cd9c4f83b9e3186551e6a7be135f6b8d087fc4d223cbb1e39571a60
+  metadata.gz: cdeeba41310895026b7e5f7c0f79c382ab91d63a4a27a3e3131adb593f71b2bf780a4974b6b08a9c7fa163f1223acadece21a8d08bc652d45962269226958c94
+  data.tar.gz: 53859905dfad6b1b1e4944aff3357c13ec1fdcd0e1635962ce5d83811d7c625b08efa5da46c5eef76c22f0cf66cf5ac477a01796fff47499b6849a1fb3118fe2

checksums.yaml.gz.sig

@@ -1,2 +1 @@
-x���	HiA��l�D.���M�<~�N�?k�6/�ֿ��z��M�뿝rF5�LtpD�
-�S7fT���_
+x��n1�Xԋ�!��<VT}�)�3�a�i<CaX�d<��@�t�?d

data/context/getting-started.md

@@ -0,0 +1,55 @@
+# Getting Started
+
+This guide explains how to use the `Protocol::Redis` gem to implement the RESP2 and RESP3 Redis protocols for low level client and server implementations.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add protocol-redis
+```
+
+## Usage
+
+Here is a basic example communicating over a bi-directional socket pair:
+
+``` ruby
+sockets = Socket.pair(Socket::PF_UNIX, Socket::SOCK_STREAM)
+
+client = Protocol::Redis::Connection.new(sockets.first)
+server = Protocol::Redis::Connection.new(sockets.last)
+
+client.write_object("Hello World!")
+puts server.read_object
+# => "Hello World!"
+```
+
+## Methods
+
+{ruby Protocol::Redis::Methods} provides access to documented Redis commands. You can use these methods by inluding the module in your class:
+
+``` ruby
+class MyRedisClient
+	include Protocol::Redis::Methods
+	
+	def call(*arguments)
+		connection = self.acquire # Connection management is up to you
+		
+		connection.write_request(arguments)
+		connection.flush
+		
+		return connection.read_response
+	end
+end
+```
+You can then call Redis commands like this:
+
+``` ruby
+client = MyRedisClient.new
+client.set("key", "value")
+```
+
+### Valkey Support
+
+You can always use `#call` to send any command. This library provides a set of methods for what we believe are the most commonly used commands (in other words, the intersection of Redis and Valkey commands). If you need more commands, youn could define these yourself similarly to how {ruby Protocol::Redis::Methods} does.

data/context/index.yaml

@@ -0,0 +1,13 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A transport agnostic RESP protocol client/server.
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-redis/
+  funding_uri: https://github.com/sponsors/ioquatix
+  source_code_uri: https://github.com/socketry/protocol-redis.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use the `Protocol::Redis` gem to implement
+    the RESP2 and RESP3 Redis protocols for low level client and server implementations.

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