Replicated Chat Infrastructure

Project for the Distributed Systems exam at Politecnico di Milano.

Replicated Chat Infrastructure is a fault-tolerant chat system built around a cluster of replicated brokers. Brokers communicate on the same LAN through UDP broadcast, coordinate leader election and message replication, and expose TCP endpoints that clients can use to join the chat.

The system provides a single globally ordered chat stream across all connected clients. Each accepted client message is assigned a global sequence number by the current leader and replicated to the broker cluster before it is delivered.

---

Features

• Broker replication: multiple brokers cooperate to keep the chat stream available after broker failures.
• Leader-based sequencing: one broker acts as leader and assigns global sequence numbers to client messages.
• Total and causal ordering: delivered messages follow the same global order for every client.
• Failure detection: brokers exchange heartbeats and start an election when the leader is no longer reachable.
• Client recovery: clients can reconnect to another broker and request missing messages when a failure interrupts delivery.
• Retransmission support: brokers and clients track acknowledgements and retry undelivered messages when needed.

---

Architecture

The project is split into two main components.

The diagram shows the main communication channels: brokers coordinate inside the LAN through UDP broadcast on port 3500, while clients connect to brokers through TCP ports starting from 2000.

Brokers

Brokers are the replicated core of the system.

• Use UDP broadcast on the LAN to discover peers, exchange heartbeats, and coordinate elections.
• Listen for client connections over TCP.
• Forward client messages to the leader when they are received by a follower.
• Replicate sequenced messages to the broker cluster.
• Keep an in-memory message cache used for retransmission and recovery.

Each broker has a numeric identifier. Its client TCP port is computed as:

2000 + broker_id

For example, broker 0 listens on port 2000, broker 1 on port 2001, and so on.

Clients

Clients connect to one available broker through TCP.

• Read the list of available brokers from brokers.txt.
• Send chat messages to the connected broker.
• Track expected global sequence numbers.
• Detect missing messages and request retransmission.
• Reconnect to another broker if the current connection fails.

---

Assumptions

• Crash-recovery model: clients, brokers, and network links may fail and recover.
• No Byzantine behavior: nodes may crash or stop responding, but they do not behave maliciously.
• No LAN partitions: the LAN may lose packets or introduce latency, but it does not split into isolated broker groups.
• In-memory storage: brokers do not persist chat history to disk. Recovery relies on the in-memory message cache.
• Real-time delivery: clients receive messages while they are connected to the infrastructure.

---

Requirements

• Java 17 or newer
• Maven
• A LAN broadcast address for broker-to-broker communication

---

Build

From the project root, run:

mvn clean package

Maven creates the executable fat JAR at:

target/ds-project-1.0-SNAPSHOT-jar-with-dependencies.jar

---

Configuration

Broker Broadcast Address

run_broker.sh contains the LAN broadcast address used by brokers:

INPUT1=10.169.223.255

Update this value if your network uses a different broadcast address, for example:

INPUT1=192.168.1.255

Client Broker List

Clients read broker endpoints from brokers.txt. The file must contain one host:port entry per line:

# List of available brokers (ip:port)
# The client will connect to the first one that responds.
localhost:2000
localhost:2001
localhost:2002
localhost:2003

Blank lines and lines starting with # are ignored.

---

Running the System

Start Brokers

Run one terminal per broker:

bash run_broker.sh <broker_id>

Examples:

bash run_broker.sh 0
bash run_broker.sh 1
bash run_broker.sh 2

The script builds the JAR automatically if it is missing, then starts:

java -cp target/ds-project-1.0-SNAPSHOT-jar-with-dependencies.jar org.example.broker.Broker <broadcast_ip> <broker_id>

Start a Client

Run:

bash run_client.sh

Or start it manually:

java -cp target/ds-project-1.0-SNAPSHOT-jar-with-dependencies.jar org.example.StartClient

On startup, the client loads brokers.txt, connects to the first reachable broker, and starts sending and receiving ordered chat messages.

---

License

Source code is licensed under the MIT License. See LICENSE for details.

Images and third-party logos remain property of their respective owners.