🚀 Distributed In-Memory Key-Value Store

A high-performance, distributed, lock-free Redis-clone written from scratch in C++20.

---

📖 Overview

Modern web applications require sub-millisecond access to caches and session data. Relational databases on disk are too slow for these operations. This project solves that by keeping data entirely in RAM, managing high-concurrency access, and ensuring data isn't lost during power failures via disk persistence.

This project is a ground-up recreation of Redis. It speaks the exact same strict REdis Serialization Protocol (RESP) natively over TCP sockets, allowing standard Redis clients to technically communicate with it. It focuses strictly on String values to perfect the core distributed systems algorithms: memory sharding, probabilistic eviction, AOF persistence, and real-time streaming replication.

---

✨ Core Features

• 🌐 Custom TCP Multiplexing Engine: Implements a native Thread-Per-Connection architecture built directly on top of raw POSIX sockets for high-concurrency client multiplexing.
• 🗣️ Strict RESP Protocol: Handrolls a fully-compliant RESP parser for reading byte-chunks and safely decoding arrays, bulk strings, integers, simple strings, and complex nested commands.
• ⚡ Lock-Free Dictionary Sharding: Bypasses the traditional global std::mutex bottleneck by splitting the primary index into an array of isolated shards using std::shared_mutex, unlocking massive parallel throughput.
• 🗑️ O(1) Approximate LRU Eviction: Strictly enforces memory thresholds (maxmemory) via random-bucket sampling, elegantly evicting stale keys in constant time without the memory bloat of doubly-linked lists.
• ⏳ Lazy & Active Expiration (TTL): Time-to-live cache invalidation powered by both active background sweeper threads and lazy read-time evaluation.
• 💾 Durability via AOF: Serializes all mutating events directly into an Append-Only File (AOF). Upon startup, the system parses the AOF to fully rebuild memory state deterministically.
• 🔄 Distributed Replication: Builds a powerful Primary-Replica streaming pipeline. Replicas initiate a PSYNC offset handshake, and the Primary blasts byte-for-byte AOF diffs directly across the TCP stream to enforce perfect mirroring.
• 📊 Observability Layer: Emits real-time atomic telemetry on cache hits, misses, TTL expirations, and throughput via the INFO dashboard command.

---

🏛️ Architecture & System Topology

Instead of placing a massive global mutex around a single std::unordered_map (which artificially caps concurrent read/writes), the StorageEngine utilizes Dictionary Sharding. The core index is split into 16 distinct Shard objects. When a key is inserted, the engine hashes it, computes modulo 16, and locks only that specific shard. This allows 16 parallel threads to perform operations simultaneously with zero lock contention.

 [ Python Client ]       [ Python Client ]
        |                       |
        +------- (TCP 6379) ----+
                    |
          +-------------------+
          |  Primary KV Node  | <---- Tracks `connected_clients` (Atomic)
          +-------------------+
          | - TCP Listener    |
          | - RESP Parser     |
          | - Cmd Dispatcher  |
          +-------------------+
                    |
          +-------------------+                 +-------------------+
          |  Storage Engine   | -- (AOF Sync) - | appendonly.aof    |
          +-------------------+                 +-------------------+
          | - Shard 0 (Mutex) |                           |
          | - Shard 1 (Mutex) |                      (TCP Stream)
          | - ...             |                           |
          | - Shard 15(Mutex) |                 +-------------------+
          +-------------------+                 |  Replica KV Node  |
                    |                           +-------------------+
          (Background Sweeper)                  | - Read Only Mode  |
          (Purges expired TTL)                  | - replica_aof.aof |
                                                +-------------------+

---

🏎️ Benchmarks & Performance

The core has been rigorously benchmarked using a multi-threaded Python 3 testing rig under extreme load scenarios. Utilizing C++20 atomics and sharded locks, the server's theoretical maximum throughput is exceptionally high.

Metric	Result	Description
Throughput	~ 12,000 req / sec	Sustained parallel SET/GET commands locally via Python threads (with strict synchronous disk fsync).
P50 Latency	0.73 ms	Median round-trip time.
P99 Latency	2.11 ms	The slowest 1% of transactions still complete in ~2 milliseconds.
Recovery Time	242 ms	The time required to read, decode, and execute an AOF containing 20,000 commands after a catastrophic process crash.
Replication Lag	0.27 ms	The microsecond delay between Primary execution and Replica convergence.

