async-redis 0.11.2 → 0.13.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

@@ -22,12 +22,17 @@ module Async
 				
 				# 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.

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"
@@ -44,7 +44,7 @@ module Async
 				end
 				
 				# Flush responses.
-				# @param count [Integer] leave this many responses.
+				# @parameter count [Integer] leave this many responses.
 				def flush(count = 0)
 					while @count > count
 						read_response

data/lib/async/redis/context/{subscribe.rb → subscription.rb}

@@ -2,7 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2018, by Huba Nagy.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 require_relative "generic"
 
@@ -10,8 +10,10 @@ module Async
 	module Redis
 		module Context
 			# Context for Redis pub/sub subscription operations.
-			class Subscribe < Generic
+			class Subscription < Generic
 				MESSAGE = "message"
+				PMESSAGE = "pmessage"
+				SMESSAGE = "smessage"
 				
 				# Initialize a new subscription context.
 				# @parameter pool [Pool] The connection pool to use.
@@ -19,12 +21,12 @@ module Async
 				def initialize(pool, channels)
 					super(pool)
 					
-					subscribe(channels)
+					subscribe(channels) if channels.any?
 				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.
+					# 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
@@ -34,7 +36,11 @@ module Async
 				# @returns [Array] The next message response, or nil if connection closed.
 				def listen
 					while response = @connection.read_response
-						return response if response.first == MESSAGE
+						type = response.first
+						
+						if type == MESSAGE || type == PMESSAGE || type == SMESSAGE
+							return response
+						end
 					end
 				end
 				
@@ -62,6 +68,34 @@ module Async
 					@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

data/lib/async/redis/endpoint.rb

@@ -2,10 +2,12 @@
 
 # Released under the MIT License.
 # Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2025, by Joan Lledó.
 
 require "io/endpoint"
 require "io/endpoint/host_endpoint"
 require "io/endpoint/ssl_endpoint"
+require "io/endpoint/unix_endpoint"
 
 require_relative "protocol/resp2"
 require_relative "protocol/authenticated"
@@ -41,6 +43,15 @@ module Async
 				self.new(URI::Generic.build(scheme: "redis", host: host, port: port), **options)
 			end
 			
+			# Create a local Redis endpoint from a UNIX socket path.
+			# @parameter path [String] The path to the UNIX socket.
+			# @parameter options [Hash] Additional options for the endpoint.
+			# @returns [Endpoint] A local Redis endpoint.
+			def self.unix(path, **options)
+				endpoint = ::IO::Endpoint.unix(path)
+				self.new(URI::Generic.build(scheme: "redis", path:), endpoint, **options)
+			end
+			
 			SCHEMES = {
 				"redis" => URI::Generic,
 				"rediss" => URI::Generic,
@@ -58,11 +69,19 @@ module Async
 			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, host, credentials: nil, port: nil, database: nil, **options)
