async-redis 0.11.1 → 0.12.0

data/lib/async/redis/cluster_subscription.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/limited_queue"
+require "async/barrier"
+
+module Async
+	module Redis
+		# Context for managing sharded subscriptions across multiple Redis cluster nodes.
+		# This class handles the complexity of subscribing to channels that may be distributed
+		# across different shards in a Redis cluster.
+		class ClusterSubscription
+			# Represents a failure in the subscription process, e.g. network issues, shard failures.
+			class SubscriptionError < StandardError
+			end
+			
+			# Initialize a new shard subscription context.
+			# @parameter cluster_client [ClusterClient] The cluster client to use.
+			def initialize(cluster_client, queue: Async::LimitedQueue.new)
+				@cluster_client = cluster_client
+				@subscriptions = {}
+				@channels = []
+				
+				@barrier = Async::Barrier.new
+				@queue = queue
+			end
+			
+			# Close all shard subscriptions.
+			def close
+				if barrier = @barrier
+					@barrier = nil
+					barrier.stop
+				end
+				
+				@subscriptions.each_value(&:close)
+				@subscriptions.clear
+			end
+			
+			# Listen for the next message from any subscribed shard.
+			# @returns [Array] The next message response.
+			# @raises [SubscriptionError] If the subscription has failed for any reason.
+			def listen
+				@queue.pop
+			rescue => error
+				raise SubscriptionError, "Failed to read message!"
+			end
+			
+			# Iterate over all messages from all subscribed shards.
+			# @yields {|response| ...} Block called for each message.
+			# 	@parameter response [Array] The message response.
+			def each
+				return to_enum unless block_given?
+				
+				while response = self.listen
+					yield response
+				end
+			end
+			
+			# Subscribe to additional sharded channels.
+			# @parameter channels [Array(String)] The channels to subscribe to.
+			def subscribe(channels)
+				slots = @cluster_client.slots_for(channels)
+				
+				slots.each do |slot, channels_for_slot|
+					if subscription = @subscriptions[slot]
+						# Add to existing subscription for this shard
+						subscription.ssubscribe(channels_for_slot)
+					else
+						# Create new subscription for this shard
+						client = @cluster_client.client_for(slot)
+						subscription = @subscriptions[slot] = client.ssubscribe(*channels_for_slot)
+						
+						@barrier.async do
+							# This is optimistic, in other words, subscription.listen will also fail on close.
+							until subscription.closed?
+								@queue << subscription.listen
+							end
+						ensure
+							# If we are exiting here for any reason OTHER than the subscription was closed, we need to re-create the subscription state:
+							unless subscription.closed?
+								@queue.close
+							end
+						end
+					end
+				end
+				
+				@channels.concat(channels)
+			end
+			
+			# Unsubscribe from sharded channels.
+			# @parameter channels [Array(String)] The channels to unsubscribe from.
+			def unsubscribe(channels)
+				slots = @cluster_client.slots_for(channels)
+				
+				slots.each do |slot, channels_for_slot|
+					if subscription = @subscriptions[slot]
+						subscription.sunsubscribe(channels_for_slot)
+						
+						# Remove channels from our tracking
+						@channels -= channels_for_slot
+						
+						# Check if this shard still has channels
+						remaining_channels_for_slot = @channels.select {|ch| @cluster_client.slot_for(ch) == slot}
+						
+						# If no channels left for this shard, close and remove it
+						if remaining_channels_for_slot.empty?
+							@subscriptions.delete(slot)
+							subscription.close
+						end
+					end
+				end
+			end
+			
+			# Get the list of currently subscribed channels.
+			# @returns [Array(String)] The list of subscribed channels.
+			def channels
+				@channels.dup
+			end
+			
+			# Get the number of active shard subscriptions.
+			# @returns [Integer] The number of shard connections.
+			def shard_count
+				@subscriptions.size
+			end
+		end
+	end
+end

data/lib/async/redis/context/generic.rb

@@ -8,30 +8,50 @@ require "protocol/redis/methods"
 
 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)
+					if connection = @connection
 						@connection = nil
+						@pool.release(connection)
 					end
 				end
 				
+				# @returns [Boolean] Whether the context is closed.
+				def closed?
+					@connection.nil?
+				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)
 					

data/lib/async/redis/context/pipeline.rb

@@ -2,7 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2019, by David Ortiz.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2022, by Tim Willard.
 
 require_relative "generic"
@@ -14,9 +14,12 @@ module Async
 			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 @@ module Async
 					end
 				end
 				
