Fred
An async Redis client for Rust built on Tokio and Futures.
Example
use *;
async
See the examples for more.
Install
With cargo edit.
cargo add fred
Features
- Supports clustered and centralized Redis deployments.
- Optional built-in reconnection logic with multiple backoff policies.
- Publish-Subscribe and keyspace events interfaces.
- Supports transactions.
- Supports Lua scripts.
- Supports custom commands provided by third party modules.
- Supports connections over TLS.
- Handles cluster rebalancing operations without downtime or errors.
- Supports various scanning functions.
- Automatically pipeline requests, with an option for callers to disable this.
- Automatically retry requests under bad network conditions.
- Support for configuring global settings that can affect performance under different network conditions. Callers can configure backpressure settings, when and how the underlying socket is flushed, and how many times requests are attempted.
- Built-in tracking for network latency and payload size metrics.
- A client pooling interface to round-robin requests among a pool of clients.
- Built in support for tracing.
Tracing
This crate supports tracing via the tracing crate. See the tracing docs for more information.
This feature is disabled by default, but callers can opt-in via the full-tracing
or partial-tracing
features.
Logging
To enable logs use the environment variable RUST_LOG
with a value of trace
, debug
, warn
, error
, or info
. See the documentation for env_logger for more information.
When a client is initialized it will generate a unique client name with a prefix of fred-
. This name will appear in all logging statements on the client in order to associate client and server operations if logging is enabled on both.
Compile Time Features
Name | Default | Description |
---|---|---|
enable-tls | x | Enable TLS support. This requires OpenSSL (or equivalent) dependencies. |
vendored-tls | Enable TLS support, using vendored OpenSSL (or equivalent) dependencies, if possible. | |
ignore-auth-error | x | Ignore auth errors that occur when a password is supplied but not required. |
reconnect-on-auth-error | A NOAUTH error is treated the same as a general connection failure and the client will reconnect based on the reconnection policy. | |
index-map | Use IndexMap instead of HashMap as the backing store for Redis Map types. | |
pool-prefer-active | x | Prefer connected clients over clients in a disconnected state when using the RedisPool interface. |
full-tracing | Enable full tracing support. This can emit a lot of data so a partial tracing feature is also provided. | |
partial-tracing | Enable partial tracing support, only emitting traces for top level commands and network latency. Note: this has a non-trivial impact on performance. | |
blocking-encoding | Use a blocking task for encoding or decoding frames over a certain size. This can be useful for clients that send or receive large payloads, but will only work when used with a multi-thread Tokio runtime. | |
network-logs | Enable TRACE level logging statements that will print out all data sent to or received from the server. |
Environment Variables
Name | Default | Description |
---|---|---|
FRED_DISABLE_CERT_VERIFICATION | false |
Disable certificate verification when using TLS features. |
FRED_DISABLE_HOST_VERIFICATION | false |
Disable host verification when using TLS features. |
These are environment variables because they're dangerous in production and callers should be forced to surface them in a loud and obvious way.
Pipelining
The caller can toggle pipelining by providing flags to the client's connect
function. These settings can drastically affect performance on both the server and client, but further performance tuning may be necessary to avoid issues such as using too much memory on the client or server while buffering commands.
See the global performance tuning functions for more information on how to tune backpressure or other relevant settings related to pipelining.
This module also contains a separate test application that can be used to demonstrate the effects of pipelining. This test application also contains some helpful information on how to use the tracing features.
Tests
To run the unit and integration tests:
cargo test -- --test-threads=1
OR
./tests/run.sh
Note: a local Redis server must be running on port 6379, and a clustered deployment must be running on ports 30001 - 30006 for the integration tests to pass.
Scripts are included to download and run centralized and clustered redis servers at any Redis version. These scripts will not make any modifications to your system outside the tests/tmp
folder.
export REDIS_VERSION=6.2.2
./tests/scripts/install_redis_centralized.sh
./tests/scripts/install_redis_clustered.sh
Beware: the tests will periodically run flushall
.
Contributing
See the contributing documentation for info on adding new commands.