fredis 10.1.0 - Docs.rs

# fredis

[![Crates.io](https://img.shields.io/crates/v/fredis.svg?style=flat-square)](https://crates.io/crates/fredis)
[![Docs.rs](https://img.shields.io/docsrs/fredis?style=flat-square)](https://docs.rs/fredis)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg?style=flat-square)](https://github.com/webc-site/fredis)

An asynchronous, high-performance client for **Redis** and **Valkey** in Rust.

> [!NOTE]
> **fredis** is an actively maintained fork of [aembke/fred.rs](https://github.com/aembke/fred.rs). Because the upstream repository is no longer actively maintained, this fork was created to modernize the codebase, support **Cloudflare Workers (TCP sockets)**, upgrade dependencies (such as `rand 0.10`, `oneshot 0.2`, `rustls 0.23`), migrate to **Rust Edition 2024**, and provide continuous maintenance and new features.

---

## Installation

Add `fredis` to your `Cargo.toml`:

```toml
[dependencies]
fredis = "10.1.0"
```

Or via `cargo`:

```bash
cargo add fredis
```

---

## Quick Example

```rust
use fredis::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Error> {
  let config = Config::from_url("redis://localhost:6379/1")?;
  let client = Builder::from_config(config)
    .with_connection_config(|config| {
      config.connection_timeout = Duration::from_secs(5);
      config.tcp = TcpConfig {
        nodelay: Some(true),
        ..Default::default()
      };
    })
    .build()?;

  client.init().await?;

  client.on_error(|(error, server)| async move {
    println!("{:?}: Connection error: {:?}", server, error);
    Ok(())
  });

  // Convert responses to common Rust types
  let foo: Option<String> = client.get("foo").await?;
  assert!(foo.is_none());

  client.set("foo", "bar", None, None, false).await?;

  // Or use turbofish to declare response types
  println!("Foo: {:?}", client.get::<String, _>("foo").await?);

  client.quit().await?;
  Ok(())
}
```

See the [examples](https://github.com/webc-site/fredis/tree/main/examples) directory for more usage patterns.

---

## Highlights

* **Cloudflare Workers Support**: Experimental support for Cloudflare Workers via TCP sockets (`cloudflare` feature).
* **Modern Rust**: Built on **Rust Edition 2024** (MSRV 1.85).
* **Protocol Flexibility**: Full support for both **RESP2** and **RESP3** protocol modes.
* **Deployment Topologies**: Works seamlessly with **Clustered**, **Centralized**, and **Sentinel** server topologies.
* **TLS & Security**: Secure connections via `native-tls` or `rustls` (with `aws-lc-rs` or `ring` backends).
* **High Performance**:
  * Automatic command pipelining across Tokio tasks
  * Zero-copy frame parsing powered by `redis-protocol`
  * Round-robin client pooling (`Pool` and `DynamicPool`)
  * Round-robin replica routing
* **Rich Feature Set**:
  * Publish-Subscribe and keyspace event streams
  * Built-in mocking layer for testing
  * Lua scripts and functions
  * Transactions and Client Tracking (client-side caching)
  * Distributed tracing integration

---

## Feature Flags

### Client Features

| Name | Default | Description |
|:-----|:-------:|:------------|
| `transactions` | **x** | Enable a [Transaction](https://redis.io/docs/interact/transactions/) interface. |
| `cloudflare` | | Enable experimental support for Cloudflare Workers (TCP sockets). |
| `enable-rustls` | | Enable TLS via [rustls](https://crates.io/crates/rustls) with the `aws-lc-rs` crypto backend. |
| `enable-rustls-ring` | | Enable TLS via [rustls](https://crates.io/crates/rustls) with the `ring` crypto backend. |
| `enable-native-tls` | | Enable TLS via [native-tls](https://crates.io/crates/native-tls). |
| `vendored-openssl` | | Enable `native-tls/vendored`. |
| `dynamic-pool` | | Enable dynamic client pooling that scales connections based on metrics. |
| `metrics` | | Enable latency, network latency, and payload size tracking. |
| `full-tracing` | | Enable detailed [tracing](./src/trace/README.md) across all commands and network frames. |
| `partial-tracing` | | Enable lightweight [tracing](./src/trace/README.md) for top-level commands. |
| `blocking-encoding` | | Offload encoding/decoding to blocking tasks (useful for heavy payloads). |
| `custom-reconnect-errors`| | Customize error types that trigger automatic reconnection. |
| `monitor` | | Enable the `MONITOR` command interface. |
| `sentinel-client` | | Enable direct communication with Sentinel nodes. |
| `sentinel-auth` | | Use distinct authentication credentials for Sentinel nodes. |
| `subscriber-client` | | Enable managed subscriber client for pub/sub channels. |
| `serde-json` | | Enable automatic conversion between Redis types and JSON via `serde_json`. |
| `mocks` | | Enable mocking interfaces for intercepting commands in unit/integration tests. |
| `dns` | | Override DNS lookup logic via `hickory-resolver`. |
| `replicas` | | Route read commands to replica nodes. |
| `default-nil-types` | | Enable looser parsing for `nil` values. |
| `sha-1` | | Enable hashing Lua scripts. |
| `unix-sockets` | | Enable Unix domain socket support. |
| `credential-provider` | | Dynamically load auth credentials at runtime. |
| `tcp-user-timeouts` | | Configure `TCP_USER_TIMEOUT` on TCP sockets. |
| `glommio` | | Enable experimental [Glommio](https://github.com/DataDog/glommio) runtime support (Linux only). |

---

### Command Interfaces

Command interfaces start with `i-` to control which public command sets are compiled:

| Name | Default | Description |
|:-----|:-------:|:------------|
| `i-std` | **x** | Enable standard data structure interfaces (`keys`, `hashes`, `lists`, `sets`, `streams`, etc.). |
| `i-all` | | Enable all command interfaces listed below. |
| `i-acl` | | Enable ACL commands. |
| `i-client` | | Enable `CLIENT` commands. |
| `i-cluster` | | Enable `CLUSTER` commands. |
| `i-config` | | Enable `CONFIG` commands. |
| `i-geo` | | Enable geospatial commands (`GEOADD`, `GEODIST`, etc.). |
| `i-hashes` | | Enable hash commands (`HGET`, `HSET`, etc.). |
| `i-hyperloglog` | | Enable HyperLogLog commands (`PFADD`, `PFCOUNT`, etc.). |
| `i-keys` | | Enable general key management commands (`GET`, `SET`, `DEL`, `EXPIRE`, etc.). |
| `i-lists` | | Enable list commands (`LPUSH`, `RPOP`, etc.). |
| `i-memory` | | Enable `MEMORY` commands. |
| `i-pubsub` | | Enable Publish/Subscribe commands (`SUBSCRIBE`, `PUBLISH`, etc.). |
| `i-scripts` | | Enable Lua scripting & functions (`EVAL`, `FUNCTION`, etc.). |
| `i-server` | | Enable server administration commands (`SHUTDOWN`, `BGSAVE`, etc.). |
| `i-sets` | | Enable set commands (`SADD`, `SMEMBERS`, etc.). |
| `i-slowlog` | | Enable `SLOWLOG` commands. |
| `i-sorted-sets` | | Enable sorted set commands (`ZADD`, `ZRANGE`, etc.). |
| `i-streams` | | Enable Redis streams commands (`XADD`, `XREAD`, `XGROUP`, etc.). |
| `i-tracking` | | Enable [Client Tracking](https://redis.io/docs/manual/client-side-caching/) (client-side caching). |

---

### Redis Stack & Module Features

| Name | Default | Description |
|:-----|:-------:|:------------|
| `i-redis-json` | | Enable [RedisJSON](https://github.com/RedisJSON/RedisJSON) commands (`JSON.SET`, `JSON.GET`, etc.). |
| `i-redisearch` | | Enable [RediSearch](https://github.com/RediSearch/RediSearch) commands (`FT.CREATE`, `FT.SEARCH`, etc.). |
| `i-time-series` | | Enable [Redis TimeSeries](https://redis.io/docs/data-types/timeseries/) commands (`TS.ADD`, `TS.RANGE`, etc.). |
| `i-redis-stack` | | Enable all Redis Stack features (`i-redis-json`, `i-redisearch`, `i-time-series`). |
| `i-hexpire` | | Enable field-level hash expiration (`HEXPIRE`, `HTTL`, etc., Redis >= 7.4). |

---

## License

Licensed under either of:

* Apache License, Version 2.0 ([LICENSE-APACHE](http://www.apache.org/licenses/LICENSE-2.0))
* MIT license ([LICENSE-MIT](http://opensource.org/licenses/MIT))

at your option.