+				# Initialize a new pipeline context.
+				# @parameter pool [Pool] The connection pool to use.
 				def initialize(pool)
 					super(pool)
 					
@@ -46,6 +51,9 @@ module Async
 					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 @@ module Async
 					@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 @@ module Async
 					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 @@ module Async
 					end
 				end
 				
+				# Close the pipeline and flush all pending responses.
 				def close
 					flush
 				ensure

data/lib/async/redis/context/subscription.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2018, by Huba Nagy.
+# Copyright, 2018-2025, by Samuel Williams.
+
+require_relative "generic"
+
+module Async
+	module Redis
+		module Context
+			# Context for Redis pub/sub subscription operations.
+			class Subscription < Generic
+				MESSAGE = "message"
+				PMESSAGE = "pmessage"
+				SMESSAGE = "smessage"
+				
+				# 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) if channels.any?
+				end
+				
+				# Close the subscription context.
+				def close
+					# This causes anyone calling `#listen` to exit, as `read_response` will fail. If we decided to use `RESET` instead, we'd need to take that into account.
+					@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
+						type = response.first
+						
+						if type == MESSAGE || type == PMESSAGE || type == SMESSAGE
+							return response
+						end
+					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?
+					
+					while response = self.listen
+						yield response
+					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
+				end
+				
+				# Subscribe to channel patterns.
+				# @parameter patterns [Array(String)] The channel patterns to subscribe to.
+				def psubscribe(patterns)
+					@connection.write_request ["PSUBSCRIBE", *patterns]
+					@connection.flush
+				end
+				
+				# Unsubscribe from channel patterns.
+				# @parameter patterns [Array(String)] The channel patterns to unsubscribe from.
+				def punsubscribe(patterns)
+					@connection.write_request ["PUNSUBSCRIBE", *patterns]
+					@connection.flush
+				end
+				
+				# Subscribe to sharded channels (Redis 7.0+).
+				# @parameter channels [Array(String)] The sharded channels to subscribe to.
+				def ssubscribe(channels)
+					@connection.write_request ["SSUBSCRIBE", *channels]
+					@connection.flush
+				end
+				
+				# Unsubscribe from sharded channels (Redis 7.0+).
+				# @parameter channels [Array(String)] The sharded channels to unsubscribe from.
+				def sunsubscribe(channels)
+					@connection.write_request ["SUNSUBSCRIBE", *channels]
+					@connection.flush
+				end
+			end
+		end
+	end
+end

data/lib/async/redis/context/transaction.rb

@@ -9,15 +9,22 @@ require_relative "pipeline"
 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 @@ module Async
 					sync.call("EXEC")
 				end
 				
+				# Discard all queued commands in the transaction.
 				def discard
 					sync.call("DISCARD")
 				end

data/lib/async/redis/endpoint.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require "io/endpoint"
 require "io/endpoint/host_endpoint"
@@ -13,20 +13,32 @@ require_relative "protocol/selected"
 
 module Async
 	module Redis
+		# Create a local Redis endpoint.
+		# @parameter options [Hash] Options for the endpoint.
+		# @returns [Endpoint] A local Redis endpoint.
 		def self.local_endpoint(**options)
 			Endpoint.local(**options)
 		end
 		
 		# Represents a way to connect to a remote Redis server.
 		class Endpoint < ::IO::Endpoint::Generic
-			LOCALHOST = URI.parse("redis://localhost").freeze
+			LOCALHOST = URI::Generic.build(scheme: "redis", host: "localhost").freeze
 			
+			# Create a local Redis endpoint.
+			# @parameter options [Hash] Additional options for the endpoint.
+			# @returns [Endpoint] A local Redis endpoint.
 			def self.local(**options)
 				self.new(LOCALHOST, **options)
 			end
 			
+			# Create a remote Redis endpoint.
+			# @parameter host [String] The hostname to connect to.
+			# @parameter port [Integer] The port to connect to.
+			# @parameter options [Hash] Additional options for the endpoint.
+			# @returns [Endpoint] A remote Redis endpoint.
 			def self.remote(host, port = 6379, **options)
-				self.new(URI.parse("redis://#{host}:#{port}"), **options)
+				# URI::Generic.build automatically handles IPv6 addresses correctly:
+				self.new(URI::Generic.build(scheme: "redis", host: host, port: port), **options)
 			end
 			
 			SCHEMES = {
@@ -34,18 +46,31 @@ module Async
 				"rediss" => URI::Generic,
 			}
 			
