async-redis 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4307fa3fa26652c590ff6c371541d216944b0e724fb67f8ffa3799e1f120c37c
-  data.tar.gz: 3d1320e98619fcaf9b5e3f80ec7cef3533a25f62ec19047478c87aacb3c15bec
+  metadata.gz: 631249ff627c06ac8931e39bbebd3a357695b390452bc67e7fc69e98a8abbcf0
+  data.tar.gz: 9f85726c02e706838bbf90d78d36233a4749901593e8c766ab008f797d18f381
 SHA512:
-  metadata.gz: a79be2158187c9dbb6b59eec5a709f899d5e41d94be7e83977b500680888a739d50e4cb06bf53e7676540a49cdd1be50a3458f9002f0951866ea61f91ceb6299
-  data.tar.gz: 81829d10c42316190844935547406678a1593c291bbc51fe69da274d495dc5eec9b590e6ade56af997ac453a520dbffc5d916cee4c962408979261e1010d300b
+  metadata.gz: 4471fecf34ff2cc9a3ead17ac8a92978aafe7e4ef8abcc5b25a36c7a48223ac9f9734ce8972a337ee2a83fd684e790a8a2bbaf263fd09d8ac646f39520f79443
+  data.tar.gz: 3d7388f8ab00d99aa5fd97d06ddec1f07c9027c7512fb8c194a08afa1becabf7c93407e73e85be25fc75c6af54129984fee5e638b550e22846e30c0c2b56f5fc

data/context/getting-started.md

@@ -0,0 +1,94 @@
+# Getting Started
+
+This guide explains how to use the `async-redis` gem to connect to a Redis server and perform basic operations.
+
+## Installation
+
+Add the gem to your project:
+
+``` shell
+$ bundle add async-redis
+```
+
+## Usage
+
+### Basic Local Connection
+
+``` ruby
+require 'async/redis'
+
+Async do
+	endpoint = Async::Redis.local_endpoint(
+		# Optional database index:
+		database: 1,
+		# Optional credentials:
+		credentials: ["username", "password"]
+	)
+	
+	client = Async::Redis::Client.new(endpoint)
+	puts client.info
+	
+	client.set("mykey", "myvalue")
+	puts client.get("mykey")
+end
+```
+
+You can also encode this information in a URL:
+
+
+
+### Connecting to Redis SSL Endpoint
+
+This example demonstrates parsing an environment variable with a `redis://` or SSL `rediss://` scheme, and demonstrates how you can specify SSL parameters on the SSLContext object.
+
+``` ruby
+require 'async/redis'
+
+ssl_context = OpenSSL::SSL::SSLContext.new.tap do |context|
+	# Load the certificate store:
+	context.cert_store = OpenSSL::X509::Store.new.tap do |store|
+		store.add_file(Rails.root.join("config/redis.pem").to_s)
+	end
+	
+	# Load the certificate:
+	context.cert = OpenSSL::X509::Certificate.new(File.read(
+		Rails.root.join("config/redis.crt")
+	))
+	
+	# Load the private key:
+	context.key = OpenSSL::PKey::RSA.new(
+		Rails.application.credentials.services.redis.private_key
+	)
+	
+	# Ensure the connection is verified according to the above certificates:
+	context.verify_mode = OpenSSL::SSL::VERIFY_PEER
+end
+
+# e.g. REDIS_URL=rediss://:PASSWORD@redis.example.com:12345
+endpoint = Async::Redis::Endpoint.parse(ENV["REDIS_URL"], ssl_context: ssl_context)
+client = Async::Redis::Client.new(endpoint)
+Sync do
+	puts client.call("PING")
+end
+```
+
+### Variables
+
+``` ruby
+require 'async'
+require 'async/redis'
+
+endpoint = Async::Redis.local_endpoint
+client = Async::Redis::Client.new(endpoint)
+
+Async do
+	client.set('X', 10)
+	puts client.get('X')
+ensure
+	client.close
+end
+```
+
+## Next Steps
+
+- [Subscriptions](../subscriptions/) - Learn how to use Redis pub/sub functionality for real-time messaging.

data/context/index.yaml

