Creating Custom Conflict Strategies

Relevant source files

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

• lib/sidekiq_unique_jobs/on_conflict/strategy.rb
• lib/sidekiq_unique_jobs/config.rb
• lib/sidekiq_unique_jobs/on_conflict.rb
• lib/sidekiq_unique_jobs/on_conflict/null_strategy.rb
• spec/sidekiq_unique_jobs/configuration_spec.rb
• spec/sidekiq_unique_jobs/on_conflict/strategy_spec.rb
• CLAUDE.md

Custom conflict strategies in sidekiq-unique-jobs allow developers to define specific behaviors when a job fails to acquire a unique lock. This mechanism handles scenarios where a duplicate job is either enqueued (client-side) or attempted for execution (server-side) while a lock is already held. The system is built on an abstract base class, providing access to job data, logging, and Redis communication.

By implementing the SidekiqUniqueJobs::OnConflict::Strategy interface, developers can extend the gem's default behaviors—such as logging, raising errors, or rescheduling—with domain-specific logic.

Sources: lib/sidekiq_unique_jobs/on_conflict/strategy.rb, CLAUDE.md:65-72

Core Architecture

The conflict resolution system utilizes a strategy pattern. The SidekiqUniqueJobs::OnConflict module acts as a factory to find and instantiate the appropriate strategy based on the job configuration.

The Strategy Base Class

All conflict strategies must inherit from SidekiqUniqueJobs::OnConflict::Strategy. This abstract class provides the necessary context for handling conflicts:

• item: A hash containing the Sidekiq job data (e.g., jid, class, args, lock_digest).
• redis_pool: The Redis connection pool for executing atomic operations if needed.
• Mixins: Inherits JSON, Logging, Script::Caller, and Timing utilities.

Sources: lib/sidekiq_unique_jobs/on_conflict/strategy.rb:11-37, CLAUDE.md:72

Default Strategy Registry

The gem provides several built-in strategies that serve as references for custom implementations:

Strategy	Behavior
log	Logs the conflict occurrence.
raise	Raises a SidekiqUniqueJobs::Conflict error.
reject	Rejects the job, typically sending it to the Dead Set.
replace	Deletes the existing job/lock and allows the new one.
reschedule	Delays the job for later execution.
null	A NOOP strategy that does nothing.

Sources: lib/sidekiq_unique_jobs/config.rb:91-97, lib/sidekiq_unique_jobs/on_conflict/null_strategy.rb

Implementing a Custom Strategy

To create a custom strategy, you must define a class that inherits from SidekiqUniqueJobs::OnConflict::Strategy and implements the call method.

module CustomStrategies
  class MyUniqueConflict < SidekiqUniqueJobs::OnConflict::Strategy
    def call
      # Custom logic here
      # Access job data via @item
      log_info("Handling conflict for job #{@item['jid']}")
    end
  end
end

Sources: lib/sidekiq_unique_jobs/on_conflict/strategy.rb:39-42, spec/sidekiq_unique_jobs/configuration_spec.rb:21-27

Conflict Resolution Flow

The following diagram illustrates how the middleware identifies a conflict and invokes the configured strategy.

The diagram shows the decision path when a job encounter a lock conflict, leading to the selection and execution of a strategy.
Sources: lib/sidekiq_unique_jobs/on_conflict.rb:24-37, spec/sidekiq_unique_jobs/configuration_spec.rb:5-9

Registering Custom Strategies

Once a custom strategy class is defined, it must be registered within the SidekiqUniqueJobs configuration.

Global Registration

Use the add_strategy method within the configuration block to make the strategy available globally via a symbol.

SidekiqUniqueJobs.configure do |config|
  config.add_strategy :my_custom_handler, CustomStrategies::MyUniqueConflict
end

Sources: lib/sidekiq_unique_jobs/config.rb:275-283, spec/sidekiq_unique_jobs/configuration_spec.rb:53-57

Worker-Specific Configuration

After registration, the strategy can be applied to specific Sidekiq workers using the sidekiq_options hash.

class MyWorker
  include Sidekiq::Job
  sidekiq_options lock: :until_executed,
                  on_conflict: :my_custom_handler
end

Sources: CLAUDE.md:88-96, spec/sidekiq_unique_jobs/configuration_spec.rb:13-17

Architecture Relationships

The following class diagram represents the relationship between the configuration, the strategy factory, and the custom implementations.

This diagram visualizes the inheritance hierarchy and how the configuration manages strategy classes.
Sources: lib/sidekiq_unique_jobs/config.rb:89-99, lib/sidekiq_unique_jobs/on_conflict.rb:15-38, lib/sidekiq_unique_jobs/on_conflict/strategy.rb:11-15

Summary

Creating custom conflict strategies involves extending the base Strategy class and implementing the call method. These strategies are registered via SidekiqUniqueJobs.config.add_strategy, allowing them to be referenced by name in worker options. This architecture provides a clean separation between uniqueness locking logic and the resulting behavior when duplicates occur.

Sources: lib/sidekiq_unique_jobs/on_conflict.rb, lib/sidekiq_unique_jobs/config.rb:275-283