async-redis 0.12.0 → 0.13.1

data/context/subscriptions.md

@@ -2,24 +2,35 @@
 
 This guide explains how to use Redis pub/sub functionality with `async-redis` to publish and subscribe to messages.
 
+Redis pub/sub enables real-time communication between different parts of your application or between different applications. It's perfect for broadcasting notifications, coordinating distributed systems, or building real-time features, provided you don't need reliable messaging.
+
+Common use cases:
+- **Real-time notifications**: Alert users about new messages, updates, or events.
+- **System coordination**: Notify services about configuration changes or cache invalidation.
+- **Live updates**: Push data changes to web interfaces or mobile apps.
+- **Event-driven architecture**: Decouple services through asynchronous messaging.
+
 ## 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.
+Redis provides 3 pub/sub mechanisms:
+- **SUBSCRIBE**: Subscribe to specific channels by name.
+- **PSUBSCRIBE**: Subscribe to channels matching patterns (e.g., `user.*`).
+- **SSUBSCRIBE**: Sharded subscriptions for cluster environments (better performance).
 
 ## 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.
+The `SUBSCRIBE` command lets you listen for messages on specific channels. This creates a persistent connection that receives messages as they're published.
 
-First, let's create a simple listener that subscribes to messages on a channel:
+Here's a simple notification system - first, create a listener:
 
 ``` ruby
-require 'async'
-require 'async/redis'
+require "async"
+require "async/redis"
 
 client = Async::Redis::Client.new
 
 Async do
-	client.subscribe 'status.frontend' do |context|
+	client.subscribe "status.frontend" do |context|
 		puts "Listening for messages on 'status.frontend'..."
 		
 		type, name, message = context.listen
@@ -29,17 +40,17 @@ Async do
 end
 ```
 
-Now, let's create a publisher that sends messages to the same channel:
+In another part of your application, publish notifications:
 
 ``` ruby
-require 'async'
-require 'async/redis'
+require "async"
+require "async/redis"
 
 client = Async::Redis::Client.new
 
 Async do
 	puts "Publishing message..."
-	client.publish 'status.frontend', 'good'
+	client.publish "status.frontend", "good"
 	puts "Message sent!"
 end
 ```
@@ -57,13 +68,13 @@ Received: good
 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'
+require "async"
+require "async/redis"
 
 client = Async::Redis::Client.new
 
 Async do
-	client.subscribe 'status.frontend' do |context|
+	client.subscribe "status.frontend" do |context|
 		puts "Listening for messages on 'status.frontend'..."
 		
 		context.each do |type, name, message|
@@ -79,19 +90,19 @@ 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.
+When you need to listen to multiple related channels, patterns save you from subscribing to each channel individually. This is perfect for monitoring all user activities or all events from a specific service.
 
-Let's replace the receiver in the above example:
+For example, to monitor all user-related events (`user.login`, `user.logout`, `user.signup`):
 
 ``` ruby
-require 'async'
-require 'async/redis'
+require "async"
+require "async/redis"
 
 endpoint = Async::Redis.local_endpoint
 client = Async::Redis::Client.new(endpoint)
 
 Async do
-	client.psubscribe 'status.*' do |context|
+	client.psubscribe "status.*" do |context|
 		puts "Listening for messages on 'status.*'..."
 		
 		type, pattern, name, message = context.listen
@@ -110,14 +121,14 @@ If you are working with a clustered environment, you can improve performance by
 To use sharded subscriptions, use a cluster client which supports sharded pub/sub:
 
 ``` ruby
-require 'async'
-require 'async/redis'
+require "async"
+require "async/redis"
 
 # endpoints = ...
 cluster_client = Async::Redis::ClusterClient.new(endpoints)
 
 Async do
-	cluster_client.subscribe 'status.frontend' do |context|
+	cluster_client.subscribe "status.frontend" do |context|
 		puts "Listening for messages on 'status.frontend'..."
 		
 		type, name, message = context.listen
@@ -128,15 +139,15 @@ end
 ```
 
 ``` ruby