+			# Parse a Redis URL string into an endpoint.
+			# @parameter string [String] The URL string to parse.
+			# @parameter endpoint [Endpoint] Optional underlying endpoint.
+			# @parameter options [Hash] Additional options for the endpoint.
+			# @returns [Endpoint] The parsed endpoint.
 			def self.parse(string, endpoint = nil, **options)
-				url = URI.parse(string).normalize
+				url = URI.parse(string)
 				
 				return self.new(url, endpoint, **options)
 			end
 			
 			# Construct an endpoint with a specified scheme, hostname, optional path, and options.
+			# If no scheme is provided, it will be auto-detected based on SSL context.
 			#
-			# @parameter scheme [String] The scheme to use, e.g. "redis" or "rediss".
+			# @parameter scheme [String, nil] The scheme to use, e.g. "redis" or "rediss". If nil, will auto-detect.
 			# @parameter hostname [String] The hostname to connect to (or bind to).
 			# @parameter options [Hash] Additional options, passed to {#initialize}.
-			def self.for(scheme, hostname, credentials: nil, port: nil, database: nil, **options)
+			def self.for(scheme, host, credentials: nil, port: nil, database: nil, **options)
+				# Auto-detect scheme if not provided:
+				if default_scheme = options.delete(:scheme)
+					scheme ||= default_scheme
+				end
+				
+				scheme ||= options.key?(:ssl_context) ? "rediss" : "redis"
+				
 				uri_klass = SCHEMES.fetch(scheme.downcase) do
 					raise ArgumentError, "Unsupported scheme: #{scheme.inspect}"
 				end
@@ -55,7 +80,13 @@ module Async
 				end
 				
 				self.new(
-					uri_klass.new(scheme, credentials&.join(":"), hostname, port, nil, path, nil, nil, nil).normalize,
+					uri_klass.build(
+						scheme: scheme,
+						userinfo: credentials&.join(":"),
+						host: host,
+						port: port,
+						path: path,
+					),
 					**options
 				)
 			end
@@ -92,6 +123,8 @@ module Async
 				end
 			end
 			
+			# Convert the endpoint to a URL.
+			# @returns [URI] The URL representation of the endpoint.
 			def to_url
 				url = @url.dup
 				
@@ -102,24 +135,34 @@ module Async
 				return url
 			end
 			
+			# Convert the endpoint to a string representation.
+			# @returns [String] A string representation of the endpoint.
 			def to_s
 				"\#<#{self.class} #{self.to_url} #{@options}>"
 			end
 			
+			# Convert the endpoint to an inspectable string.
+			# @returns [String] An inspectable string representation of the endpoint.
 			def inspect
 				"\#<#{self.class} #{self.to_url} #{@options.inspect}>"
 			end
 			
 			attr :url
 			
+			# Get the address of the underlying endpoint.
+			# @returns [String] The address of the endpoint.
 			def address
 				endpoint.address
 			end
 			
+			# Check if the connection is secure (using TLS).
+			# @returns [Boolean] True if the connection uses TLS.
 			def secure?
 				["rediss"].include?(self.scheme)
 			end
 			
+			# Get the protocol for this endpoint.
+			# @returns [Protocol] The protocol instance configured for this endpoint.
 			def protocol
 				protocol = @options.fetch(:protocol, Protocol::RESP2)
 				
@@ -134,14 +177,20 @@ module Async
 				return protocol
 			end
 			
+			# Get the default port for Redis connections.
+			# @returns [Integer] The default Redis port (6379).
 			def default_port
 				6379
 			end
 			
+			# Check if the endpoint is using the default port.
+			# @returns [Boolean] True if using the default port.
 			def default_port?
 				port == default_port
 			end
 			
+			# Get the port for this endpoint.
+			# @returns [Integer] The port number.
 			def port
 				@options[:port] || @url.port || default_port
 			end
@@ -151,10 +200,14 @@ module Async
 				@options[:hostname] || @url.hostname
 			end
 			
+			# Get the scheme for this endpoint.
+			# @returns [String] The URL scheme (e.g., "redis" or "rediss").
 			def scheme
 				@options[:scheme] || @url.scheme
 			end
 			
+			# Get the database number for this endpoint.
+			# @returns [Integer | Nil] The database number or nil if not specified.
 			def database
 				@options[:database] || extract_database(@url.path)
 			end
@@ -165,6 +218,8 @@ module Async
 				end
 			end
 			
