100% documentation coverage.

Author: ioquatix

lib/async/redis.rb

@@ -6,6 +6,14 @@
 
 require_relative "redis/version"
 require_relative "redis/client"
+require_relative "redis/endpoint"
 
 require_relative "redis/cluster_client"
 require_relative "redis/sentinel_client"
+
+# @namespace
+module Async
+	# @namespace
+	module Redis
+	end
+end

lib/async/redis/client.rb

@@ -23,10 +23,18 @@ module Redis
 		# Legacy.
 		ServerError = ::Protocol::Redis::ServerError
 
+		# A Redis client that provides connection pooling and context management.
 		class Client
 			include ::Protocol::Redis::Methods
 
+			# Methods module providing Redis-specific functionality.
 			module Methods
+				# Subscribe to one or more channels for pub/sub messaging.
+				# @parameter channels [Array(String)] The channels to subscribe to.
+				# @yields {|context| ...} If a block is given, it will be executed within the subscription context.
+				# 	@parameter context [Context::Subscribe] The subscription context.
+				# @returns [Object] The result of the block if block given.
+				# @returns [Context::Subscribe] The subscription context if no block given.
 				def subscribe(*channels)
 					context = Context::Subscribe.new(@pool, channels)
 
@@ -39,6 +47,11 @@ def subscribe(*channels)
 					end
 				end
 
+				# Execute commands within a Redis transaction.
+				# @yields {|context| ...} If a block is given, it will be executed within the transaction context.
+				# 	@parameter context [Context::Transaction] The transaction context.
+				# @returns [Object] The result of the block if block given.
+				# @returns [Context::Transaction] Else if no block is given, returns the transaction context.
 				def transaction(&block)
 					context = Context::Transaction.new(@pool)
 
@@ -53,6 +66,11 @@ def transaction(&block)
 
 				alias multi transaction
 
+				# Execute commands in a pipeline for improved performance.
+				# @yields {|context| ...} If a block is given, it will be executed within the pipeline context.
+				# 	@parameter context [Context::Pipeline] The pipeline context.
+				# @returns [Object] The result of the block if block given.
+				# @returns [Context::Pipeline] The pipeline context if no block given.
 				def pipeline(&block)
 					context = Context::Pipeline.new(@pool)
 
@@ -68,6 +86,9 @@ def pipeline(&block)
 				# Deprecated.
 				alias nested pipeline
 
+				# Execute a Redis command directly.
+				# @parameter arguments [Array] The command and its arguments.
+				# @returns [Object] The response from the Redis server.
 				def call(*arguments)
 					@pool.acquire do |connection|
 						connection.write_request(arguments)
@@ -78,25 +99,37 @@ def call(*arguments)
 					end
 				end
 
+				# Close the client and all its connections.
 				def close
 					@pool.close
 				end
 			end
 
 			include Methods
 
+			# Create a new Redis client.
+			# @parameter endpoint [Endpoint] The Redis endpoint to connect to.
+			# @parameter protocol [Protocol] The protocol to use for communication.
+			# @parameter options [Hash] Additional options for the connection pool.
 			def initialize(endpoint = Endpoint.local, protocol: endpoint.protocol, **options)
 				@endpoint = endpoint
 				@protocol = protocol
 
 				@pool = make_pool(**options)
 			end
 
+			# @attribute [Endpoint] The Redis endpoint.
 			attr :endpoint
+			
+			# @attribute [Protocol] The communication protocol.
 			attr :protocol
 
-			# @return [client] if no block provided.
-			# @yield [client, task] yield the client in an async task.
+			# Open a Redis client and optionally yield it in an async task.
+			# @yields {|client, task| ...} If a block is given, yield the client in an async task.
+			# 	@parameter client [Client] The Redis client instance.
+			# 	@parameter task [Async::Task] The async task.
+			# @returns [Client] The client if no block provided.
+			# @returns [Object] The result of the block if block given.
 			def self.open(*arguments, **options, &block)
 				client = self.new(*arguments, **options)
 

lib/async/redis/cluster_client.rb

@@ -9,26 +9,39 @@
 
 module Async
 	module Redis
+		# A Redis cluster client that manages multiple Redis instances and handles cluster operations.
 		class ClusterClient
+			# Raised when cluster configuration cannot be reloaded.
 			class ReloadError < StandardError
 			end
 
