diff options
| author | Paul Buetow <paul@buetow.org> | 2025-06-22 16:45:17 +0300 |
|---|---|---|
| committer | Paul Buetow <paul@buetow.org> | 2025-06-22 16:45:17 +0300 |
| commit | 4c16cc3c4da7bbf8375d7951185db1761eb396bf (patch) | |
| tree | 19199b664ce802ed3e967e318e6d4ffeb8c9bf39 /docs | |
| parent | 464df52901e2dcb84eb81a22f2db19cbf17e5a9f (diff) | |
Remove all Raft protocol code
Removed all Raft-related code as it was not working properly:
- Removed VSRaftProtocol.java implementation
- Removed all Raft test files
- Removed Raft example/demo files
- Removed Raft documentation
- Removed Raft simulation files (.dat)
- Removed Raft scripts
- Updated VSRegisteredEvents to remove Raft registration
- Updated SimulationBuilder to remove RAFT constant
- Updated SimulationFactory to remove Raft methods
- Updated SimulationBuilderTest to remove Raft tests
- Updated pom.xml to remove Raft test configurations
The protocol had issues with leader election not completing in GUI mode.
🤖 Generated with Claude Code
https://claude.ai/code
Co-Authored-By: Claude <noreply@anthropic.com>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/creating-raft-simulation.md | 99 | ||||
| -rw-r--r-- | docs/raft-simulation-status.md | 115 |
2 files changed, 0 insertions, 214 deletions
diff --git a/docs/creating-raft-simulation.md b/docs/creating-raft-simulation.md deleted file mode 100644 index d3fb9ab..0000000 --- a/docs/creating-raft-simulation.md +++ /dev/null @@ -1,99 +0,0 @@ -# Creating a Raft Consensus Simulation - -This guide explains how to create a working Raft consensus simulation in DS-Sim. - -## Overview - -The Raft protocol implementation in DS-Sim demonstrates: -- Leader election with randomized timeouts -- Heartbeat messages from leader to followers -- Vote requests and responses -- Term management -- Log replication (basic implementation) - -## Creating the Simulation via GUI - -1. **Start DS-Sim**: - ```bash - java -jar target/ds-sim-1.0.1-SNAPSHOT.jar - ``` - -2. **Add Processes**: - - Click "Add Process" button 3 times to create 3 nodes - - This creates the minimum cluster size for consensus - -3. **Configure Each Process as Raft Server**: - - Right-click on Process 1 - - Select "Protocols" → "Raft Consensus Algorithm" → "Server" - - Repeat for Process 2 and Process 3 - -4. **Set Simulation Duration**: - - Go to Edit → Preferences → Simulator - - Set "Simulation duration" to 15 seconds - - This gives enough time to see leader election - -5. **Save the Simulation**: - - File → Save As - - Save as `saved-simulations/raft.dat` - -6. **Run the Simulation**: - - Click the "Play" button - - Watch the message exchanges and leader election - -## Expected Behavior - -When you run the simulation: - -1. **Initial State** (0-300ms): - - All nodes start as FOLLOWERS - - Each sets a random election timeout (150-300ms) - -2. **Election Phase** (150-500ms): - - First node to timeout becomes CANDIDATE - - Sends REQUEST_VOTE messages to all nodes - - Other nodes respond with VOTE_RESPONSE - -3. **Leader Establishment** (300-600ms): - - Candidate with majority votes becomes LEADER - - Leader is highlighted in the visualization - - Starts sending APPEND_ENTRIES (heartbeats) - -4. **Steady State** (600ms+): - - Leader sends periodic heartbeats (every 50ms) - - Followers reset election timeout on heartbeat - - System remains stable with one leader - -## Testing the Simulation - -Run the simulation in headless mode: -```bash -java -cp target/classes:target/test-classes \ - -Djava.awt.headless=true \ - -Dds.sim.verbose=true \ - testing.HeadlessProtocolRunner saved-simulations/raft.dat -``` - -Expected output includes: -- "[FOLLOWER T:0 N:X] Raft node initialized as FOLLOWER" -- "[CANDIDATE T:1 N:X] Starting election for term 1" -- "Sending vote request to all nodes" -- "[FOLLOWER T:1 N:Y] Granted vote to node X for term 1" -- "[LEADER T:1 N:X] Elected as leader with Y votes" -- "Sending heartbeats to all followers" - -## Troubleshooting - -If leader election doesn't occur: -- Ensure all processes are configured as "Server" not "Client" -- Check that simulation duration is long enough (>5 seconds) -- Verify VSRaftProtocol has `setClassname()` in constructor - -## Implementation Notes - -The Raft protocol uses: -- `onServerStart()`: Initializes election timeout -- `onServerSchedule()`: Handles timeouts and periodic tasks -- `scheduleAt()`: Schedules future events -- `sendMessage()`: Broadcasts to all other nodes - -See `VSRaftProtocol.java` for full implementation details.
\ No newline at end of file diff --git a/docs/raft-simulation-status.md b/docs/raft-simulation-status.md deleted file mode 100644 index 146c11c..0000000 --- a/docs/raft-simulation-status.md +++ /dev/null @@ -1,115 +0,0 @@ -# Raft Simulation Status Report - -## Completed Tasks - -### 1. Raft Protocol Documentation ✓ -- Created comprehensive documentation at `/docs/raft-consensus-protocol.md` -- Includes detailed explanations of: - - Leader election process - - Log replication mechanism - - Safety properties - - ASCII diagrams for visualization - - Implementation notes for DS-Sim - -### 2. Raft Protocol Implementation ✓ -- Successfully implemented in `VSRaftProtocol.java` -- Features include: - - Leader election with randomized timeouts - - Heartbeat mechanism - - Log replication - - Client request handling - - Crash recovery support - -### 3. Simulation Creation ✓ -- Created multiple simulation files: - - `saved-simulations/raft-working.dat` - Full working simulation - - `saved-simulations/raft-consensus.dat` - Basic consensus demo - - `saved-simulations/raft-simple.dat` - Simple example - - `saved-simulations/raft-verified.dat` - Verification attempt - -### 4. Example Programs ✓ -- `CreateWorkingRaftSimulation.java` - Creates a comprehensive Raft simulation -- `CreateAndVerifyRaftSimulation.java` - Creates and attempts to verify -- `CreateMinimalRaftSimulation.java` - Minimal test case -- `TestRaftLoading.java` - Verifies Raft protocol registration - -## Current Issue - -### Protocol Deserialization Error -When loading saved simulations, the following error occurs: -``` -java.lang.NullPointerException: Cannot invoke "protocols.VSAbstractProtocol.deserialize()" -because "protocol" is null -``` - -### Root Cause Analysis -1. The serialization process saves ALL protocols that have been instantiated on a process -2. During deserialization, it tries to recreate these protocol instances -3. Some protocols may not have been properly initialized or registered -4. The error suggests that a protocol classname is null or empty during deserialization - -### Workaround -Despite the deserialization error, the simulation files are created successfully and contain: -- 5 processes (3 servers, 2 clients) -- Raft protocol activations scheduled at appropriate times -- Crash/recovery events for testing fault tolerance - -## How to Use the Raft Simulation - -1. **Run the simulator GUI:** - ```bash - java -jar target/ds-sim-1.0.1-SNAPSHOT.jar - ``` - -2. **Load the simulation:** - - File → Open → `saved-simulations/raft-working.dat` - - Note: You may see deserialization warnings, but the simulation should still load - -3. **Run the simulation:** - - Click the Run (▶) button - - Watch for: - - Leader election messages (REQUEST_VOTE, VOTE_RESPONSE) - - Heartbeats from the leader (APPEND_ENTRIES) - - Client requests and responses - - Re-election when servers crash - -## Testing Framework - -### Attempted Approaches -1. **GUI Testing Framework** - Created test classes to verify simulation behavior -2. **Integration Tests** - Direct testing without GUI -3. **Verification Programs** - Standalone verification utilities - -### Current Status -The testing frameworks encounter compilation issues due to: -- Private field access requirements -- Missing or changed API methods -- Type compatibility issues - -## Recommendations - -1. **For immediate use:** The created simulations should work when loaded in the GUI despite the warnings -2. **For fixing deserialization:** Investigate why some protocols have null classnames during save/load -3. **For testing:** Consider using the GUI directly to verify behavior rather than automated tests - -## Files Created - -### Documentation -- `/docs/raft-consensus-protocol.md` - Complete Raft protocol documentation -- `/docs/raft-simulation-status.md` - This status report -- `/saved-simulations/README-raft.txt` - User instructions - -### Source Code -- `/src/main/java/examples/CreateWorkingRaftSimulation.java` -- `/src/main/java/examples/CreateAndVerifyRaftSimulation.java` -- `/src/main/java/examples/CreateMinimalRaftSimulation.java` -- `/src/main/java/examples/TestRaftLoading.java` - -### Simulation Files -- `/saved-simulations/raft-working.dat` -- `/saved-simulations/raft-consensus.dat` -- `/saved-simulations/raft-simple.dat` -- `/saved-simulations/raft-verified.dat` - -### Test Files -- `/src/test/java/simulator/SimpleRaftGUITest.java`
\ No newline at end of file |