+			# Get the credentials for authentication.
+			# @returns [Array(String) | Nil] The username and password credentials or nil if not specified.
 			def credentials
 				@options[:credentials] || extract_userinfo(@url.userinfo)
 			end
@@ -179,6 +234,8 @@ module Async
 				end
 			end
 			
+			# Check if the endpoint is connecting to localhost.
+			# @returns [Boolean] True if connecting to localhost.
 			def localhost?
 				@url.hostname =~ /^(.*?\.)?localhost\.?$/
 			end
@@ -192,6 +249,8 @@ module Async
 				end
 			end
 			
+			# Get the SSL context for secure connections.
+			# @returns [OpenSSL::SSL::SSLContext] The SSL context configured for this endpoint.
 			def ssl_context
 				@options[:ssl_context] || OpenSSL::SSL::SSLContext.new.tap do |context|
 					context.set_params(
@@ -200,6 +259,9 @@ module Async
 				end
 			end
 			
+			# Build the underlying endpoint with optional SSL wrapping.
+			# @parameter endpoint [IO::Endpoint] Optional base endpoint to wrap.
+			# @returns [IO::Endpoint] The built endpoint, potentially wrapped with SSL.
 			def build_endpoint(endpoint = nil)
 				endpoint ||= tcp_endpoint
 				
@@ -215,22 +277,33 @@ module Async
 				return endpoint
 			end
 			
+			# Get the underlying endpoint, building it if necessary.
+			# @returns [IO::Endpoint] The underlying endpoint for connections.
 			def endpoint
 				@endpoint ||= build_endpoint
 			end
 			
+			# Set the underlying endpoint.
+			# @parameter endpoint [IO::Endpoint] The endpoint to wrap and use.
 			def endpoint=(endpoint)
 				@endpoint = build_endpoint(endpoint)
 			end
 			
+			# Bind to the endpoint and yield the server socket.
+			# @parameter arguments [Array] Arguments to pass to the underlying endpoint bind method.
+			# @yields [IO] The bound server socket.
 			def bind(*arguments, &block)
 				endpoint.bind(*arguments, &block)
 			end
 			
+			# Connect to the endpoint and yield the client socket.
+			# @yields [IO] The connected client socket.
 			def connect(&block)
 				endpoint.connect(&block)
 			end
 			
+			# Iterate over each possible endpoint variation.
+			# @yields [Endpoint] Each endpoint variant.
 			def each
 				return to_enum unless block_given?
 				
@@ -239,14 +312,21 @@ module Async
 				end
 			end
 			
+			# Get the key for hashing and equality comparison.
+			# @returns [Array] The key components for this endpoint.
 			def key
 				[@url, @options]
 			end
 			
+			# Check if this endpoint is equal to another.
+			# @parameter other [Endpoint] The other endpoint to compare with.
+			# @returns [Boolean] True if the endpoints are equal.
 			def eql? other
 				self.key.eql? other.key
 			end
 			
+			# Get the hash code for this endpoint.
+			# @returns [Integer] The hash code based on the endpoint's key.
 			def hash
 				self.key.hash
 			end

data/lib/async/redis/key.rb

@@ -1,39 +1,57 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 module Async
 	module Redis
+		# Represents a Redis key with utility methods for key manipulation.
 		class Key
+			# Create a new Key instance.
+			# @parameter path [String] The key path.
+			# @returns [Key] A new Key instance.
 			def self.[] path
 				self.new(path)
 			end
 			
 			include Comparable
 			
+			# Initialize a new Key.
+			# @parameter path [String] The key path.
 			def initialize(path)
 				@path = path
 			end
 			
+			# Get the byte size of the key.
+			# @returns [Integer] The byte size of the key path.
 			def size
 				@path.bytesize
 			end
 			
 			attr :path
 			
+			# Convert the key to a string.
+			# @returns [String] The key path as a string.
 			def to_s
 				@path
 			end
 			
+			# Convert the key to a string (for String compatibility).
+			# @returns [String] The key path as a string.
 			def to_str
 				@path
 			end
 			
+			# Create a child key by appending a subkey.
+			# @parameter key [String] The subkey to append.
+			# @returns [Key] A new Key with the appended subkey.
 			def [] key
 				self.class.new("#{@path}:#{key}")
 			end
 			
+			# Compare this key with another key.
+			# @parameter other [Key] The other key to compare with.
+			# @returns [Integer] -1, 0, or 1 for comparison result.
 			def <=> other
 				@path <=> other.to_str
 			end