Add more guides.

Author: samuel-williams-shopify

.rubocop.yml

@@ -1,4 +1,5 @@
 plugins:
+  - rubocop-md
   - rubocop-socketry
 
 AllCops:

context/getting-started.md

@@ -15,7 +15,7 @@ $ bundle add async-redis
 ### Basic Local Connection
 
 ``` ruby
-require 'async/redis'
+require "async/redis"
 
 Async do
 	endpoint = Async::Redis.local_endpoint(
@@ -42,7 +42,7 @@ You can also encode this information in a URL:
 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'
+require "async/redis"
 
 ssl_context = OpenSSL::SSL::SSLContext.new.tap do |context|
 	# Load the certificate store:
@@ -75,15 +75,15 @@ end
 ### Variables
 
 ``` 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.set('X', 10)
-	puts client.get('X')
+	client.set("X", 10)
+	puts client.get("X")
 ensure
 	client.close
 end

context/subscriptions.md

@@ -13,13 +13,13 @@ The `SUBSCRIBE` command is used to subscribe to one or more channels. When a mes
 First, let's create a simple listener that subscribes to messages on a channel:
 
 ``` 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
@@ -32,14 +32,14 @@ end
 Now, let's create a publisher that sends messages to the same channel:
 
 ``` 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 +57,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|
@@ -84,14 +84,14 @@ The `PSUBSCRIBE` command is used to subscribe to channels that match a given pat
 Let's replace the receiver in the above example:
 
 ``` 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 +110,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 +128,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
 ```

gems.rb

@@ -25,6 +25,7 @@
 	gem "decode"
 
 	gem "rubocop"
+	gem "rubocop-md"
 	gem "rubocop-socketry"
 
 	gem "bake-test"

guides/client-architecture/readme.md

@@ -0,0 +1,124 @@
+# Client Architecture
+
+This guide explains the different client types available in `async-redis` and when to use each one.
+
+## Redis Deployment Patterns
+
+Redis can be deployed in several configurations, each serving different scalability and availability needs:
+
+### Single Instance
+A single Redis server handles all operations. Simple to set up and manage, but limited by the capacity of one machine.
+
+**Use when:**
+- **Development**: Local development and testing.
+- **Small applications**: Low traffic applications with simple caching needs.
+- **Prototyping**: Getting started quickly without infrastructure complexity.
+
+**Limitations:**
+- **Single point of failure**: If Redis goes down, your application loses caching.
+- **Memory constraints**: Limited by the memory of one machine.
+- **CPU bottlenecks**: All operations processed by one Redis instance.
+
+Use {ruby Async::Redis::Client} to connect to a single Redis instance.
+
+``` ruby
+require "async/redis"
+
+endpoint = Async::Redis.local_endpoint
+client = Async::Redis::Client.new(endpoint)
+
+Async do
+	begin
+		client.set("cache:page", "cached content")
+		content = client.get("cache:page")
+		puts "Retrieved: #{content}"
+	ensure
+		client.close
+	end
+end
+```
+
+### Cluster (Sharded)
+
+Multiple Redis nodes work together, with data automatically distributed across nodes based on key hashing. Provides horizontal scaling and high availability.
+
+**Use when:**
+- **Large datasets**: Data doesn't fit in a single Redis instance's memory.
+- **High throughput**: Need to distribute load across multiple machines.
+- **Horizontal scaling**: Want to add capacity by adding more nodes.
+
+**Benefits:**
+- **Automatic sharding**: Data distributed across nodes based on consistent hashing.
+- **High availability**: Cluster continues operating if some nodes fail.
+- **Linear scaling**: Add nodes to increase capacity and throughput.
+
+Use {ruby Async::Redis::ClusterClient} to connect to a Redis cluster.
+
+``` ruby
+require "async/redis"
+
+cluster_endpoints = [
+	Async::Redis::Endpoint.new(hostname: "redis-1.example.com", port: 7000),
+	Async::Redis::Endpoint.new(hostname: "redis-2.example.com", port: 7001),
+	Async::Redis::Endpoint.new(hostname: "redis-3.example.com", port: 7002)
+]
+
+cluster_client = Async::Redis::ClusterClient.new(cluster_endpoints)
+
+Async do
+	begin
+		# Data automatically distributed across nodes:
+		cluster_client.set("cache:user:123", "user data")
+		cluster_client.set("cache:user:456", "other user data")
+		
+		data = cluster_client.get("cache:user:123")
+		puts "Retrieved from cluster: #{data}"
+	ensure
+		cluster_client.close
+	end
+end
+```
+
+Note that the cluster client automatically routes requests to the correct shard where possible.
+
+### Sentinel (Master/Slave with Failover)
+
+One master handles writes, multiple slaves handle reads, with sentinel processes monitoring for automatic failover.
+
+**Use when:**
+- **High availability**: Cannot tolerate Redis downtime.
+- **Read scaling**: Many read operations, fewer writes.
+- **Automatic failover**: Want automatic promotion of slaves to masters.
+
+**Benefits:**
+- **Automatic failover**: Sentinels promote slaves when master fails.
+- **Read/write separation**: Distribute read load across slave instances.
+- **Monitoring**: Built-in health checks and failure detection.
+
+Use {ruby Async::Redis::SentinelClient} to connect to a Redis sentinel.
+
+``` ruby
+require "async/redis"
+
+sentinel_endpoints = [
+	Async::Redis::Endpoint.new(hostname: "sentinel-1.example.com", port: 26379),
+	Async::Redis::Endpoint.new(hostname: "sentinel-2.example.com", port: 26379),
+	Async::Redis::Endpoint.new(hostname: "sentinel-3.example.com", port: 26379)
+]
+
+sentinel_client = Async::Redis::SentinelClient.new(
+	sentinel_endpoints,
+	master_name: "mymaster"
+)
+
+Async do
+	begin
+		# Automatically connects to current master:
+		sentinel_client.set("cache:critical", "important data")
+		data = sentinel_client.get("cache:critical")
+		puts "Retrieved from master: #{data}"
+	ensure
+		sentinel_client.close
+	end
+end
+```