+			# Raised when no nodes are found for a specific slot.
 			class SlotError < StandardError
 			end
 
 			Node = Struct.new(:id, :endpoint, :role, :health, :client)
 
+			# A map that stores ranges and their associated values for efficient lookup.
 			class RangeMap
+				# Initialize a new RangeMap.
 				def initialize
 					@ranges = []
 				end
 
+				# Add a range-value pair to the map.
+				# @parameter range [Range] The range to map.
+				# @parameter value [Object] The value to associate with the range.
+				# @returns [Object] The added value.
 				def add(range, value)
 					@ranges << [range, value]
 
 					return value
 				end
 
+				# Find the value associated with a key within any range.
+				# @parameter key [Object] The key to find.
+				# @yields {...} Block called if no range contains the key.
+				# @returns [Object] The value if found, result of block if given, or nil.
 				def find(key)
 					@ranges.each do |range, value|
 						return value if range.include?(key)
@@ -41,12 +54,16 @@ def find(key)
 					return nil
 				end
 
+				# Iterate over all values in the map.
+				# @yields {|value| ...} Block called for each value.
+				# 	@parameter value [Object] The value from the range-value pair.
 				def each
 					@ranges.each do |range, value|
 						yield value
 					end
 				end
 
+				# Clear all ranges from the map.
 				def clear
 					@ranges.clear
 				end
@@ -61,6 +78,13 @@ def initialize(endpoints, **options)
 				@shards = nil
 			end
 
+			# Execute a block with clients for the given keys, grouped by cluster slot.
+			# @parameter keys [Array] The keys to find clients for.
+			# @parameter role [Symbol] The role of nodes to use (:master or :slave).
+			# @parameter attempts [Integer] Number of retry attempts for cluster errors.
+			# @yields {|client, keys| ...} Block called for each client-keys pair.
+			# 	@parameter client [Client] The Redis client for the slot.
+			# 	@parameter keys [Array] The keys handled by this client.
 			def clients_for(*keys, role: :master, attempts: 3)
 				slots = slots_for(keys)
 
@@ -83,6 +107,10 @@ def clients_for(*keys, role: :master, attempts: 3)
 				end
 			end
 
+			# Get a client for a specific slot.
+			# @parameter slot [Integer] The cluster slot number.
+			# @parameter role [Symbol] The role of node to get (:master or :slave).
+			# @returns [Client] The Redis client for the slot.
 			def client_for(slot, role = :master)
 				unless @shards
 					reload_cluster!
@@ -203,6 +231,9 @@ def slot_for(key)
 				return crc16(key) % HASH_SLOTS
 			end
 
+			# Calculate the hash slots for multiple keys.
+			# @parameter keys [Array] The keys to calculate slots for.
+			# @returns [Hash] A hash mapping slot numbers to arrays of keys.
 			def slots_for(keys)
 				slots = Hash.new{|hash, key| hash[key] = []}
 

lib/async/redis/context/generic.rb

@@ -8,30 +8,45 @@
 
 module Async
 	module Redis
+		# @namespace
 		module Context
+			# Base class for Redis command execution contexts.
 			class Generic
+				# Initialize a new generic context.
+				# @parameter pool [Pool] The connection pool to use.
+				# @parameter arguments [Array] Additional arguments for the context.
 				def initialize(pool, *arguments)
 					@pool = pool
 					@connection = pool.acquire
 				end
 
+				# Close the context and release the connection back to the pool.
 				def close
 					if @connection
 						@pool.release(@connection)
 						@connection = nil
 					end
 				end
 
+				# Write a Redis command request to the connection.
+				# @parameter command [String] The Redis command.
+				# @parameter arguments [Array] The command arguments.
 				def write_request(command, *arguments)
 					@connection.write_request([command, *arguments])
 				end
 
+				# Read a response from the Redis connection.
+				# @returns [Object] The Redis response.
 				def read_response
 					@connection.flush
 
 					return @connection.read_response
 				end
 
+				# Execute a Redis command and return the response.
+				# @parameter command [String] The Redis command.
+				# @parameter arguments [Array] The command arguments.
+				# @returns [Object] The Redis response.
 				def call(command, *arguments)
 					write_request(command, *arguments)
 

lib/async/redis/context/pipeline.rb

