Consistent Hashing Simulator

A terminal-based Python simulator for exploring consistent hashing with virtual nodes and replica placement. It demonstrates how keys are distributed across a cluster of servers, how adding or removing a server affects ownership, and how replica servers are selected.

Features

• Consistent hashing over a configurable hash space
• Virtual nodes per server to improve distribution
• Replica placement based on successor virtual nodes
• In-memory storage for primary and replica key/value data
• Interactive command-line interface for simulating cluster operations

Project Overview

This project models a distributed key-value cluster using consistent hashing. Instead of mapping each server directly onto the hash ring, it uses virtual nodes so data is spread more evenly across the ring.

When a key is stored:

• its hash token is computed,
• the responsible server is determined from the ring,
• the key is stored on the primary server and on replica servers according to the configured replication factor.

Requirements

• Python 3.9+

Run the Simulator

From the project root, run:

python main.py

You will enter an interactive shell prompt:

Cluster>

Available Commands

Use help to view the available commands.

• help - Show command usage
• add-server <server-name> - Add a new server to the cluster
• remove-server <server-name> - Remove an existing server
• put <key> <value> - Store a key/value pair
• get <key> - Retrieve a value by key
• delete <key> - Delete a key
• show-cluster - Show cluster membership and storage summary
• show-ring - Display the hash ring contents
• show-server <server-name> - Show details for a specific server
• show-replica <key> - Show the replica chain for a key
• exit - Exit the simulator

Example Usage

Cluster> add-server server1
Cluster> add-server server2
Cluster> put user1 Alice
Cluster> get user1
Cluster> show-ring
Cluster> show-replica user1
Cluster> exit

Default Configuration

The simulator starts with the following defaults in main.py:

• Replication factor: 3
• Virtual nodes per server: 10
• Hash space: 1,000,000

Project Structure

.
├── cli/
│   ├── commands.py
│   ├── input_handler.py
│   └── shell.py
├── cluster/
│   ├── cluster_manager.py
│   ├── hash_ring.py
│   ├── hashing.py
│   ├── migration_manager.py
│   ├── replica_manager.py
│   └── virtual_node_generator.py
├── models/
│   ├── cluster_config.py
│   ├── key_value.py
│   ├── physical_server.py
│   └── virtual_node.py
├── storage/
│   └── memory_store.py
├── main.py

How It Works

1. A server is added to the cluster and assigned virtual nodes on the hash ring.
2. Keys are hashed to a token.
3. The token is mapped to the next server on the ring.
4. The key is stored on the primary server and on additional replica servers.
5. If a server is removed, data is rebalanced and ownership changes accordingly.

Notes

This project is intended as a learning and visualization tool for understanding consistent hashing, virtual nodes, and basic replication behavior in distributed systems.