Distributed Leader Election System with Redisson

A Java-based distributed leader election system using Redisson for Redis operations. This project demonstrates how to implement a robust leader election mechanism in distributed systems using Java 21 virtual threads and Redisson's distributed locks.

Features

• Distributed Leader Election: Multiple application instances compete for leadership using Redis distributed locks
• Task Processing: Leader nodes process tasks from a Redis blocking queue
• Automatic Failover: When the leader fails, other nodes automatically become the new leader after lock expiration
• Graceful Shutdown: Proper resource cleanup and lock release on application shutdown
• Java 21 Virtual Threads: Efficient concurrency handling using virtual threads
• Comprehensive Logging: Detailed logging for monitoring and debugging

Architecture

+----------------+     +------------------+
|   Application  |     |     Redis        |
|    Instance 1  |<--->|   (Redis Server) |
+----------------+     +------------------+
         |
         | (Distributed Lock)
         v
+----------------+     +------------------+
|   Application  |     |   Task Queue     |
|    Instance 2  |     |   (RBlockingQueue)|
+----------------+     +------------------+

Technology Stack

• JDK 21: Modern Java with virtual threads support
• Redisson 3.23+: Redis client library with distributed data structures
• Maven: Build automation tool
• SLF4J + Logback: Logging framework
• JUnit 5 + Mockito: Testing framework

Configuration

The application uses configuration properties that can be set via:

1. application.properties file in src/main/resources/
2. System properties
3. Environment variables

Redis Configuration

redis.address=localhost:6379
redis.password=
redis.timeout=5000
redis.connectionPoolSize=10
redis.connectionMinimumIdleSize=2

Leader Election Configuration

leader.lock.key=distributed:leader:lock
leader.lock.lease-time=30000
leader.lock.watchdog-timeout=10000

Task Queue Configuration

task.queue.name=distributed:task:queue
task.queue.timeout=5000

Running the Application

Prerequisites

• JDK 21 or higher
• Redis server running (default: localhost:6379)
• Maven 3.6+

Build and Run

# Clone the repository
git clone <repository-url>
cd taskreq-java

# Build the project
mvn clean compile

# Run the application
mvn exec:java -Dexec.mainClass="space.lambdadriver.Main"

Running with Custom Configuration

# Set custom Redis address
mvn exec:java -Dexec.mainClass="space.lambdadriver.Main" \
               -Dredis.address="your-redis-host:6379"

# Set custom lock key
mvn exec:java -Dexec.mainClass="space.lambdadriver.Main" \
               -Dleader.lock.key="custom:leader:lock"

Testing

Run unit tests:

mvn test

Run specific test classes:

mvn test -Dtest=SampleTaskProcessorTest
mvn test -Dtest=LeaderSelectorTest

Project Structure

src/
├── main/java/
│   └── space/lambdadriver/
│       ├── config/           # Configuration classes
│       │   └── RedissonConfig.java
│       ├── election/         # Leader election logic
│       │   └── LeaderSelector.java
│       ├── service/          # Task processing interface and implementations
│       │   ├── TaskProcessor.java
│       │   └── SampleTaskProcessor.java
│       └── Main.java         # Application entry point
├── main/resources/
│   └── application.properties
└── test/java/
    └── space/lambdadriver/
        ├── election/
        │   └── LeaderSelectorTest.java
        └── service/
            └── SampleTaskProcessorTest.java

Key Components

RedissonConfig

Singleton class that provides a configured RedissonClient instance for connecting to Redis.

LeaderSelector

Core component that handles:

• Distributed lock acquisition using Redisson
• Task processing while holding the lock
• Graceful failure handling and retry logic
• Automatic lock renewal via Redisson's watch dog

TaskProcessor Interface

Defines the contract for processing tasks from the queue.

SampleTaskProcessor

Example implementation that logs task details and simulates processing.

Leader Election Flow

1. Startup: Each application instance starts and creates a LeaderSelector
2. Lock Acquisition: Instances attempt to acquire a distributed lock
3. Leadership: The instance that successfully acquires the lock becomes the leader
4. Task Processing: Leader processes tasks from the Redis blocking queue
5. Lock Renewal: Redisson's watch dog automatically renews the lock during processing
6. Failure Detection: If the leader loses the lock (timeout/failure), it stops processing
7. Failover: Other instances detect the lost lock and compete for leadership again

Monitoring and Debugging

The application provides detailed logging at different levels:

• INFO: Startup, leadership changes, task processing
• DEBUG: Detailed operation information
• WARN: Potential issues
• ERROR: Critical failures

Log output includes:

• Leadership status changes
• Task processing details
• Lock acquisition/release events
• Error conditions and stack traces

Performance Considerations

• Uses Java 21 virtual threads for efficient concurrency
• Configurable connection pooling for Redis
• Non-blocking queue operations
• Automatic lock renewal prevents premature expiration
• Graceful degradation on network issues

Scalability

• Horizontal scaling by adding more application instances
• Redis cluster support through Redisson configuration
• Configurable lock timeouts and retry intervals
• Independent task processing per leader instance

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

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