Configuration

JoobQ provides various configuration options to tailor its behavior to your specific application needs. In this section, we will guide you through how to customize JoobQ, connect it to Redis, and configure job options.

The JoobQ.configure block allows you to:

1. Centralize Configuration: Define all your queues, schedules, and global settings in one place.

2. Optimize Performance: Set worker counts, job retries, and throttling to match your application's requirements.

3. Enhance Flexibility: Schedule jobs using cron patterns or time intervals, and integrate custom middlewares to extend functionality.

4. Improve Reliability: Enable retries, dead-letter queues, and expiration settings to ensure jobs are processed and errors are handled gracefully.

5. Monitor and Control: Enable optional features like REST APIs and statistics tracking for better system visibility.

Key Features of JoobQ Configuration

• Queue Management: Define multiple queues with specific worker counts and job types.

• Job Scheduling: Schedule tasks with precision using cron expressions or periodic intervals.

• Global Customization: Set defaults for retries, timeouts, and job expiration.

• Extensibility: Add custom middlewares for advanced use cases.

• Resilience: Leverage throttling, retries, and dead-letter queues for fault tolerance.

Configuration Guide

This guide provides an overview of configuring JoobQ, a job queue system designed for the Crystal programming language. You will learn how to define queues, set up middlewares, schedule jobs, and customize various options to suit your needs.

---

Define Configuration

Use the JoobQ.configure block to set up your job queue system. This is where you define queues, schedule jobs, and set global options.

JoobQ.configure do |config|
  # Enable REST API for monitoring and management
  config.rest_api_enabled = true

  # Define queues with their properties
  queue name: "queue:test", workers: 2, job: TestJob, throttle: nil
  queue name: "queue:fail", workers: 1, job: FailJob
  queue name: "queue:expire", workers: 1, job: ExpireJob

  # Define job schedulers
  scheduler do
    cron(pattern: "*/5 * * * * *") { puts "Every 5 seconds: #{Time.local}" }
    every(1.minute, TestJob, x: 1)
  end
end

---

Key Features and Configuration Options

1. Queues

Define queues to manage jobs. Each queue can be customized with:

• A name.

• The number of workers.

• The job class to process the tasks.

• Optional throttling limits.

Example:

queue name: "queue:my_queue", workers: 5, job: MyJob, throttle: { limit: 10, period: 1.minute }

Parameters:

• name - A unique string identifying the queue.

• workers - Number of worker threads to handle jobs in the queue.

• job - The job class responsible for processing tasks.

• throttle (optional) - Limits the number of tasks processed per period.

---

2. Scheduling Jobs

Jobs can be scheduled using either cron expressions or time intervals.

Using cron:

scheduler do
  cron(pattern: "*/5 * * * * *") { puts "Runs every 5 seconds" }
end

Using every:

scheduler do
  every(10.seconds, MyJob, some_param: "value")
end

---

3. Global Settings

JoobQ provides several global configuration options:

Option	Default Value	Description
time_location	Time::Location.load("America/New_York")	Globally sets the default timezone for JoobQ
rest_api_enabled	false	Enables REST API for queue management.
stats_enabled	true	Enables gathering of queue statistics.
default_queue	"default"	Name of the default queue.
retries	3	Number of retries for failed jobs.
expires	3.days	Time before a queued job expires.
timeout	2.seconds	Timeout for job execution.
failed_ttl	3.milliseconds	Time to retain failed job logs.
dead_letter_ttl	7.days	Time to retain dead-letter jobs.

Example:

JoobQ.configure do |config|
  config.rest_api_enabled = true
  config.default_queue = "high_priority"
  config.retries = 5
end

---

4. Middlewares

JoobQ supports middlewares to modify job execution behavior. Middlewares are applied in the following order:

1. Throttle - Limits job execution rate.

2. Retry - Handles job retries on failure.

3. Timeout - Enforces execution time limits.

Adding Custom Middleware:

JoobQ.configure do |config|
  config.use do |middlewares|
    middlewares << MyCustomMiddleware.new
  end
end

---

5. Time Location

You can set the global time location for scheduling jobs. By default, it uses "America/New_York".

Example:

JoobQ.configure do |config|
  config.time_location = Time::Location.load("America/New_York")
end

---

Example: Full Configuration

Below is a complete example of a JoobQ configuration:

JoobQ.configure do |config|
  config.rest_api_enabled = true
  config.stats_enabled = true
  config.default_queue = "default"
  config.retries = 3
  config.time_location = Time::Location.load("America/New_York")

  # Define queues
  queue name: "queue:email", workers: 3, job: EmailJob, throttle: { limit: 20, period: 1.minute }
  queue name: "queue:report", workers: 2, job: ReportJob

  # Define schedulers
  scheduler do
    cron(pattern: "0 * * * * *") { puts "Hourly task: #{Time.local}" }
    every(1.day, CleanupJob)
  end
end

---

Conclusion

Configuring JoobQ properly allows you to fine-tune its performance, reliability, and responsiveness according to your application’s needs. Now that you understand configuration, let’s dive into some Advanced Features that JoobQ has to offer!