---

🛠️ Build & Installation

Option A: Build from Source (Ubuntu/Linux)

Requirements: C++20 Compiler (GCC 10+ or Clang 11+), CMake 3.15+, Make

# 1. Clone the repository
git clone https://github.com/Akgithub2028/Distributed-In-Memory-Key-Value-Store.git
cd Distributed-In-Memory-Key-Value-Store

# 2. Build the project
mkdir build && cd build
cmake ..
make -j$(nproc)
cd ..

# 3. Run the automated Python integration suite to verify
python3 tests/run_tests.py

Option B: Docker Compose (Instant Cluster)

If you have Docker installed, you can instantly spin up a distributed Primary and Replica cluster with zero configuration:

docker compose -f docker/docker-compose.yml up -d

(This will launch the Primary on port 6379 and the Replica on port 6380)

---

🚀 Quick Start / Usage Guide

Starting the Server

# Start standalone primary node
./build/redis_kv_store --port 6379

# Start a replica node (syncing from primary)
./build/redis_kv_store --port 6380 --replicaof 127.0.0.1 6379

Interacting via Python Client

The repository includes a native Python KVClient that handles the raw RESP byte-serialization for you.

from tools.client import KVClient

# Connect to the primary node
db = KVClient(host='127.0.0.1', port=6379)
db.connect()

# Basic CRUD
db.set("user:1000", "Alice")
print(db.get("user:1000"))  # Output: 'Alice'
db.delete("user:1000")

# Atomic Counters
db.set("page_views", "10")
db.incr("page_views")
print(db.get("page_views")) # Output: '11'

# Time-To-Live (TTL)
db.set("session_token", "abc123xyz")
db.execute_command("EXPIRE", "session_token", 5) # Expires in 5 seconds

Supported Commands

• PING [message] - Tests connection.
• ECHO message - Echoes the given string.
• SET key value - Stores a string value.
• GET key - Retrieves a string value.
• DEL key [key ...] - Removes one or more keys.
• EXISTS key [key ...] - Returns the number of keys that exist.
• INCR key - Atomically increments an integer string.
• DECR key - Atomically decrements an integer string.
• EXPIRE key seconds - Sets a timeout on key.
• PEXPIRE key milliseconds - Sets a timeout in milliseconds.
• TTL key - Returns remaining time to live in seconds.
• PTTL key - Returns remaining time to live in milliseconds.
• PERSIST key - Removes expiration from a key.
• INFO [section] - Returns system health, memory, and telemetry statistics.
• CONFIG SET parameter value - Dynamically updates server configuration (e.g., MAXMEMORY).
• QUIT - Closes the connection.

---

📈 Telemetry & Observability

You can view real-time engine metrics via the INFO STATS or INFO MEMORY commands:

# Memory
used_memory:104250
maxmemory:0

# Stats
total_commands_processed:42
keyspace_hits:15
keyspace_misses:2
evicted_keys:0
expired_keys:1

# Replication
role:master
master_repl_offset:24510

• keyspace_hits / keyspace_misses: Live cache hit ratio.
• evicted_keys: Tracks how many stale keys the LRU algorithm has destroyed due to OOM memory pressure.
• expired_keys: Tracks natural TTL expirations.

---

📂 Project Structure

├── CMakeLists.txt        # Build configuration
├── README.md             # You are here
├── bench/                # Multi-threaded Python benchmarking rig
├── docker/               # Dockerfiles and Compose scripts
├── docs/                 # Extended technical architecture guides
├── include/              # C++ Header files (.h)
│   ├── net/              # Raw TCP Sockets & Connection handling
│   ├── protocol/         # RESP Serialization/Deserialization
│   ├── server/           # Command Dispatcher, Metrics, Server Core
│   └── storage/          # Storage Engine, Shards, AOF Logger
├── src/                  # C++ Source files (.cpp)
├── tests/                # Automated validation & integration suite
└── tools/                # Native Python Client wrapper

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.