@@ -0,0 +1,16 @@
+# 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 Redis client library.
+metadata:
+  documentation_uri: https://socketry.github.io/async-redis/
+  source_code_uri: https://github.com/socketry/async-redis.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use the `async-redis` gem to connect to
+    a Redis server and perform basic operations.
+- path: subscriptions.md
+  title: Subscriptions
+  description: This guide explains how to use Redis pub/sub functionality with `async-redis`
+    to publish and subscribe to messages.

data/context/subscriptions.md

@@ -0,0 +1,161 @@
+# Subscriptions
+
+This guide explains how to use Redis pub/sub functionality with `async-redis` to publish and subscribe to messages.
+
+## Overview
+
+Redis actually has 3 mechanisms to support pub/sub - a general `SUBSCRIBE` command, a pattern-based `PSUBSCRIBE` command, and a sharded `SSUBSCRIBE` command for cluster environments. They mostly work the same way, but have different use cases.
+
+## Subscribe
+
+The `SUBSCRIBE` command is used to subscribe to one or more channels. When a message is published to a subscribed channel, the client receives the message in real-time.
+
+First, let's create a simple listener that subscribes to messages on a channel:
+
+``` ruby
+require 'async'
+require 'async/redis'
+
+client = Async::Redis::Client.new
+
+Async do
+	client.subscribe 'status.frontend' do |context|
+		puts "Listening for messages on 'status.frontend'..."
+		
+		type, name, message = context.listen
+		
+		puts "Received: #{message}"
+	end
+end
+```
+
+Now, let's create a publisher that sends messages to the same channel:
+
+``` ruby
+require 'async'
+require 'async/redis'
+
+client = Async::Redis::Client.new
+
+Async do
+	puts "Publishing message..."
+	client.publish 'status.frontend', 'good'
+	puts "Message sent!"
+end
+```
+
+To see pub/sub in action, you can run the listener in one terminal and the publisher in another. The listener will receive any messages sent by the publisher to the `status.frontend` channel:
+
+```bash
+$ ruby listener.rb
+Listening for messages on 'status.frontend'...
+Received: good
+```
+
+### Error Handling
+
+Subscriptions are at-most-once delivery. In addition, subscriptions are stateful, meaning that they maintain their own internal state and can be affected by network issues or server restarts. In order to improve resilience, it's important to implement error handling and reconnection logic.
+
+```ruby
+require 'async'
+require 'async/redis'
+
+client = Async::Redis::Client.new
+
+Async do
+	client.subscribe 'status.frontend' do |context|
+		puts "Listening for messages on 'status.frontend'..."
+		
+		context.each do |type, name, message|
+			puts "Received: #{message}"
+		end
+	end
+rescue => error
+	Console.warn(self, "Subscription failed", error)
+	sleep 1
+	retry
+end
+```
+
+## Pattern Subscribe
+
+The `PSUBSCRIBE` command is used to subscribe to channels that match a given pattern. This allows clients to receive messages from multiple channels without subscribing to each one individually.
+
+Let's replace the receiver in the above example:
+
+``` ruby
+require 'async'
+require 'async/redis'
+
+endpoint = Async::Redis.local_endpoint
+client = Async::Redis::Client.new(endpoint)
+
+Async do
+	client.psubscribe 'status.*' do |context|
+		puts "Listening for messages on 'status.*'..."
+		
+		type, pattern, name, message = context.listen
+		
+		puts "Received: #{message}"
+	end
+end
+```
+
+Note that an extra field, `pattern` is returned when using `PSUBSCRIBE`. This field indicates the pattern that was matched for the incoming message. This can be useful for logging or debugging purposes, as it allows you to see which pattern triggered the message delivery.
+
+## Shard Subscribe
+
+If you are working with a clustered environment, you can improve performance by limiting the scope of your subscriptions to specific shards. This can help reduce the amount of data that needs to be sent between shards and improve overall throughput.
+
+To use sharded subscriptions, use a cluster client which supports sharded pub/sub:
+
+``` ruby
+require 'async'
+require 'async/redis'
+
+# endpoints = ...
+cluster_client = Async::Redis::ClusterClient.new(endpoints)
+
+Async do
+	cluster_client.subscribe 'status.frontend' do |context|
+		puts "Listening for messages on 'status.frontend'..."
+		
+		type, name, message = context.listen
+		
+		puts "Received: #{message}"
+	end
+end
+```
+
+``` ruby
+require 'async'
+require 'async/redis'
+
+# endpoints = ...
+cluster_client = Async::Redis::ClusterClient.new(endpoints)
+
+Async do
+	puts "Publishing message..."
+	cluster_client.publish('status.frontend', 'good')
+	puts "Message sent!"
+end
+```
+
+### Clustered Subscriptions
+
+While general `PUBLISH` and `SUBSCRIBE` will work on a cluster, they are less efficient as they require inter-shard communication. By default, the {ruby Async::Redis::ClusterClient} subscription mechanism defaults to `SSUBSCRIBE` and `SPUBLISH`, which are optimized for sharded environments. However, if using multiple subscriptions, internally, several connections will be made to the relevant shards, which increases the complexity.
+
+#### Cluster Topology Changes and Subscription Invalidation
+
+If the cluster is re-configured (e.g. adding or removing nodes, resharding), the subscription state may need to be re-established to account for the new topology. During this process, messages may be lost. This is expected as subscriptions are stateless.
+
+**Important**: When any individual shard subscription fails (due to resharding, node failures, or network issues), the entire cluster subscription is invalidated and will stop delivering messages. This design ensures consistency and prevents partial subscription states that could lead to missed messages on some shards.
+
+Common scenarios that trigger subscription invalidation:
+
+- **Resharding operations**: When slots are migrated between nodes (`MOVED` errors)
+- **Node failures**: When Redis nodes become unavailable
+- **Network partitions**: When connections to specific shards are lost
+- **Cluster reconfiguration**: When the cluster topology changes
+
+Applications should be prepared to handle subscription failures and implement appropriate retry strategies.

