async-redis 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a6afd9e0917905a3ac88663aab6185431af4f90230a160439131b137611a072
-  data.tar.gz: 503e41aea7adc5f2f103d442db5be4c37f9299c9fb9bbba33b040f8200237511
+  metadata.gz: 631249ff627c06ac8931e39bbebd3a357695b390452bc67e7fc69e98a8abbcf0
+  data.tar.gz: 9f85726c02e706838bbf90d78d36233a4749901593e8c766ab008f797d18f381
 SHA512:
-  metadata.gz: 459502e1c7c5cfbb6250a4460f1dfa4b5e0cd2386e056f77696883521274d3ad0b6c25cd5a1e6ee3db393d18703782c643c1fe6b39e4cf22292cd26417b6af9b
-  data.tar.gz: 3119cf4d3b60ed724b68ed9fa2fc9dee2729a27657ebf1460453d236426d8e1c19f3f1717c5d0266fb85a9c7f821ca1e74f3e1e2321750b71805ecbefe084387
+  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"
@@ -23,12 +23,20 @@ module Async
 		# 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::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 subscribe(*channels)
-					context = Context::Subscribe.new(@pool, channels)
+					context = Context::Subscription.new(@pool, channels)
 					
 					return context unless block_given?
 					
@@ -39,6 +47,49 @@ module Async
 					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?
+					
+					begin
+						yield context
+					ensure
+						context.close
+					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 +104,11 @@ module Async
 				
 				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 +124,9 @@ module Async
 				# 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,6 +137,7 @@ module Async
 					end
 				end
 				
+				# Close the client and all its connections.
 				def close
 					@pool.close
 				end
@@ -85,6 +145,10 @@ module Async
 			
 			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
@@ -92,11 +156,18 @@ module Async
 				@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)
 				

data/lib/async/redis/cluster_client.rb

@@ -5,53 +5,28 @@
 # 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
 			
+			# Raised when no nodes are found for a specific slot.
 			class SlotError < StandardError
 			end
 			
 			Node = Struct.new(:id, :endpoint, :role, :health, :client)
 			
-			class RangeMap
-				def initialize
-					@ranges = []
-				end
-				
-				def add(range, value)
-					@ranges << [range, value]
-					
-					return value
-				end
-				
-				def find(key)
-					@ranges.each do |range, value|
-						return value if range.include?(key)
-					end
-					
-					if block_given?
-						return yield
-					end
-					
-					return nil
-				end
-				
-				def each
-					@ranges.each do |range, value|
-						yield value
-					end
-				end
-				
-				def clear
-					@ranges.clear
-				end
-			end
-			
 			# Create a new instance of the cluster client.
 			#
 			# @property endpoints [Array(Endpoint)] The list of cluster endpoints.
@@ -61,6 +36,13 @@ module Async
 				@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 +65,10 @@ module Async
 				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!
@@ -99,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|
@@ -116,7 +124,7 @@ module Async
 						
 						nodes = shard["nodes"].map do |node|
 							node = node.each_slice(2).to_h
-							endpoint = Endpoint.remote(node["ip"], node["port"])
+							endpoint = Endpoint.for(endpoint.scheme, node["endpoint"], port: node["port"])
 							
 							# Collect all endpoints:
 							endpoints << endpoint
@@ -203,6 +211,9 @@ module Async
 				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] = []}
 				
@@ -212,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