@@ -14,9 +14,12 @@ module Context
 			class Pipeline < Generic
 				include ::Protocol::Redis::Methods
 
+				# A synchronous wrapper for pipeline operations that executes one command at a time.
 				class Sync
 					include ::Protocol::Redis::Methods
 
+					# Initialize a new sync wrapper.
+					# @parameter pipeline [Pipeline] The pipeline to wrap.
 					def initialize(pipeline)
 						@pipeline = pipeline
 					end
@@ -31,6 +34,8 @@ def call(...)
 					end
 				end
 
+				# Initialize a new pipeline context.
+				# @parameter pool [Pool] The connection pool to use.
 				def initialize(pool)
 					super(pool)
 
@@ -46,6 +51,9 @@ def flush(count = 0)
 					end
 				end
 
+				# Collect all pending responses.
+				# @yields {...} Optional block to execute while collecting responses.
+				# @returns [Array] Array of all responses if no block given.
 				def collect
 					if block_given?
 						flush
@@ -55,6 +63,8 @@ def collect
 					@count.times.map{read_response}
 				end
 
+				# Get a synchronous wrapper for this pipeline.
+				# @returns [Sync] A synchronous wrapper that executes commands immediately.
 				def sync
 					@sync ||= Sync.new(self)
 				end
@@ -73,6 +83,8 @@ def call(command, *arguments)
 					return nil
 				end
 
+				# Read a response from the pipeline.
+				# @returns [Object] The next response in the pipeline.
 				def read_response
 					if @count > 0
 						@count -= 1
@@ -82,6 +94,7 @@ def read_response
 					end
 				end
 
+				# Close the pipeline and flush all pending responses.
 				def close
 					flush
 				ensure

lib/async/redis/context/subscribe.rb

@@ -9,28 +9,38 @@
 module Async
 	module Redis
 		module Context
+			# Context for Redis pub/sub subscription operations.
 			class Subscribe < Generic
 				MESSAGE = "message"
 
+				# Initialize a new subscription context.
+				# @parameter pool [Pool] The connection pool to use.
+				# @parameter channels [Array(String)] The channels to subscribe to.
 				def initialize(pool, channels)
 					super(pool)
 
 					subscribe(channels)
 				end
 
+				# Close the subscription context.
 				def close
 					# There is no way to reset subscription state. On Redis v6+ you can use RESET, but this is not supported in <= v6.
 					@connection&.close
 
 					super
 				end
 
+				# Listen for the next message from subscribed channels.
+				# @returns [Array] The next message response, or nil if connection closed.
 				def listen
 					while response = @connection.read_response
 						return response if response.first == MESSAGE
 					end
 				end
 
+				# Iterate over all messages from subscribed channels.
+				# @yields {|response| ...} Block called for each message.
+				# 	@parameter response [Array] The message response.
 				def each
 					return to_enum unless block_given?
 
@@ -39,11 +49,15 @@ def each
 					end
 				end
 
+				# Subscribe to additional channels.
+				# @parameter channels [Array(String)] The channels to subscribe to.
 				def subscribe(channels)
 					@connection.write_request ["SUBSCRIBE", *channels]
 					@connection.flush
 				end
 
+				# Unsubscribe from channels.
+				# @parameter channels [Array(String)] The channels to unsubscribe from.
 				def unsubscribe(channels)
 					@connection.write_request ["UNSUBSCRIBE", *channels]
 					@connection.flush

lib/async/redis/context/transaction.rb

@@ -9,15 +9,22 @@
 module Async
 	module Redis
 		module Context
+			# Context for Redis transaction operations using MULTI/EXEC.
 			class Transaction < Pipeline
+				# Initialize a new transaction context.
+				# @parameter pool [Pool] The connection pool to use.
+				# @parameter arguments [Array] Additional arguments for the transaction.
 				def initialize(pool, *arguments)
 					super(pool)
 				end
 
+				# Begin a transaction block.
 				def multi
 					call("MULTI")
 				end
 
+				# Watch keys for changes during the transaction.
+				# @parameter keys [Array(String)] The keys to watch.
 				def watch(*keys)
 					sync.call("WATCH", *keys)
 				end
@@ -27,6 +34,7 @@ def execute
 					sync.call("EXEC")
 				end
 
+				# Discard all queued commands in the transaction.
 				def discard
 					sync.call("DISCARD")
 				end