data/lib/async/redis/client.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, 2018, by Huba Nagy.
 # Copyright, 2019, by Mikael Henriksson.
 # Copyright, 2019, by David Ortiz.
@@ -9,7 +9,7 @@
 
 require_relative "context/pipeline"
 require_relative "context/transaction"
-require_relative "context/subscribe"
+require_relative "context/subscription"
 require_relative "endpoint"
 
 require "io/endpoint/host_endpoint"
@@ -32,11 +32,49 @@ module Async
 				# 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.
+				# 	@parameter context [Context::Subscription] The subscription context.
 				# @returns [Object] The result of the block if block given.
-				# @returns [Context::Subscribe] The subscription context if no block given.
+				# @returns [Context::Subscription] The subscription context if no block given.
 				def subscribe(*channels)
-					context = Context::Subscribe.new(@pool, channels)
+					context = Context::Subscription.new(@pool, channels)
+					
+					return context unless block_given?
+					
+					begin
+						yield context
+					ensure
+						context.close
+					end
+				end
+				
+				# Subscribe to one or more channel patterns for pub/sub messaging.
+				# @parameter patterns [Array(String)] The channel patterns to subscribe to.
+				# @yields {|context| ...} If a block is given, it will be executed within the subscription context.
+				# 	@parameter context [Context::Subscription] The subscription context.
+				# @returns [Object] The result of the block if block given.
+				# @returns [Context::Subscription] The subscription context if no block given.
+				def psubscribe(*patterns)
+					context = Context::Subscription.new(@pool, [])
+					context.psubscribe(patterns)
+					
+					return context unless block_given?
+					
+					begin
+						yield context
+					ensure
+						context.close
+					end
+				end
+				
+				# Subscribe to one or more sharded channels for pub/sub messaging (Redis 7.0+).
+				# @parameter channels [Array(String)] The sharded channels to subscribe to.
+				# @yields {|context| ...} If a block is given, it will be executed within the subscription context.
+				# 	@parameter context [Context::Subscription] The subscription context.
+				# @returns [Object] The result of the block if block given.
+				# @returns [Context::Subscription] The subscription context if no block given.
+				def ssubscribe(*channels)
+					context = Context::Subscription.new(@pool, [])
+					context.ssubscribe(channels)
 					
 					return context unless block_given?
 					

data/lib/async/redis/cluster_client.rb

@@ -5,12 +5,18 @@
 # Copyright, 2025, by Travis Bell.
 
 require_relative "client"
+require_relative "cluster_subscription"
+require_relative "range_map"
 require "io/stream"
 
