🚀 Distributed LSM-Tree Key-Value Store

A high-performance, production-grade distributed key-value store implemented in Go, featuring a log-structured storage engine (LSM-tree), replication, and multi-protocol support.

✨ Features

• Storage Engine: High-performance LSM-tree implementation with:
  • WAL (Write-Ahead Log) for crash recovery and atomicity.
  • MemTable for fast, concurrent in-memory operations.
  • SSTables (Sorted String Tables) for persistent, efficient storage.
  • Automatic Compaction for space reclamation and read optimization.
• TTL Support: Per-key expiration with automatic cleanup.
• Distributed Architecture:
  • Leader-Follower Replication for data durability and high availability.
  • Quorum-based Reads/Writes to ensure consistency across nodes.
• Multi-Protocol Support:
  • HTTP REST API for ease of integration.
  • TCP Binary Protocol for high-throughput, low-latency communication.
• Observability: Prometheus-compatible metrics for real-time monitoring.
• CLI Tool: kvctl for easy administration and debugging.

🏗 Architecture

The store follows a classic Log-Structured Merge-Tree (LSM-tree) design:

1. Write Path: Incoming writes are first appended to the WAL and then added to the MemTable. When the MemTable reaches its capacity, it is flushed to disk as an SSTable.
2. Read Path: Reads search the MemTable first, then browse SSTables (from newest to oldest).
3. Background Processes: Periodic compaction merges SSTables, removes duplicates, and purges expired entries (TTL) or deleted items (tombstones).

🚀 Getting Started

Prerequisites

• Go 1.21 or higher
• Make

Building

Build both the server and the CLI tool:

make build

Binaries will be available in the bin/ directory.

Running the Server

Start a standalone node:

./bin/server -data-dir ./data -http-addr :8080 -tcp-addr :9090

Using the CLI

The kvctl tool allows you to interact directly with the storage engine:

# Put a value
./bin/kvctl put mykey myvalue

# Get a value
./bin/kvctl get mykey

# Delete a value
./bin/kvctl delete mykey

🌐 API Reference

HTTP REST API

Method	Endpoint	Description
GET	/{key}	Retrieve a value
PUT	/{key}	Store a value
DELETE	/{key}	Delete a key

Store a value (JSON):

curl -X PUT http://localhost:8080/user123 \
     -d '{"value": "Saurab", "ttl": 3600}'

Retrieve a value:

curl http://localhost:8080/user123

TCP Binary Protocol

For high-performance applications, use the TCP binary protocol (default port 9090). It uses a custom binary format for minimal overhead.

📡 Replication & Clusters

To start a cluster with replication:

# Node 1 (Leader)
./bin/server -node-id node1 -replication-addr :10001 -peers node2:10002 -quorum-size 2

# Node 2 (Follower)
./bin/server -node-id node2 -replication-addr :10002 -peers node1:10001 -quorum-size 2

📊 Monitoring

Metrics are exported in Prometheus format at http://localhost:2112/metrics.

Key metrics include:

• kvstore_memtable_size_bytes: Current size of the in-memory table.
• kvstore_sstable_count: Number of SSTables on disk.
• kvstore_operations_total: Total count of PUT/GET/DELETE operations.

🛠 Advanced Configuration

Flag	Default	Description
-data-dir	./data	Directory to store WAL and SSTables
-max-mem-size	10MB	Max size of MemTable before flushing
-http-addr	:8080	Address for the REST API
-tcp-addr	:9090	Address for the binary protocol
-metrics-addr	:2112	Address for Prometheus metrics

🧪 Testing

Run tests and benchmarks:

make test
make bench

📄 License

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