async-redis 0.11.1 → 0.12.0

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

@@ -1,28 +1,40 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 require "protocol/redis"
 
 module Async
 	module Redis
+		# @namespace
 		module Protocol
+			# RESP2 protocol implementation for Redis.
 			module RESP2
+				# A connection implementation for RESP2 protocol.
 				class Connection < ::Protocol::Redis::Connection
+					# Get the concurrency level for this connection.
+					# @returns [Integer] The concurrency level (1 for RESP2).
 					def concurrency
 						1
 					end
 					
+					# Check if the connection is viable for use.
+					# @returns [Boolean] True if the stream is readable.
 					def viable?
 						@stream.readable?
 					end
 					
+					# Check if the connection can be reused.
+					# @returns [Boolean] True if the stream is not closed.
 					def reusable?
 						!@stream.closed?
 					end
 				end
 				
+				# Create a new RESP2 client connection.
+				# @parameter stream [IO] The stream to use for communication.
+				# @returns [Connection] A new RESP2 connection.
 				def self.client(stream)
 					Connection.new(stream)
 				end

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"
@@ -10,6 +10,7 @@ require "io/stream"
 
 module Async
 	module Redis
+		# A Redis Sentinel client for high availability Redis deployments.
 		class SentinelClient
 			DEFAULT_MASTER_NAME = "mymaster"
 			
@@ -20,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 = {}
@@ -40,6 +43,9 @@ module Async
 			# @attribute [Symbol] The role of the instance that you want to connect to.
 			attr :role
 			
+			# Resolve an address for the specified role.
+			# @parameter role [Symbol] The role to resolve (:master or :slave).
+			# @returns [Endpoint] The resolved endpoint address.
 			def resolve_address(role = @role)
 				case role
 				when :master
@@ -55,6 +61,7 @@ module Async
 				address or raise RuntimeError, "Unable to fetch #{role} via Sentinel."
 			end
 			
+			# Close the sentinel client and all connections.
 			def close
 				super
 				
@@ -63,25 +70,37 @@ module Async
 				end
 			end
 			
+			# Initiate a failover for the specified master.
+			# @parameter name [String] The name of the master to failover.
+			# @returns [Object] The result of the failover command.
 			def failover(name = @master_name)
 				sentinels do |client|
 					return client.call("SENTINEL", "FAILOVER", name)
 				end
 			end
 			
+			# Get information about all masters.
+			# @returns [Array(Hash)] Array of master information hashes.
 			def masters
 				sentinels do |client|
 					return client.call("SENTINEL", "MASTERS").map{|fields| fields.each_slice(2).to_h}
 				end
 			end
 			
+			# Get information about a specific master.
+			# @parameter name [String] The name of the master.
+			# @returns [Hash] The master information hash.
 			def master(name = @master_name)
 				sentinels do |client|
 					return client.call("SENTINEL", "MASTER", name).each_slice(2).to_h
 				end
 			end
 			
-			def resolve_master
+			private
+			
+			# Resolve the master endpoint address.
+			# @returns [Endpoint | Nil] The master endpoint or nil if not found.
+			def resolve_master(options = @master_options)
 				sentinels do |client|
 					begin
 						address = client.call("SENTINEL", "GET-MASTER-ADDR-BY-NAME", @master_name)
@@ -89,13 +108,15 @@ 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
 			end
 			
-			def resolve_slave
+			# Resolve a slave endpoint address.
+			# @returns [Endpoint | Nil] A slave endpoint or nil if not found.
+			def resolve_slave(options = @slave_options)
 				sentinels do |client|
 					begin
 						reply = client.call("SENTINEL", "SLAVES", @master_name)
@@ -107,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.
@@ -128,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

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 module Async
 	module Redis
-		VERSION = "0.11.1"
+		VERSION = "0.12.0"
 	end
 end

data/lib/async/redis.rb

@@ -1,11 +1,19 @@
 # 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"
 require_relative "redis/client"
+require_relative "redis/endpoint"
 
 require_relative "redis/cluster_client"
 require_relative "redis/sentinel_client"
+
+# @namespace
+module Async
+	# @namespace
+	module Redis
+	end
+end

data/readme.md

@@ -14,10 +14,23 @@ 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.
+
 ### v0.11.1
 
   - Correctly pass `@options` to `Async::Redis::Client` instances created by `Async::Redis::ClusterClient`.

data/releases.md

@@ -1,5 +1,16 @@
 # 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.
+
 ## v0.11.1
 
   - Correctly pass `@options` to `Async::Redis::Client` instances created by `Async::Redis::ClusterClient`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-redis
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -9,6 +9,7 @@ authors:
 - David Ortiz
 - Gleb Sinyavskiy
 - Mikael Henriksson
+- Travis Bell
 - Troex Nevelin
 - Alex Matchneer
 - Jeremy Jung
@@ -17,7 +18,6 @@ authors:
 - Pierre Montelle
 - Salim Semaoune
 - Tim Willard
-- Travis Bell
 bindir: bin
 cert_chain:
 - |
@@ -49,7 +49,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -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
@@ -155,14 +160,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Redis client library.
 test_files: []

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

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2018, by Huba Nagy.
-# Copyright, 2018-2024, by Samuel Williams.
-
-require_relative "generic"
-
-module Async
-	module Redis
-		module Context
-			class Subscribe < Generic
-				MESSAGE = "message"
-				
-				def initialize(pool, channels)
-					super(pool)
-					
-					subscribe(channels)
-				end
-				
-				def close
-					# There is no way to reset subscription state. On Redis v6+ you can use RESET, but this is not supported in <= v6.
-					@connection&.close
-					
-					super
-				end
-				
-				def listen
-					while response = @connection.read_response
-						return response if response.first == MESSAGE
-					end
-				end
-				
-				def each
-					return to_enum unless block_given?
-					
-					while response = self.listen
-						yield response
-					end
-				end
-				
-				def subscribe(channels)
-					@connection.write_request ["SUBSCRIBE", *channels]
-					@connection.flush
-				end
-				
-				def unsubscribe(channels)
-					@connection.write_request ["UNSUBSCRIBE", *channels]
-					@connection.flush
-				end
-			end
-		end
-	end
-end