-require 'async'
-require 'async/redis'
+require "async"
+require "async/redis"
 
 # endpoints = ...
 cluster_client = Async::Redis::ClusterClient.new(endpoints)
 
 Async do
 	puts "Publishing message..."
-	cluster_client.publish('status.frontend', 'good')
+	cluster_client.publish("status.frontend", "good")
 	puts "Message sent!"
 end
 ```

data/context/transactions-and-pipelines.md

@@ -0,0 +1,197 @@
+# Transactions and Pipelines
+
+This guide explains how to use Redis transactions and pipelines with `async-redis` for atomic operations and improved performance.
+
+By default, each command (e.g. `GET key`) acquires a connection from the client, runs the command, returns the result and releases the connection back to the client's connection pool. This may be inefficient for some use cases, and so there are several ways to group together operations that run on the same connection.
+
+## Transactions (MULTI/EXEC)
+
+Transactions ensure that multiple Redis commands execute atomically - either all commands succeed, or none of them do. This is crucial when you need to maintain data consistency, such as transferring money between accounts or updating related fields together.
+
+Use transactions when you need:
+- **Atomic updates**: Multiple operations that must all succeed or all fail.
+- **Data consistency**: Keeping related data in sync across multiple keys.
+- **Preventing partial updates**: Avoiding situations where only some of your changes are applied.
+
+Redis transactions queue commands and execute them all at once:
+
+``` ruby
+require "async/redis"
+
+endpoint = Async::Redis.local_endpoint
+client = Async::Redis::Client.new(endpoint)
+
+Async do
+	begin
+		# Execute commands atomically:
+		results = client.transaction do |context|
+			context.multi
+			
+			# Queue commands for atomic execution:
+			context.set("user:1:name", "Alice")
+			context.set("user:1:email", "alice@example.com")
+			context.incr("user:count")
+			
+			# Execute all queued commands:
+			context.execute
+		end
+		
+		puts "Transaction results: #{results}"
+		
+	ensure
+		client.close
+	end
+end
+```
+
+### Watch/Unwatch for Optimistic Locking
+
+When multiple clients might modify the same data simultaneously, you need to handle race conditions. Redis WATCH provides optimistic locking - the transaction only executes if watched keys haven't changed since you started watching them.
+
+This is essential for scenarios like:
+- Updating counters or balances where the current value matters.
+- Implementing atomic increment operations with business logic.
+- Preventing lost updates in concurrent environments.
+
+Here's how to implement safe concurrent updates:
+
+``` ruby
+require "async/redis"
+
+endpoint = Async::Redis.local_endpoint
+client = Async::Redis::Client.new(endpoint)
+
+Async do
+	begin
+		# Initialize counter.
+		client.set("counter", 0)
+		
+		# Optimistic locking example:
+		5.times do |i|
+			success = false
+			attempts = 0
+			
+			while !success && attempts < 3
+				attempts += 1
+				
+				result = client.transaction do |context|
+					# Watch the counter for changes (executes immediately):
+					context.watch("counter")
+					
+					# Read current value (executes immediately):
+					current_value = client.get("counter").to_i
+					new_value = current_value + 1
+					
+					# Start transaction - commands after this are queued, not executed:
+					context.multi
+					
+					# Queue commands (these return "QUEUED", don't execute yet):
+					context.set("counter", new_value)
+					context.set("last_update", Time.now.to_f)
+					
+					# Execute all queued commands atomically.
+					# Returns nil if watched key was modified by another client:
+					context.execute
+				end
+				
+				if result
+					puts "Increment #{i + 1} succeeded: #{result}"
+					success = true
+				else
+					puts "Increment #{i + 1} failed, retrying (attempt #{attempts})"
+					sleep 0.01
+				end
+			end
+		end
+		
+		final_value = client.get("counter")
+		puts "Final counter value: #{final_value}"
+		
+	ensure
+		client.close
+	end
+end
+```
+
+## Pipelines
+
+When you need to execute many Redis commands quickly, sending them one-by-one creates network latency bottlenecks. Pipelines solve this by batching multiple commands together, dramatically reducing round-trip time.
+
+Use pipelines when you need:
+- **Better performance**: Reduce network round trips for bulk operations.
+- **High throughput**: Process hundreds or thousands of commands efficiently.
+- **Independent operations**: Commands that don't depend on each other's results.
+
+Unlike transactions, pipeline commands are not atomic - some may succeed while others fail:
+
+``` ruby
+require "async/redis"
+
+endpoint = Async::Redis.local_endpoint
+client = Async::Redis::Client.new(endpoint)
+
+Async do
+	begin
+		# Execute commands in a pipeline:
+		results = client.pipeline do |context|
+			# Commands are buffered and flushed if needed:
+			context.set("pipeline:1", "value1")
+			context.set("pipeline:2", "value2")
+			context.set("pipeline:3", "value3")
+			
+			context.get("pipeline:1")
+			context.get("pipeline:2")
+			context.get("pipeline:3")
+			
+			# Flush and collect the results from all previous commands:
+			context.collect
+		end
+		
+		puts "Pipeline results: #{results}"
+		
+	ensure
+		client.close
+	end
+end
+```
+
+### Synchronous Pipeline Operations
+
+When you need immediate results from individual commands within a pipeline, use `context.sync`:
+
+``` ruby
+require "async/redis"
+
+endpoint = Async::Redis.local_endpoint
+client = Async::Redis::Client.new(endpoint)
+
+Async do
+	begin
+		client.pipeline do |context|
+			# Set values using pipeline - no immediate response:
+			context.set("async_key_1", "value1")
+			context.set("async_key_2", "value2")
+			
+			# Get immediate response using sync:
+			immediate_result = context.sync.get("async_key_1")
+			puts "Immediate result: #{immediate_result}"
+			
+			# Continue with pipelined operations:
+			context.get("async_key_2")
+			
+			# Collect remaining pipelined results:
+			context.collect
+		end
+		
+	ensure
+		client.close
+	end
+end
+```
+
+Use `context.sync` when you need to:
+- **Check values mid-pipeline**: Verify data before continuing with more operations.
+- **Conditional logic**: Make decisions based on current Redis state.
+- **Debugging**: Get immediate feedback during pipeline development.
+
+Note that `sync` operations execute immediately and flush pending responses, so use them strategically to maintain pipeline performance benefits.

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

@@ -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/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,
@@ -63,13 +74,13 @@ module Async
 			# @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"
+				scheme ||= options[:ssl_context] ? "rediss" : "redis"
 				
 				uri_klass = SCHEMES.fetch(scheme.downcase) do
 					raise ArgumentError, "Unsupported scheme: #{scheme.inspect}"
@@ -82,7 +93,6 @@ module Async
 				self.new(
 					uri_klass.build(
 						scheme: scheme,
-						userinfo: credentials&.join(":"),
 						host: host,
 						port: port,
 						path: path,
@@ -263,7 +273,7 @@ module Async
 			# @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:
@@ -345,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/range_map.rb

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

data/lib/async/redis/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Redis
-		VERSION = "0.12.0"
+		VERSION = "0.13.1"
 	end
 end

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,12 +14,27 @@ 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.

data/releases.md

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

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: async-redis
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.1
 platform: ruby
 authors:
 - Samuel Williams
 - Huba Nagy
 - David Ortiz
+- Joan Lledó
 - Gleb Sinyavskiy
 - Mikael Henriksson
 - Travis Bell
 - Troex Nevelin
 - Alex Matchneer
 - Jeremy Jung
-- Joan Lledó
 - Olle Jonsson
 - Pierre Montelle
 - Salim Semaoune
@@ -125,9 +125,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/client-architecture.md
+- context/data-structures.md
 - context/getting-started.md
 - context/index.yaml
+- context/scripting.md
+- context/streams.md
 - context/subscriptions.md
+- context/transactions-and-pipelines.md
 - lib/async/redis.rb
 - lib/async/redis/client.rb
 - lib/async/redis/cluster_client.rb
@@ -167,7 +172,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: A Redis client library.
 test_files: []