How Undermoon Implements the Redis Cluster Protocol with a Server‑Side Proxy in Rust

Redis Cluster basics

Redis Cluster is the official distributed solution for Redis, providing sharding and failover. Clients that connect to a Redis Cluster must implement the Redis Cluster Client Protocol. The protocol’s core responsibilities are:

Redirecting a command when it is sent to the wrong node.

Caching the cluster routing table by issuing either CLUSTER NODES or CLUSTER SLOTS.

A client that implements these responsibilities is called a Smart Client .

Existing Redis Cluster proxies

To preserve compatibility with standard Redis clients, several Redis Cluster proxy projects exist:

https://github.com/RedisLabs/redis-cluster-proxy

https://github.com/wayslog/aster

https://github.com/eleme/corvus

https://github.com/samaritan-proxy/samaritan

Undermoon server‑side proxy

Undermoon implements the Redis Cluster Protocol as a server‑side proxy. The proxy behaves like the official Redis Cluster module and returns redirect responses when a key belongs to a different slot range.

Why a server‑side proxy?

Typical Redis proxies (e.g., redis‑cluster‑proxy, corvus, aster, codis) run on separate machines because they need to forward requests to multiple Redis instances. The server‑side proxy does not merely route requests; it acts as a cluster module, using a custom migration protocol to move data and scale quickly.

Benefits of the Undermoon implementation

Horizontal scalability and high availability for a self‑managed distributed Redis.

Redis resource‑pool management.

Support for multiple clusters per user.

Even traffic distribution across all physical machines.

Rapid scaling.

Easier integration with Kubernetes.

Demonstration

Run a single Redis instance: $ redis-server Build and start the server_proxy on port 5299, forwarding commands to 127.0.0.1:6379:

cargo build
make server

Connect to the proxy with redis-cli and initialize it using the UMCTL command:

redis-cli -p 5299
# Initialize the proxy
UMCTL SETCLUSTER v2 1 NOFLAGS mydb 127.0.0.1:6379 1 0-8000 PEER 127.0.0.1:7000 1 8001-16383

# Verify cluster view
CLUSTER NODES
mydb________________9f8fca2805923328____ 127.0.0.1:5299 myself,master - 0 0 1 connected 0-8000
mydb________________d458dd9b55cc9ad9____ 127.0.0.1:7000 master - 0 0 1 connected 8001-16383

# Request a key in the other slot range – receive a redirect
GET a
(error) MOVED 15495 127.0.0.1:7000

# Keys belonging to this proxy are handled directly
SET b 1
OK

This walk‑through shows the key difference between a regular Redis client and a Redis Cluster client: handling MOVED redirection responses.