+			def self.for(scheme, host, 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
@@ -74,7 +93,6 @@ module Async
 				self.new(
 					uri_klass.build(
 						scheme: scheme,
-						userinfo: credentials&.join(":"),
 						host: host,
 						port: port,
 						path: path,
@@ -210,6 +228,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
@@ -224,6 +244,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
@@ -237,6 +259,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(
@@ -245,8 +269,11 @@ 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
+				endpoint ||= make_endpoint
 				
 				if secure?
 					# Wrap it in SSL:
@@ -260,22 +287,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?
 				
@@ -284,14 +322,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
@@ -310,9 +355,21 @@ module Async
 				return options
 			end
 			
+			def unix_endpoint
+				::IO::Endpoint.unix(@url.path)
+			end
+			
 			def tcp_endpoint
 				::IO::Endpoint.tcp(self.hostname, port, **tcp_options)
 			end
+			
+			def make_endpoint
+				if @url.host
+					tcp_endpoint
+				else
+					unix_endpoint
+				end
+			end
 		end
 	end
 end

data/lib/async/redis/key.rb

@@ -1,7 +1,7 @@
 # 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

data/lib/async/redis/protocol/resp2.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 require "protocol/redis"
 

data/lib/async/redis/range_map.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Redis
+		# 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)
+				end
+				if block_given?
+					return yield
+				end
+				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
+			
+			# Get a random value from the map.
+			# @returns [Object] A randomly selected value, or nil if map is empty.
+			def sample
+				return nil if @ranges.empty?
+				range, value = @ranges.sample
+				return value
+			end
+			
+			# Clear all ranges from the map.
+			def clear
+				@ranges.clear
+			end
+		end
+	end
+end

data/lib/async/redis/sentinel_client.rb

@@ -2,7 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2020, by David Ortiz.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 # Copyright, 2024, by Joan Lledó.
 
 require_relative "client"
@@ -21,13 +21,15 @@ module Async
 			#
 			# @property endpoints [Array(Endpoint)] The list of sentinel endpoints.
 			# @property master_name [String] The name of the master instance, defaults to 'mymaster'.
+			# @property master_options [Hash] Connection options for master instances.
+			# @property slave_options [Hash] Connection options for slave instances (defaults to master_options if not specified).
 			# @property role [Symbol] The role of the instance that you want to connect to, either `:master` or `:slave`.
-			# @property protocol [Protocol] The protocol to use when connecting to the actual Redis server, defaults to {Protocol::RESP2}.
-			def initialize(endpoints, master_name: DEFAULT_MASTER_NAME, role: :master, protocol: Protocol::RESP2, **options)
+			def initialize(endpoints, master_name: DEFAULT_MASTER_NAME, master_options: nil, slave_options: nil, role: :master, **options)
 				@endpoints = endpoints
 				@master_name = master_name
+				@master_options = master_options || {}
+				@slave_options = slave_options || @master_options
 				@role = role
-				@protocol = protocol
 				
 				# A cache of sentinel connections.
 				@sentinels = {}
@@ -94,9 +96,11 @@ module Async
 				end
 			end
 			
+			private
+			
 			# Resolve the master endpoint address.
 			# @returns [Endpoint | Nil] The master endpoint or nil if not found.
-			def resolve_master
+			def resolve_master(options = @master_options)
 				sentinels do |client|
 					begin
 						address = client.call("SENTINEL", "GET-MASTER-ADDR-BY-NAME", @master_name)
@@ -104,7 +108,7 @@ module Async
 						next
 					end
 					
-					return Endpoint.remote(address[0], address[1]) if address
+					return Endpoint.for(nil, address[0], port: address[1], **options) if address
 				end
 				
 				return nil
@@ -112,7 +116,7 @@ module Async
 			
 			# Resolve a slave endpoint address.
 			# @returns [Endpoint | Nil] A slave endpoint or nil if not found.
-			def resolve_slave
+			def resolve_slave(options = @slave_options)
 				sentinels do |client|
 					begin
 						reply = client.call("SENTINEL", "SLAVES", @master_name)
@@ -124,16 +128,14 @@ module Async
 					next if slaves.empty?
 					
 					slave = select_slave(slaves)
-					return Endpoint.remote(slave["ip"], slave["port"])
+					return Endpoint.for(nil, slave["ip"], port: slave["port"], **options)
 				end
 				
 				return nil
 			end
 			
-			protected
-			
 			def assign_default_tags(tags)
-				tags[:protocol] = @protocol.to_s
+				tags[:role] ||= @role
 			end
 			
 			# Override the parent method. The only difference is that this one needs to resolve the master/slave address.
@@ -145,7 +147,7 @@ module Async
 					peer = endpoint.connect
 					stream = ::IO::Stream(peer)
 					
-					@protocol.client(stream)
+					endpoint.protocol.client(stream)
 				end
 			end
 			

data/lib/async/redis/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Redis
-		VERSION = "0.11.2"
+		VERSION = "0.13.0"
 	end
 end

data/lib/async/redis.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 # Copyright, 2020, by David Ortiz.
 
 require_relative "redis/version"

data/license.md

@@ -12,7 +12,7 @@ Copyright, 2021, by Olle Jonsson.
 Copyright, 2021, by Troex Nevelin.  
 Copyright, 2022, by Tim Willard.  
 Copyright, 2022, by Gleb Sinyavskiy.  
-Copyright, 2024, by Joan Lledó.  
+Copyright, 2024-2025, by Joan Lledó.  
 Copyright, 2025, by Travis Bell.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

data/readme.md

@@ -14,10 +14,34 @@ Please see the [project documentation](https://socketry.github.io/async-redis/)
 
   - [Getting Started](https://socketry.github.io/async-redis/guides/getting-started/index) - This guide explains how to use the `async-redis` gem to connect to a Redis server and perform basic operations.
 
+  - [Transactions and Pipelines](https://socketry.github.io/async-redis/guides/transactions-and-pipelines/index) - This guide explains how to use Redis transactions and pipelines with `async-redis` for atomic operations and improved performance.
+
+  - [Subscriptions](https://socketry.github.io/async-redis/guides/subscriptions/index) - This guide explains how to use Redis pub/sub functionality with `async-redis` to publish and subscribe to messages.
+
+  - [Data Structures and Operations](https://socketry.github.io/async-redis/guides/data-structures/index) - This guide explains how to work with Redis data types and operations using `async-redis`.
+
+  - [Streams](https://socketry.github.io/async-redis/guides/streams/index) - This guide explains how to use Redis streams with `async-redis` for reliable message processing and event sourcing.
+
+  - [Scripting](https://socketry.github.io/async-redis/guides/scripting/index) - This guide explains how to use Redis Lua scripting with `async-redis` for atomic operations and advanced data processing.
+
+  - [Client Architecture](https://socketry.github.io/async-redis/guides/client-architecture/index) - This guide explains the different client types available in `async-redis` and when to use each one.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-redis/releases/index) for all releases.
 
+### v0.13.0
+
+  - Fix password with special characters when using sentinels.
+  - Fix support for UNIX domain socket endpoints. You can now create Unix socket endpoints using `Async::Redis::Endpoint.unix("/path/to/socket.sock")` or parse them from URLs like `redis:/path/to/socket.sock`.
+
+### v0.12.0
+
+  - Add agent context.
+  - Add support for pattern pub/sub.
+  - Add support for sharded pub/sub.
+  - Add support for `master_options` and `slave_options` (and removed `protocol`) from `SentinelClient`.
+
 ### v0.11.2
 
   - Fix handling of IPv6 address literals, including those returned by Redis Cluster / Sentinel.

data/releases.md

@@ -1,5 +1,17 @@
 # Releases
 
+## v0.13.0
+
+  - Fix password with special characters when using sentinels.
+  - Fix support for UNIX domain socket endpoints. You can now create Unix socket endpoints using `Async::Redis::Endpoint.unix("/path/to/socket.sock")` or parse them from URLs like `redis:/path/to/socket.sock`.
+
+## v0.12.0
+
+  - Add agent context.
+  - Add support for pattern pub/sub.
+  - Add support for sharded pub/sub.
+  - Add support for `master_options` and `slave_options` (and removed `protocol`) from `SentinelClient`.
+
 ## v0.11.2
 
   - Fix handling of IPv6 address literals, including those returned by Redis Cluster / Sentinel.