How shahdhruv777/distributed_assignment1 works
Project Type and Purpose
• Type: A distributed, containerized load-balancing system implemented in Python.
• Purpose:
– Accept client requests via a client container.
– Use a multi-threaded load balancer container that maintains shards via consistent hashing, monitors servers via heartbeat, and routes requests.
– Dispatch read/write/update/delete requests to a dynamic pool of server containers.
– Persist metadata about shards and mappings in a database container.
File Structure
• Top-level Dockerfiles:
– Dockerfile_lb (load balancer)
– Dockerfile_server
– Dockerfile_client
– (plus dummy & lb variants)
• Python entry points:
– combined_lb.py, load_balancer_rehashed.py, new_lb.py → load-balancer logic
– server.py → server container logic
– client.py, scaled_client.py → client scripts
– Analysis*.py → benchmarking/analysis scripts
• Helpers and data structures:
– Datastructures.py, helper_functions.py, packages.py → core in-memory maps, mutexes, sorted containers
– drs.py, while.py, faltu.py → utility scripts
• Deployment scripts:
– initializer_script_lb, initializer_script_server
– Makefile targets to build/run images and containers
• Logs & tim-ings:
– lb_logs/, server*_logs/, AnalysisTimings
README Insights
• Docker orchestration: custom network “my_network”
• Three containers: client, load balancer (with embedded DB), servers
• Metadata class interacts with “ShardT” and “MapT” tables in the database
• Consistent hashing across shards, multi-threading, heartbeat detection, graceful server removal (20s timeout)
• Use of sorted-containers for O(log n) server lookups
Main Components & Their Interactions
a. Client Container
– Runs client.py or scaled_client.py
– Issues HTTP requests (e.g. /write, /read, /update, /del) to the load balancer
b. Load Balancer Container
– HTTP API endpoints: /add, /rm, /update, /del, /heartbeat
– ConsistentHashingEngine (uses Shard objects, serv_dict, serv_id_dict, cont_hash)
– MetadataModule (interacts with the metadata database tables)
– HeartbeatMonitor Thread (periodically pings servers; updates server pool)
– Docker initializer script sets up LB on “my_network”
c. Database Container (logical or embedded in LB)
– Holds ShardT and MapT tables
– Serves metadata queries and updates
d. Server Containers (multiple instances)
– server.py exposes endpoints to serve read/write/update/delete on its shard replicas
– Writes are committed across replicas then valid index updated
– Logs operations to server*_logs/
e. Docker Network (“my_network”)
– Virtual LAN connecting client, LB, database, server containers
Architectural Patterns and Principles
• Microservices via Docker containers for each role
• Consistent hashing for shard-to-server mapping
• Mutex locks to protect critical sections in Shard and Server class data structures
• Heartbeat pattern for failure detection and dynamic membership
• Graceful removal of servers with a TCP-like FIN timeout
• Use of sorted data structures for efficient nearest-server lookups (O(log n))
2. Load Balancer Container (large rectangle subdivided into:
• HTTP API Layer
• Consistent Hashing Engine (Shard + serv_dict + serv_id_dict)
• Heartbeat Monitor Thread)
3. Server Containers (multiple small rectangles, labeled server-1, server-2, …)
• Client → LB (HTTP requests)
• LB → Servers (routed requests, using consistent hashing)
• LB → DB (metadata reads/writes)
• LB → Servers (heartbeat pings)
– Optionally, show inter-server communication (none in this design) or back-end index updates.