redis-universal-client 0.4.0

Simple wrapper around Client and ClusterClient, like go-redis UniversalClient
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# redis-universal-client

Simple wrapper around `redis::Client` and `redis::cluster::ClusterClient`, inspired by go-redis [UniversalClient](https://pkg.go.dev/github.com/redis/go-redis/v9#UniversalClient).

Provides a single `UniversalClient` type that works with both standalone Redis and Redis Cluster, using async multiplexed connections under the hood.

## Usage

Add to your `Cargo.toml`:

```toml
[dependencies]
redis-universal-client = "0.3.0"
```

### Standalone Redis

```rust
use redis::AsyncCommands;
use redis_universal_client::UniversalClient;

#[tokio::main]
async fn main() -> redis::RedisResult<()> {
    let client = UniversalClient::open(vec!["redis://127.0.0.1:6379"])?;
    let mut conn = client.get_connection().await?;

    let _: () = conn.set("key", "value").await?;
    let val: String = conn.get("key").await?;
    println!("{}", val);
    Ok(())
}
```

### Redis Cluster

When multiple addresses are provided, `open` automatically creates a cluster client:

```rust
use redis::AsyncCommands;
use redis_universal_client::UniversalClient;

#[tokio::main]
async fn main() -> redis::RedisResult<()> {
    let client = UniversalClient::open(vec![
        "redis://127.0.0.1:7000",
        "redis://127.0.0.1:7001",
        "redis://127.0.0.1:7002",
    ])?;
    let mut conn = client.get_connection().await?;

    let _: () = conn.set("key", "value").await?;
    let val: String = conn.get("key").await?;
    println!("{}", val);
    Ok(())
}
```

### Builder

Use `UniversalBuilder` for explicit control over cluster mode, credentials, and TLS:

```rust
use redis_universal_client::UniversalBuilder;

// Force cluster mode with a single address
let client = UniversalBuilder::new(vec!["redis://127.0.0.1:7000".to_string()])
    .cluster(true)
    .build()?;

// ACL authentication (Redis 6.0+)
let client = UniversalBuilder::new(vec!["redis://127.0.0.1:6379".to_string()])
    .username("alice")
    .password("secret")
    .build()?;

// TLS (requires the tls-rustls or tls-native-tls feature)
let client = UniversalBuilder::new(vec!["redis://127.0.0.1:6380".to_string()])
    .tls(redis::TlsMode::Secure)
    .build()?;
```

## Features

All TLS features use the same names as the underlying `redis` crate.

| Feature | Description |
|---|---|
| `tls-native-tls` | TLS via native-tls (OS certificate store) |
| `tls-rustls` | TLS via rustls (native OS certificate store) |
| `tls-rustls-insecure` | rustls with support for `TlsMode::Insecure` (skips certificate verification) |
| `tls-rustls-webpki-roots` | rustls with Mozilla's WebPKI root certificates instead of the OS store |
| `tokio-native-tls-comp` | Alias for `tls-native-tls` |
| `tokio-rustls-comp` | Alias for `tls-rustls` |

TLS can also be enabled without these features by using a `rediss://` URL directly:

```toml
[dependencies]
redis-universal-client = { version = "0.3.0", features = ["tls-rustls"] }
```

```rust
// rediss:// enables TLS (secure); rediss://<host>/#insecure skips cert verification
let client = UniversalClient::open(vec!["rediss://127.0.0.1:6380"])?;
```

## How it works

| Addresses | `open` behavior | `UniversalBuilder` behavior |
|-----------|----------------|-----------------------------|
| 1 address | `Client` (standalone) | Depends on `.cluster()` flag |
| N addresses | `ClusterClient` | Depends on `.cluster()` flag |

`UniversalConnection` implements `redis::aio::ConnectionLike`, so you can use all `redis::AsyncCommands` on it. Both variants use async multiplexed connections (`MultiplexedConnection` / `cluster_async::ClusterConnection`) which are `Clone + Send + Sync`.

## Testing

```bash
# Unit tests (no Docker required)
cargo test --lib

# Integration tests with standalone Redis (requires Docker)
cargo test --test single

# Integration tests with ACL authentication (requires Docker)
cargo test --test acl

# Integration tests with Redis Cluster (requires Docker)
RUN_CLUSTER_TESTS=1 cargo test --test cluster
```

## License

BSD-3-Clause