redis-tower-modules 0.1.3

High-level ergonomic client interfaces for Redis Stack modules
Documentation

redis-tower

Crates.io Documentation CI License: MIT OR Apache-2.0

A typed, async Redis client built around Tower services.

  • Typed commands and responses for Redis 7.x, Redis 8.x, and Redis Stack.
  • A cloneable, auto-pipelined client for normal application traffic.
  • Standalone, Cluster, Sentinel, blocking, and topology-neutral clients.
  • Tower middleware, reconnection, pooling, client-side caching, metrics, TLS, and rotating credentials.

Install

cargo add redis-tower

The default feature set includes the Redis Stack command builders. A smaller core-only dependency looks like this:

[dependencies]
redis-tower = { version = "0.1", default-features = false }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Add the topology or higher-level crates only when you need them:

cargo add redis-tower-cluster redis-tower-sentinel redis-tower-client
cargo add redis-tower-modules redis-tower-primitives redis-tower-sync

The minimum supported Rust version is 1.88.

Quick start

MultiplexedClient is the recommended default. It is cheap to clone, accepts concurrent commands, and automatically pipelines work over one connection.

use redis_tower::{MultiplexedClient, RedisValueExt};
use redis_tower::commands::{Get, Set};

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let client = MultiplexedClient::connect("127.0.0.1:6379").await?;

client.execute(Set::new("greeting", "hello")).await?;
let greeting: String = client
    .execute(Get::new("greeting"))
    .await?
    .parse_into()?;

assert_eq!(greeting, "hello");
# Ok(())
# }

Redis URLs support authentication, database selection, Unix sockets, and TLS:

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
# use redis_tower::MultiplexedClient;
let client = MultiplexedClient::connect_url(
    "rediss://default:secret@redis.example.com:6380/0",
).await?;
# let _ = client;
# Ok(())
# }

Unix URLs use the redis-rs-compatible query form. Socket paths are percent-decoded, and the redis+unix and valkey+unix aliases are accepted:

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
# use redis_tower::MultiplexedClient;
let client = MultiplexedClient::connect_url(
    "redis+unix:///run/redis%20server.sock?user=app&pass=secret&db=1&protocol=resp3",
).await?;
# let _ = client;
# Ok(())
# }

Choose a client

Client Use it for
MultiplexedClient Most async applications; cloneable and auto-pipelined
CachedMultiplexedClient Read-heavy standalone workloads using RESP3 client-side caching
RedisConnection Exclusive access to one connection or custom Tower stacks
RedisClient Simple serialized sharing behind a mutex
ResilientRedisClient Automatic reconnect with optional bounded offline queuing
ConnectionPool Blocking commands, multiple sockets, or CPU-heavy response parsing
MultiplexedClusterClient High-concurrency Redis Cluster workloads
MultiplexedSentinelClient Sentinel discovery, failover, and replica reads
UniversalClient One application type selected by standalone, Cluster, or Sentinel URL
SyncClient CLI tools and other blocking code

The production tuning guide goes deeper on client selection, backpressure, timeouts, pooling, reconnects, and shutdown.

Common operations

Commands are ordinary typed values. Optional arguments use builder methods.

use redis_tower::commands::{Set, XAdd, ZAdd};

let set = Set::new("session:42", "active").ex(60).nx();
let score = ZAdd::new("leaders").member(100.0, "alice");
let event = XAdd::new("events").field("kind", "created");
# let _ = (set, score, event);

Pipelines batch a known group of commands. Transactions use Redis WATCH/MULTI/EXEC semantics.

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
# use redis_tower::{Pipeline, RedisConnection, Transaction};
# use redis_tower::commands::{Get, Incr, Set};
# let mut conn = RedisConnection::connect("127.0.0.1:6379").await?;
let results = Pipeline::new()
    .push(Set::new("a", "1"))
    .push(Incr::new("counter"))
    .push(Get::new("a"))
    .execute(&mut conn)
    .await?;

let transaction = Transaction::new()
    .watch(["counter"])
    .push(Incr::new("counter"))
    .execute(&mut conn)
    .await?;
# let _ = (results, transaction);
# Ok(())
# }

Deployment topologies

For binary channel or pattern names, use BinaryPubSubConnection and the subscribe_bytes / psubscribe_bytes / ssubscribe_bytes methods. Messages and tracked subscriptions retain Bytes, including across reconnects. Cluster clients expose pubsub_on_bytes and sharded_pubsub_bytes with the same routing and recovery behavior as the text API.

RESP3 attribute-prefixed replies currently fail with a protocol error. The transport closes rather than assign an attribute or its payload to the wrong pipelined request. Complete attribute metadata support needs a response model that pairs the prefix with its following value.