+require "protocol/redis/cluster/methods"
+
 module Async
 	module Redis
 		# A Redis cluster client that manages multiple Redis instances and handles cluster operations.
 		class ClusterClient
+			include ::Protocol::Redis::Cluster::Methods
+			
 			# Raised when cluster configuration cannot be reloaded.
 			class ReloadError < StandardError
 			end
@@ -21,54 +27,6 @@ module Async
 			
 			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)
-					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
-				
-				# Clear all ranges from the map.
-				def clear
-					@ranges.clear
-				end
-			end
-			
 			# Create a new instance of the cluster client.
 			#
 			# @property endpoints [Array(Endpoint)] The list of cluster endpoints.
@@ -127,13 +85,35 @@ module Async
 				end
 			end
 			
+			# Get any available client from the cluster.
+			# This is useful for operations that don't require slot-specific routing, such as global pub/sub operations, INFO commands, or other cluster-wide operations.
+			# @parameter role [Symbol] The role of node to get (:master or :slave).
+			# @returns [Client] A Redis client for any available node.
+			def any_client(role = :master)
+				unless @shards
+					reload_cluster!
+				end
+				
+				# Sample a random shard to get better load distribution
+				if nodes = @shards.sample
+					nodes = nodes.select{|node| node.role == role}
+					
+					if node = nodes.sample
+						return (node.client ||= Client.new(node.endpoint, **@options))
+					end
+				end
+				
+				# Fallback to slot 0 if sampling fails
+				client_for(0, role)
+			end
+			
 			protected
 			
 			def reload_cluster!(endpoints = @endpoints)
 				@endpoints.each do |endpoint|
 					client = Client.new(endpoint, **@options)
 					
-					shards = RangeMap.new
+					shards = Async::Redis::RangeMap.new
 					endpoints = []
 					
 					client.call("CLUSTER", "SHARDS").each do |shard|
@@ -243,6 +223,32 @@ module Async
 				
 				return slots
 			end
+			
+			# Subscribe to one or more sharded channels for pub/sub messaging in cluster environment.
+			# The subscription will be created on the appropriate nodes responsible for each channel's hash slot.
+			#
+			# @parameter channels [Array(String)] The sharded channels to subscribe to.
+			# @yields {|context| ...} If a block is given, it will be executed within the subscription context.
+			# 	@parameter context [ClusterSubscription] The cluster subscription context.
+			# @returns [Object] The result of the block if block given.
+			# @returns [ClusterSubscription] The cluster subscription context if no block given.
+			def subscribe(*channels)
+				context = ClusterSubscription.new(self)
+				
+				if channels.any?
+					context.subscribe(channels)
+				end
+				
+				if block_given?
+					begin
+						yield context
+					ensure
+						context.close
+					end
+				else
+					return context
+				end
+			end
 		end
 	end
 end

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"

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

@@ -58,11 +58,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)
+				# 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
@@ -210,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
@@ -224,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
@@ -237,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(
@@ -245,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
 				
@@ -260,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?
 				
@@ -284,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,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,58 @@
+# frozen_string_literal: true
+
+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.12.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/readme.md

@@ -14,10 +14,19 @@ 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.
 
+  - [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.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-redis/releases/index) for all releases.
 
+### 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,12 @@
 # Releases
 
+## 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-redis
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -113,30 +113,35 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.11'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
+- context/subscriptions.md
 - lib/async/redis.rb
 - lib/async/redis/client.rb
 - lib/async/redis/cluster_client.rb
+- lib/async/redis/cluster_subscription.rb
 - lib/async/redis/context/generic.rb
 - lib/async/redis/context/pipeline.rb
-- lib/async/redis/context/subscribe.rb
+- lib/async/redis/context/subscription.rb
 - lib/async/redis/context/transaction.rb
 - lib/async/redis/endpoint.rb
 - lib/async/redis/key.rb
 - lib/async/redis/protocol/authenticated.rb
 - lib/async/redis/protocol/resp2.rb
 - lib/async/redis/protocol/selected.rb
+- lib/async/redis/range_map.rb
 - lib/async/redis/sentinel_client.rb
 - lib/async/redis/version.rb
 - license.md
@@ -162,7 +167,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Redis client library.
 test_files: []