Installation & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• lib/sidekiq_unique_jobs/sidekiq_unique_jobs.rb
• spec/spec_helper.rb
• lib/sidekiq_unique_jobs/constants.rb
• lib/sidekiq_unique_jobs/web/helpers.rb

Installation & Setup covers the necessary steps to integrate the sidekiq-unique-jobs gem into a Ruby application. This process involves meeting system requirements, configuring Sidekiq middleware, and defining global or per-worker settings to ensure job uniqueness.

The gem acts as a middleware layer for both Sidekiq clients (pushing jobs) and servers (executing jobs). It leverages Redis to maintain locks based on job digests, preventing duplicate entries or concurrent executions according to the specified lock type.

Sources: README.md:14-25, CLAUDE.md:12-23

System Requirements

Before installation, ensure the environment meets the following minimum version requirements:

• Ruby: >= 3.2
• Sidekiq: >= 8.0
• Redis: >= 6.2 (required for LMOVE support used in reliable fetching)

Sources: README.md:18-21

Dependency Installation

To add the gem to your project, include it in your Gemfile:

gem "sidekiq-unique-jobs", "~> 9.0"

Sources: README.md:25

Middleware Configuration

The gem requires manual registration of middleware in the Sidekiq initializer. This setup ensures that the unique job logic intercepts both the enqueuing process (Client) and the execution process (Server).

Initialization Flow

The following diagram illustrates how the middleware is integrated into the Sidekiq lifecycle:

Configuration Example

A standard initializer (e.g., config/initializers/sidekiq.rb) should include both client and server configurations:

Sidekiq.configure_client do |config|
  config.client_middleware do |chain|
    chain.add SidekiqUniqueJobs::Middleware::Client
  end
end

Sidekiq.configure_server do |config|
  config.client_middleware do |chain|
    chain.add SidekiqUniqueJobs::Middleware::Client
  end

  config.server_middleware do |chain|
    chain.add SidekiqUniqueJobs::Middleware::Server
  end

  SidekiqUniqueJobs::Server.configure(config)
end

Sources: README.md:27-44, spec/spec_helper.rb:45-63

Global Configuration Options

Global settings are managed via the SidekiqUniqueJobs.configure block. These values serve as defaults unless overridden in specific workers.

Option	Type	Default	Description
enabled	Boolean	true	Globally enable or disable uniqueness checks.
lock_ttl	Integer	nil	Default expiration for locks in seconds.
lock_timeout	Integer	0	Seconds to wait for a lock (0 means immediate fail).
lock_prefix	String	"uniquejobs"	Prefix for Redis keys used for locking.
reaper	Symbol	:ruby	Strategy for cleaning orphaned locks (:ruby, :lua, :none).
digest_algorithm	Symbol	:legacy	Algorithm for digest generation (:legacy MD5, :modern SHA3).

Sources: README.md:73-85, lib/sidekiq_unique_jobs/sidekiq_unique_jobs.rb:162-171, spec/sidekiq_unique_jobs/sidekiq_unique_jobs_spec.rb:8-11

Worker-Level Setup

To enable uniqueness for a specific job, include Sidekiq::Job and define sidekiq_options.

Basic Implementation

class MyJob
  include Sidekiq::Job
  sidekiq_options lock: :until_executed
  
  def perform(args)
    # logic
  end
end

Configuration Keys

Workers support several specific keys within sidekiq_options:

• lock: The strategy to use (e.g., :until_executing, :while_executing).
• on_conflict: The strategy to handle duplicates (e.g., :log, :raise, :reschedule).
• lock_args_method: A proc or symbol for a method to filter which arguments determine uniqueness.
• unique_across_queues: Boolean to ignore the queue name in the digest.
• unique_across_workers: Boolean to ignore the worker class name in the digest.

Sources: README.md:46-56, CLAUDE.md:88-97, lib/sidekiq_unique_jobs/constants.rb:14-46

Web UI Integration

The gem provides a tab for the Sidekiq Web interface to monitor and manage locks. To enable it, add the following to your config/routes.rb:

require "sidekiq_unique_jobs/web"

This extension adds a "Locks" tab allowing administrators to view, filter, and delete active digests.

Sources: README.md:129-135, lib/sidekiq_unique_jobs/web/helpers.rb:13-18

Summary

Successful Installation & Setup requires adding the gem, configuring the Sidekiq middleware stack for both client and server, and defining the desired lock types in individual workers. By default, the gem uses Redis for lock management and provides a web interface for observability, ensuring that background job duplicates are handled according to the defined conflict strategies.