Cluster

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::commands::{Get, Set};
use redis_tower_cluster::{MultiplexedClusterClient, ReadPreference};

let client = MultiplexedClusterClient::builder("127.0.0.1:7000")
    .read_preference(ReadPreference::PreferReplica)
    .connect()
    .await?;

client.execute(Set::new("{user:42}:name", "Ada")).await?;
let name = client.execute(Get::new("{user:42}:name")).await?;
# let _ = name;
# Ok(())
# }

Raw FT.CURSOR and counted set/cardinality commands route by the index or first declared key, including binary keys and hash tags.

For node-local or connection-stateful work, client.connect_to_node(node) opens an exclusively owned connection to a current topology member using the client's authentication, TLS, protocol, and connection timeout settings. The caller bounds command duration and owns the socket; shared workers remain available. This connection does not route commands or replay failures.

The Cluster crate also provides explicit cross-node pipelines, split multi-key helpers, cluster-wide scans, regular and sharded Pub/Sub, replica routing, and automatic MOVED/ASK handling.

Sentinel

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::commands::Ping;
use redis_tower_sentinel::{MultiplexedSentinelClient, ReadPreference};

let client = MultiplexedSentinelClient::builder(
    &["127.0.0.1:26379", "127.0.0.1:26380"],
    "mymaster",
)
.read_preference(ReadPreference::PreferReplica)
.connect()
.await?;

client.execute(Ping::new()).await?;
# Ok(())
# }

One client for every topology

redis-tower-client chooses a variant from the URL scheme:

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::commands::Ping;
use redis_tower_client::UniversalClient;

let standalone = UniversalClient::connect_url("redis://127.0.0.1:6379").await?;
let cluster = UniversalClient::connect_url("redis+cluster://127.0.0.1:7000").await?;
let sentinel = UniversalClient::connect_url(
    "redis+sentinel://127.0.0.1:26379/mymaster",
).await?;

standalone.execute(Ping::new()).await?;
# let _ = (cluster, sentinel);
# Ok(())
# }

Use the rediss, rediss+cluster, and rediss+sentinel variants for TLS.

Data access modules

The redis-tower-modules crate provides higher-level clients over the lower- level typed command builders.

Module Client Typical use
RedisJSON json::JsonClient Serialize application types with Serde
RediSearch search::SearchClient Define indexes and deserialize query results
RedisTimeSeries timeseries::TimeSeriesClient Store and query timestamped samples
Probabilistic probabilistic::* Bloom, Cuckoo, CMS, TopK, and T-Digest
Vector Sets vector::VectorSetClient Add vectors and run similarity search

JSON

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::MultiplexedClient;
use redis_tower_modules::json::JsonClient;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct User { name: String }

let client = MultiplexedClient::connect("127.0.0.1:6379").await?;
let mut json = JsonClient::new(client);
json.set("user:42", "$", &User { name: "Ada".into() }).await?;
let user: Option<User> = json.get("user:42", "$").await?;
# let _ = user;
# Ok(())
# }

Search, time series, probabilistic structures, and vectors

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::RedisConnection;
use redis_tower_modules::probabilistic::BloomFilter;
use redis_tower_modules::search::{IndexBuilder, SearchClient};
use redis_tower_modules::timeseries::{TimeSeriesClient, TsKeyConfig, TsTimestamp};
use redis_tower_modules::vector::VectorSetClient;

let mut conn = RedisConnection::connect("127.0.0.1:6379").await?;

SearchClient::new(&mut conn)
    .create_index(IndexBuilder::new("users").on_hash().text_field("name"))
    .await?;

TimeSeriesClient::new(&mut conn)
    .create("temperature", TsKeyConfig::new().label("room", "lab"))
    .await?;
TimeSeriesClient::new(&mut conn)
    .add("temperature", TsTimestamp::Auto, 21.5)
    .await?;

{
    let mut bloom = BloomFilter::new(&mut conn, "seen-users");
    bloom.add("user:42").await?;
}

let mut vectors = VectorSetClient::new(&mut conn, "embeddings");
vectors.add(vec![1.0, 0.0, 0.0], "user:42").await?;
# Ok(())
# }

Pub/Sub, streams, and caching

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
# use redis_tower::RedisConnection;
let conn = RedisConnection::connect("127.0.0.1:6379").await?;
let mut pubsub = redis_tower::PubSubConnection::from_connection(conn)?;
pubsub.subscribe(&["events"]).await?;

while let Some(message) = pubsub.next().await {
    println!("{:?}", message?);
}
# Ok(())
# }

For durable processing, use Redis Streams through the typed X* commands or StreamConsumer.

RESP3 client-side caching is available as a managed client:

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
use std::time::Duration;
use redis_tower::{CachedClientConfig, CachedMultiplexedClient};
use redis_tower::commands::Get;