guides/getting-started/readme.md

@@ -10,14 +10,23 @@ Add the gem to your project:
 $ bundle add async-redis
 ```
 
+## Core Concepts
+
+`async-redis` has several core concepts:
+
+- A {ruby Async::Redis::Client} which represents the main entry point for Redis operations.
+- An {ruby Async::Redis::Endpoint} which represents connection details including host, port, and authentication.
+- An {ruby Async::Redis::Context::Generic} which represents an actual connection to the Redis server.
+
 ## Usage
 
-### Basic Local Connection
+This example shows how to connect to a local Redis server:
 
 ``` ruby
-require 'async/redis'
+require "async/redis"
 
 Async do
+	# Create a local endpoint with optional configuration:
 	endpoint = Async::Redis.local_endpoint(
 		# Optional database index:
 		database: 1,
@@ -26,61 +35,56 @@ Async do
 	)
 
 	client = Async::Redis::Client.new(endpoint)
+	
+	# Get server information:
 	puts client.info
 
+	# Store and retrieve a value:
 	client.set("mykey", "myvalue")
 	puts client.get("mykey")
+ensure
+	# Always close the client to free resources:
+	client&.close
 end
 ```
 
-### Connecting to Redis SSL Endpoint
+### Connecting to Redis using SSL
 
 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'
+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://:[email protected]:12345
-endpoint = Async::Redis::Endpoint.parse(ENV["REDIS_URL"], ssl_context: ssl_context)
+# Parse Redis URL with SSL support.
+# Example: REDIS_URL=rediss://:[email protected]:12345
+endpoint = Async::Redis::Endpoint.parse(ENV["REDIS_URL"])
 client = Async::Redis::Client.new(endpoint)
+
 Sync do
 	puts client.call("PING")
+ensure
+	client&.close
 end
 ```
 
-### Variables
+Alternatively, you can parse a URL and pass credentials as options:
 
 ``` ruby
-require 'async'
-require 'async/redis'
+require "async/redis"
+
+# Parse URL and add credentials:
+endpoint = Async::Redis::Endpoint.parse(
+	"rediss://redis.example.com:6379",
+	credentials: ["username", "password"]
+	# Optional SSL context:
+	# ssl_context: ...
+)
 
-endpoint = Async::Redis.local_endpoint
 client = Async::Redis::Client.new(endpoint)
 
 Async do
-	client.set('X', 10)
-	puts client.get('X')
+	puts client.call("PING")
 ensure
-	client.close
+	client&.close
 end
 ```