Global Configuration Options

Relevant source files

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

• lib/sidekiq_unique_jobs/config.rb
• lib/sidekiq_unique_jobs/sidekiq_unique_jobs.rb
• lib/sidekiq_unique_jobs/options_with_fallback.rb
• CLAUDE.md
• README.md
• lib/sidekiq_unique_jobs/logging.rb

Global configuration in sidekiq-unique-jobs provides a centralized mechanism to control the behavior of job uniqueness, locking strategies, and administrative tasks like orphan cleanup across an entire Sidekiq ecosystem. It utilizes a thread-safe structure to ensure consistency in multi-threaded environments, such as Sidekiq server processes.

The configuration system serves as a baseline for all workers, though many settings can be overridden at the individual worker level using sidekiq_options. This hierarchy allows developers to define sane defaults for the whole application while maintaining granularity for specific high-traffic or long-running jobs.

Sources: lib/sidekiq_unique_jobs/config.rb:7-22, README.md:121-135

Core Configuration Architecture

The configuration is managed by the SidekiqUniqueJobs::Config class, which inherits from a Concurrent::MutableStruct. This ensures that configuration updates are thread-safe. The system supports a variety of parameters ranging from lock timeouts to specialized reaper settings for cleaning up stale Redis keys.

Configuration Lifecycle

The configuration can be manipulated through several module-level methods in SidekiqUniqueJobs.

• SidekiqUniqueJobs.configure: Used to set global options, typically within a Sidekiq initializer.
• SidekiqUniqueJobs.use_config: Allows temporary configuration changes within a block, reverting to previous settings automatically after the block executes.
• SidekiqUniqueJobs.reset!: Resets the configuration to its default state and shuts down internal executors.

Sources: lib/sidekiq_unique_jobs/sidekiq_unique_jobs.rb:14-150, lib/sidekiq_unique_jobs/config.rb:27-31

Data Flow for Options Resolution

When a job is processed, the system resolves configuration using a fallback mechanism. It checks worker-specific options first, then falls back to global defaults.

This flow ensures that specific job requirements take precedence over general settings.
Sources: lib/sidekiq_unique_jobs/options_with_fallback.rb

Global Option Parameters

The following table summarizes the primary global configuration options available in SidekiqUniqueJobs::Config.

Option	Type	Default	Description
enabled	Boolean	true	Globally enable or disable uniqueness checks.
lock_timeout	Integer	0	Default seconds to wait for a lock (0 means no waiting).
lock_ttl	Integer/Nil	nil	Default expiration for locks in seconds.
lock_prefix	String	"uniquejobs"	The prefix used for all Redis keys created by the gem.
logger_enabled	Boolean	true	Enables or disables internal gem logging.
digest_algorithm	Symbol	:legacy	Algorithm for unique digest (:legacy MD5 or :modern SHA-3).
max_history	Integer	1000	Maximum number of entries kept in the changelog (if enabled).
lock_info	Boolean	false	If true, stores metadata about the lock in Redis for debugging.

Sources: lib/sidekiq_unique_jobs/config.rb:104-148, README.md:121-135

Lock and Strategy Management

The gem allows for the extension of its core capabilities by registering custom lock types and conflict strategies.

Available Lock Mappings

The configuration maintains pre-defined maps of available locks categorized by their lifecycle phase:

• LOCKS_WHILE_ENQUEUED: Includes :until_executing and :while_enqueued.
• LOCKS_FROM_PUSH_TO_PROCESSED: Includes :until_executed, :until_completed, and :until_and_while_executing.
• LOCKS_WHEN_BUSY: Includes :while_executing and :while_executing_reject.

Custom Extensions

Developers can inject custom logic using the following methods:

• add_lock(name, klass): Registers a new lock class. It raises a DuplicateLock error if the name is already taken.
• add_strategy(name, klass): Registers a new conflict resolution strategy. It raises a DuplicateStrategy error if the name is already taken.

Sources: lib/sidekiq_unique_jobs/config.rb:39-86, lib/sidekiq_unique_jobs/config.rb:250-282

Reaper Configuration

The "Reaper" is a background process responsible for cleaning up orphaned locks in Redis (locks that weren't released due to process crashes).

The reaper can be configured to use different implementations. While :lua is faster, :ruby is the default for safety.

Option	Default	Description
reaper	:ruby	The implementation type (:ruby, :lua, or :none).
reaper_count	1000	Maximum number of orphans to process in one run.
reaper_interval	600	Frequency of reaper runs in seconds.
reaper_timeout	10	Maximum execution time allowed for a reaper cycle.

Sources: lib/sidekiq_unique_jobs/config.rb:127-142, CLAUDE.md:88-93

Logging Configuration

The logging system integrates with Sidekiq's logger but provides specific toggles and context management.

• Contextual Logging: The SidekiqUniqueJobs::Logging module attempts to detect the environment (Sidekiq 8+, older Sidekiq, or generic) to provide structured logging contexts using Sidekiq::Context.with.
• Toggle: config.logger_enabled can be used to silence all gem-specific logs without affecting the main Sidekiq logs.

Sources: lib/sidekiq_unique_jobs/logging.rb:17-147, spec/sidekiq_unique_jobs/logging_spec.rb:31-40

Internal Resource Management

Locksmith Executor

The gem uses a thread pool for Locksmith operations to prevent unbounded thread growth.

• Default Pool: A Concurrent::ThreadPoolExecutor with a range of 1 to 50 threads and a queue size of 100.
• Customization: Users can provide their own locksmith_executor by setting it in the configuration.
• Shutdown: SidekiqUniqueJobs.reset! calls shutdown_executor to cleanly terminate these background threads.

Sources: lib/sidekiq_unique_jobs/config.rb:304-338, lib/sidekiq_unique_jobs/sidekiq_unique_jobs.rb:104-107

Redis Versioning

Certain features (like LMOVE support in Sidekiq 8+) depend on the Redis version. The configuration includes a thread-safe redis_version fetcher that uses a mutex and double-check locking to memoize the version string (e.g., "6.2.0") after the first fetch.

Sources: lib/sidekiq_unique_jobs/config.rb:347-362, lib/sidekiq_unique_jobs/sidekiq_unique_jobs.rb:166-168