let config = CachedClientConfig::new()
    .max_entries(10_000)
    .client_ttl(Some(Duration::from_secs(30)));
let client = CachedMultiplexedClient::connect_with_config(
    "127.0.0.1:6379",
    config,
).await?;

let value = client.execute(Get::new("user:42")).await?;
# let _ = value;
# Ok(())
# }

Read the client-side caching guide for invalidation, failure, and consistency semantics.

Tower middleware

FrameService is a tower::Service<Frame>. CommandAdapter converts a frame stack back into a typed command service.

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::{CommandAdapter, FrameService, TracingLayer};
use tower::ServiceBuilder;

let service = ServiceBuilder::new()
    .layer(TracingLayer::new())
    .service(FrameService::connect("127.0.0.1:6379").await?);
let typed = CommandAdapter::new(service);
# let _ = typed;
# Ok(())
# }

The facade also includes request deadlines, Redis-aware retries and circuit breaking, reconnection, cache middleware, and metrics-facade integration.

Distributed primitives

redis-tower-primitives builds coordination tools on the same typed executor:

  • Fenced distributed locks and leader election.
  • Expirable semaphores and countdown latches.
  • Delayed queues and block-allocated IDs.
  • Redis-time GCRA rate limiting.
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
use std::time::Duration;
use redis_tower::MultiplexedClient;
use redis_tower_primitives::DistributedLock;

let mut client = MultiplexedClient::connect("127.0.0.1:6379").await?;
let lock = DistributedLock::new(
    "{invoice:42}:lock",
    "{invoice:42}:fence",
    Duration::from_secs(10),
)?;

if let Some(lease) = lock.acquire(&mut client).await? {
    let fencing_token = lease.fencing_token();
    // Pass fencing_token to the guarded resource and reject stale writers.
    lease.release(&mut client).await?;
}
# Ok(())
# }

These are Redis-backed leases, not consensus primitives. Read the distributed primitives guide before using them for correctness-sensitive work.

Authentication, TLS, and blocking code

Static credentials can be supplied through URLs or builders. Dynamic credentials implement CredentialProvider; companion crates provide AWS ElastiCache IAM and Microsoft Entra ID integrations:

  • redis-tower-auth-aws
  • redis-tower-auth-azure

The cloud authentication guide covers URL-backed provider factories, setup deadlines, shared provider caches, reconnect-time refresh, and the reconnect/replay rules for dedicated Pub/Sub, MONITOR, blocking, and transactional sessions.

Blocking applications can use redis-tower-sync:

use redis_tower_sync::SyncClient;
use redis_tower_sync::commands::{Get, Set};

# fn example() -> Result<(), Box<dyn std::error::Error>> {
let client = SyncClient::connect("127.0.0.1:6379")?;
client.execute(Set::new("key", "value"))?;
let value = client.execute(Get::new("key"))?;
# let _ = value;
# Ok(())
# }

Workspace crates

Crate Purpose
redis-tower Main client facade, middleware, pooling, caching, and resilience
redis-tower-core Connection, command trait, Tower frame service, URL/TLS, conversions
redis-tower-protocol RESP3 frames and bounded Tokio codec
redis-tower-commands Typed Redis and Redis Stack command builders
redis-tower-cluster Cluster topology, routing, redirects, scans, pipelines, and Pub/Sub
redis-tower-sentinel Sentinel discovery, failover, and replica reads
redis-tower-client Topology-neutral UniversalClient
redis-tower-modules High-level JSON, Search, TimeSeries, probabilistic, and vector clients
redis-tower-primitives Distributed coordination primitives
redis-tower-sync Blocking wrapper
redis-tower-auth-aws ElastiCache IAM credentials
redis-tower-auth-azure Microsoft Entra ID credentials
redis-tower-test Mocks and managed Redis test fixtures

Learn more

Runnable programs live in the examples directory.

Compatibility

Redis 7.x and 8.x are the supported server lines. CI exercises Redis 7.4 and 8.0 on every change, with a broader nightly Redis and Valkey matrix. Redis Stack command groups are feature-gated and return normal server errors when a module is unavailable.

redis-tower is pre-1.0. A 0.x minor release may contain breaking changes; those changes are called out in crate changelogs.

Security

See SECURITY.md for the vulnerability disclosure policy. The workspace forbids unsafe code and runs dependency policy and advisory checks in CI.

Contributing

See CONTRIBUTING.md for development setup and validation commands.

License

Licensed under either the MIT License or the Apache License, Version 2.0, at your option.

The vendored Redis documentation metadata used by the repository's conformance reports is licensed separately. See its license and attribution notice; that metadata is not included in the released Rust crates.