# Distributed Cache Node
An in-memory, partition-tolerant distributed cache node designed for low-latency key-value storage. Implements consistent hashing with virtual nodes to minimize re-sharding overhead and utilizes a decentralized gossip membership protocol for automatic node discovery.
## Architectural Overview
```
Client Request -> Hash Ring Lookup -> Shard Leader (gRPC) -> In-Memory LRU
|
Gossip Heartbeat Protocol (UDP)
|
Peer Replicas (Sync)
```
### Core Components
1. **Consistent Hashing Ring**: Employs a 32-bit CRC hash ring with 150 virtual nodes per physical instance to ensure uniform key distribution across cluster boundaries.
2. **Gossip Protocol**: Periodic UDP heartbeats evaluate node reachability with adjustable suspicion intervals, preventing split-brain states during transient network partitions.
3. **gRPC Interface**: High-throughput multiplexed RPC endpoints provide sub-millisecond retrieval and mutation operations with protocol buffers serialization.
4. **LRU Eviction Engine**: Thread-safe doubly-linked list with hash map indexing, guaranteeing O(1) reads, updates, and memory-bounded evictions.
## Benchmarks
- **Throughput**: 120,000 requests/sec per shard (single m6i.xlarge node).
- **p99 Latency**: 0.42ms on local VPC networks.
- **Failover Convergence**: Under 1.2 seconds across 7 cluster nodes.
## Build and Run
```bash
# Build binary
go build -o bin/cache-node src/main.go
# Start primary node
./bin/cache-node --port=8080 --peers="10.0.0.2:8080,10.0.0.3:8080"
```