RedisAdapter

RedisAdapter is a C++ library for exchanging typed instrumentation data over Redis Streams. It provides a consistent key, timestamp, and payload model on top of hiredis and redis-plus-plus.

Features

• Typed scalar, string, attribute-map, and contiguous-array reads and writes.
• Time-range and latest-value queries with nanosecond RA_Time timestamps encoded directly in Redis Stream IDs.
• Background stream readers with typed callbacks, configurable reader sharding, and a worker pool for callback dispatch.
• Lazy reconnection after failed operations, including restoration of registered stream readers after Redis returns.
• Batched reader topology changes through setDeferReaders(), avoiding repeated thread teardown while a configuration is replaced.
• Wire-compatible {baseKey}:subKey construction with the required literal braces.
• Standalone Redis connections over TCP or a Unix-domain socket, with username/password authentication and connection pooling.
• Pub/sub helpers, generic readers for non-RedisAdapter streams, key lifecycle helpers, and field-TTL watchdogs.
• A versioned, implementation-independent RedisAdapter wire protocol.

The wire protocol is version 1.0. The C++ library is version 0.1.0; these are separate compatibility promises.

Redis Cluster is unsupported. After the first successful PING, the adapter sends CLUSTER INFO before making the connection available. A successful reply rejects the endpoint as Cluster; a server refusal, including ACL denial, accepts the endpoint without proving it is standalone. The decision is cached and reconnects never repeat the check. A transport failure leaves detection pending for the next connection attempt. Applications using a Cluster deployment must migrate their endpoint and data to standalone Redis before upgrading. The {baseKey}:subKey key format, including its braces, remains unchanged for compatibility with existing data and producers; this change does not bump the library or wire-protocol version.

Quick start

RedisAdapter is normally embedded into another CMake project. Clone it with its dependencies, then build the test target:

git clone --recurse-submodules https://github.com/fermi-ad/redis-adapter.git
cd redis-adapter
cmake -S . -B build -DREDIS_ADAPTER_TEST=ON
cmake --build build --parallel

Start Redis 7.4 or newer with both TCP and the test Unix socket enabled, then run the suite:

./redis-start.sh
ctest --test-dir build --output-on-failure

A minimal writer and reader look like this:

#include "RedisAdapter.hpp"

RedisAdapter redis("BPM01");

RA_Time written = redis.addSingleDouble("position", 1.25);
double position = 0.0;
RA_Time observed = redis.getSingleValue("position", position);

if (!written.ok() || !observed.ok()) {
  // Redis was unavailable or the operation failed.
}

The data is stored in the Redis Stream {BPM01}:position, under the binary-safe _ field. See Building from source for dependencies, test Redis options, and CMake integration.

Documentation

• Documentation index
• Building from source and CMake integration
• C++ API guide
• RedisAdapter Protocol Specification v1.0
• Release process
• Changelog

Support and security

Use GitHub issues for bugs and feature requests. Report security issues privately as described in SECURITY.md.

License

Project-authored code is available under the BSD 3-Clause License. The government-rights notice is in NOTICE, and dependency licenses are inventoried in THIRD_PARTY_NOTICES.md.

Use the private Redis fixture in scripts/run-test-redis.py for local tests. Legacy redis-start.sh is intended for an isolated machine and fails if its loopback port or Unix socket is already occupied. Fault tests require an explicitly isolated fixture; keep shared Redis services out of those tests.