Rqueue | Redis-Backed Job Queue and Scheduler For Spring Framework

Rqueue is a Redis-backed job queue and producer-consumer system for Spring and Spring Boot. It supports both producers and consumers for background jobs, scheduled tasks, and event-driven workflows, similar to Sidekiq or Celery, while staying fully integrated with the Spring programming model through annotation-driven APIs and minimal setup.

Get started now View it on GitHub

Features

Job execution
- Run background jobs asynchronously
- Schedule jobs for any future time
- Run periodic jobs at fixed intervals
- Guarantee at-least-once delivery
- Retry failed jobs automatically with fixed or exponential backoff
- Disable retries for selected workloads when needed
Queues and routing
- Deduplicate messages using message IDs
- Process priority workloads such as high, medium, and low
- Prioritize workloads with group-level queue priority and weighted, strict, or hard strict ordering
- Fan out the same message to multiple listeners
- Poll messages in batches for higher throughput
Consumers and scale
- Use annotation-driven listeners with Spring beans
- Get started with just the dependency in Spring Boot applications
- Run multiple competing consumers in parallel
- Configure listener concurrency per worker
- Support long-running jobs with periodic check-ins
- Serialize and deserialize message payloads automatically
Operations and extensibility
- Add middleware before listener execution
- Use callbacks for dead-letter, discard, and related flows
- Subscribe to bootstrap and task execution events
- Monitor in-flight, queued, and scheduled messages with metrics
- Use the built-in web dashboard for queue visibility and monitoring
Redis and platform support
- Support Redis standalone, Sentinel, and Cluster setups
- Support reactive Redis and Spring WebFlux
- Keep Redis configuration flexible for different deployment models

Requirements

Spring 6+, 7+
Spring Boot 3+, 4+
Java 21+
Spring Reactive
Lettuce client for Redis cluster
Read master preference for Redis cluster

Getting Started

Queue names are dynamic. Manually creating queues with the registerQueue method may cause inconsistencies. Queues should only be created when using Rqueue as a producer.

Sample Applications

The Rqueue GitHub repository includes several sample applications for local testing and demonstration:

Project Integration

When configuring the Redis connection factory, set readFrom to MASTER_PREFERRED for Redis Cluster compatibility. Failure to do so may prevent the application from starting.

Spring Boot

Use Rqueue Spring Boot Starter 4.x for Spring Boot 4.x, and 3.x for Spring Boot 3.x.

Download the latest version from Maven Central and add the dependency to your project:

Spring Boot 4.x Setup

Gradle

implementation 'com.github.sonus21:rqueue-spring-boot-starter:4.0.0-RELEASE'

Maven

<dependency>
    <groupId>com.github.sonus21</groupId>
    <artifactId>rqueue-spring-boot-starter</artifactId>
    <version>4.0.0-RELEASE</version>
</dependency>

Spring Framework

Use Rqueue Spring 4.x for Spring Framework 7.x, and 3.x for Spring Framework 6.x.

Download the latest version from Maven Central and add the dependency to your project:

Spring Framework 7.x Setup

Gradle

implementation 'com.github.sonus21:rqueue-spring:4.0.0-RELEASE'

Maven

<dependency>
    <groupId>com.github.sonus21</groupId>
    <artifactId>rqueue-spring</artifactId>
    <version>4.0.0-RELEASE</version>
</dependency>

When using the Spring Framework, ensure you:

Add the @EnableRqueue annotation to your configuration class.
Define a RedisConnectionFactory bean.

Example Spring Application Configuration

@EnableRqueue
public class Application {
  @Bean
  public RedisConnectionFactory redisConnectionFactory() {
    // return a Redis connection factory
  }
}

Once Rqueue is configured, you can use its methods and annotations consistently across both Spring and Spring Boot environments.

Message Publishing / Task Submission

Submit tasks using the RqueueMessageEnqueuer bean. Use the enqueueXXX, enqueueInXXX, or enqueueAtXXX methods based on your requirements:

import com.github.sonus21.rqueue.core.RqueueMessageEnqueuer;

@Component
public class MessageService {
  @Autowired
  private RqueueMessageEnqueuer rqueueMessageEnqueuer;

  public void doSomething() {
    rqueueMessageEnqueuer.enqueue("simple-queue", "Rqueue is configured");
  }

  public void createJob(Job job) {
    rqueueMessageEnqueuer.enqueue("job-queue", job);
  }

  public void sendNotification(Notification notification) {
    rqueueMessageEnqueuer.enqueueIn("notification-queue", notification, 30 * 1000L);
  }

  public void createInvoice(Invoice invoice, Instant instant) {
    rqueueMessageEnqueuer.enqueueAt("invoice-queue", invoice, instant);
  }

  public void sendSms(Sms sms, SmsPriority priority) {
    rqueueMessageEnqueuer.enqueueWithPriority("sms-queue", priority.value(), sms);
  }

  public void sendPeriodicEmail(Email email) {
    rqueueMessageEnqueuer.enqueuePeriodic("email-queue", email, 30_000);
  }
}

Workers and Task Listeners

Annotate any public method of a Spring bean with @RqueueListener to create a message consumer:

import com.github.sonus21.rqueue.annotation.RqueueListener;
import com.github.sonus21.rqueue.listener.RqueueMessageHeaders;

@Component
@Slf4j
public class MessageListener {

  @RqueueListener(value = "simple-queue")
  public void handleSimpleMessage(String message) {
    log.info("Received message from simple-queue: {}", message);
  }

  @RqueueListener(value = "job-queue", numRetries = "3", deadLetterQueue = "failed-job-queue", concurrency = "5-10")
  public void handleJob(Job job) {
    log.info("Received job: {}", job);
  }

  @RqueueListener(value = "push-notification-queue", numRetries = "3", deadLetterQueue = "failed-notification-queue")
  public void handleNotification(Notification notification) {
    log.info("Received notification: {}", notification);
  }

  @RqueueListener(value = "sms", priority = "critical=10,high=8,medium=4,low=1")
  public void handleSms(Sms sms) {
    log.info("Received SMS: {}", sms);
  }

  @RqueueListener(value = "chat-indexing", priority = "20", priorityGroup = "chat")
  public void handleChatIndexing(ChatIndexing chatIndexing) {
    log.info("Received chat indexing message: {}", chatIndexing);
  }

  @RqueueListener(value = "chat-indexing-daily", priority = "10", priorityGroup = "chat")
  public void handleDailyChatIndexing(ChatIndexing chatIndexing) {


    log.info("Received daily chat indexing message: {}", chatIndexing);
  }
}

Notes:

Retry Mechanism: Configure retry behavior using numRetries and deadLetterQueue attributes.
Concurrency: Adjust concurrency using the concurrency attribute.
Priority: Set message priority using the priority attribute.

Advanced Configuration

Rqueue Configuration

For advanced configurations such as message serialization, queue properties, message listener details, and more, refer to the official documentation.

Support

For any issues, questions, or feature requests, please create an issue on the GitHub repository or contact the maintainers directly.

License

Rqueue is licensed under the Apache License 2.0. See the LICENSE file for more details.