protocol-redis 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4eaf2e185b9e0b2f5a29527a83e803e56bd89470ebbd800519338db47c33ae8
-  data.tar.gz: 6954fa6365d178dca0ff302b5b1739e9d731dd72df61a9238f6d16a152640318
+  metadata.gz: 77a3cf15694be52495a873fe8e807a5fb96909bdf0642a6619d26281b14a5aa8
+  data.tar.gz: fd4602f3b11bbf724a863a1012e1105add29017a8e4e6b6f7ae50be502df9cd8
 SHA512:
-  metadata.gz: d85825ba053ca54ae00e329edef4ae7bcb0b06afc5c3752d777faa20439fff39d0a4bf9cd293f675a36859b5bb7fa8417c449fc6efe3fa0664892ad8f7b7593e
-  data.tar.gz: 503526c37e829a7272c0a43c458f514544d9b1514410f957c1b8ef669bab5701c0a892143cd9c4f83b9e3186551e6a7be135f6b8d087fc4d223cbb1e39571a60
+  metadata.gz: b9e1310a24336a7aff3d5d23d3f43adbb18cbc70089a1daae360f9c835fc843ad886d81da80b34f5140f1bc58cde08630855fbc5e81486512a75944cd9c72b3e
+  data.tar.gz: 888798d1c44e1f8b8883c3f016ef00f0f47b13113b5a8cc5d087b1039d340d4196c3bcb54064d3e9526b86a80139eeb0178592df30df731cbc8c53f9e38cd89d

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/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,15 +125,15 @@ 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
 					
@@ -115,9 +144,9 @@ module Protocol
 			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,9 +5,11 @@
 
 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
 	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