# Twemproxy — Fast Lightweight Proxy for Memcached and Redis

> Twemproxy (nutcracker) is a fast, lightweight proxy for Memcached and Redis developed by Twitter. It reduces the number of direct connections to cache servers and enables automatic sharding across a cluster.

## Install

Save in your project root:

# Twemproxy — Fast Lightweight Proxy for Memcached and Redis

## Quick Use
```bash
git clone https://github.com/twitter/twemproxy.git
cd twemproxy
autoreconf -fvi && ./configure && make
src/nutcracker -c conf/nutcracker.yml
```

## Introduction
Twemproxy (also called nutcracker) is a proxy created by Twitter to sit between application clients and pools of Memcached or Redis servers. It multiplexes thousands of client connections into a small number of backend connections, reducing resource usage while automatically distributing keys across shards.

## What Twemproxy Does
- Proxies requests to multiple Memcached or Redis instances transparently
- Automatically shards data using consistent hashing or other distribution strategies
- Multiplexes many client connections into fewer backend connections to reduce load
- Detects failed backends and temporarily ejects them from the pool
- Supports pipelining of requests and responses for higher throughput

## Architecture Overview
Twemproxy runs as a single-threaded event-driven process using epoll or kqueue. Incoming client connections are accepted on a listening socket and each request is parsed, hashed to a backend server, and forwarded. Responses travel back through the same proxy connection. The consistent hashing ring can be configured with ketama, modula, or random distribution modes.

## Self-Hosting & Configuration
- Build from source using autoconf and make, or install via package managers on some distributions
- Define server pools in a YAML configuration file specifying listen address, hash function, and backend list
- Set the hash algorithm (fnv1a_64, murmur, md5, crc32, etc.) and distribution mode (ketama, modula, random)
- Configure server_retry_timeout and server_failure_limit to control automatic ejection of unhealthy backends
- Enable stats collection on a dedicated port for monitoring via tools like collectd or Prometheus exporters

## Key Features
- Extremely low overhead with single-threaded epoll-based architecture
- Zero-copy proxying keeps latency minimal even at high throughput
- Supports both Memcached ASCII and Redis protocols in the same binary
- Connection multiplexing reduces the total number of TCP connections to backends
- Production-proven at Twitter-scale handling millions of requests per second

## Comparison with Similar Tools
- **Redis Cluster** — Native sharding built into Redis, but requires Redis 3.0+ and cluster-aware clients
- **ProxySQL** — Focused on MySQL protocol proxying, not cache stores
- **Envoy** — General-purpose L4/L7 proxy that can front Redis, but heavier and more complex
- **mcrouter** — Meta's Memcached proxy with richer routing, but Memcached-only
- **KeyDB** — Multi-threaded Redis fork with built-in active replication, but not a proxy

## FAQ
**Q: Does Twemproxy support Redis Cluster commands?**
A: No. Twemproxy predates Redis Cluster and implements its own sharding. Multi-key commands that span shards are not supported.

**Q: Can Twemproxy handle Redis Pub/Sub?**
A: No. Pub/Sub, blocking commands, and scripting are not proxied because they require stateful server affinity.

**Q: How does Twemproxy handle a backend going down?**
A: It ejects the server from the hash ring after a configurable number of failures and re-adds it after a timeout.

**Q: Is Twemproxy still maintained?**
A: The repository receives occasional updates. It remains widely deployed in production but new features are infrequent.

## Sources
- https://github.com/twitter/twemproxy
- https://github.com/twitter/twemproxy/blob/master/notes/recommendation.md

---
Source: https://tokrepo.com/en/workflows/asset-67cd36dd
Author: AI Open Source