Custom Lock Arguments
Relevant source files
The following files were used as context for generating this wiki page:
Custom Lock Arguments allow developers to define exactly which subset of a job's parameters should be used to determine its uniqueness. By default, the gem generates a unique digest based on the worker class, the queue, and all provided arguments. However, in scenarios where jobs contain transient data (like timestamps) that shouldn't impact uniqueness, custom lock arguments provide the necessary filtering mechanism.
This system ensures that only the relevant business logic parameters are evaluated when checking for duplicate jobs in Redis. This is primarily handled via the lock_args_method configuration or by defining a specific method within the worker class itself.
Sources: README.md:126-138, CLAUDE.md:104-106
Architecture and Data Flow
The processing of custom lock arguments occurs during the job preparation phase, before the lock is attempted in Redis. The SidekiqUniqueJobs::LockArgs class is responsible for determining if filtering is enabled and executing the filter logic against the raw job arguments.
The diagram above shows how job arguments are transformed into filtered arguments before digest generation.
Sources: lib/sidekiq_unique_jobs/lock_args.rb, spec/sidekiq_unique_jobs/lock_args_spec.rb:71-100
Filtering Mechanisms
There are three primary ways to implement custom lock arguments in a Sidekiq worker.
1. Using a Proc
A Proc can be passed to the lock_args_method option in sidekiq_options. This is useful for simple transformations or when you want to define the logic inline.
sidekiq_options lock: :until_executed,
lock_args_method: ->(args) { [args.first] }
Sources: README.md:129-132, spec/sidekiq_unique_jobs/lock_args_spec.rb:81-87
2. Using a Worker Class Method
If a symbol is provided to lock_args_method, the gem looks for a class method with that name on the worker. By default, if the worker implements self.lock_args(args), it will be used.
Sources: CLAUDE.md:104-106, spec/sidekiq_unique_jobs/lock_args_spec.rb:93-100
3. Global Configuration
Uniqueness filtering can also be configured globally via Sidekiq.default_job_options, which affects all workers unless overridden locally.
Sources: spec/sidekiq_unique_jobs/lock_args_spec.rb:88-91
Key Components and Logic
| Component | Responsibility |
|---|---|
SidekiqUniqueJobs::LockArgs | Main class that orchestrates the filtering of job arguments. |
filtered_args | The method that returns the subset of arguments used for the lock digest. |
lock_args_method | The configuration key identifying the filter (Proc or Symbol). |
InvalidUniqueArguments | Exception raised when a worker's lock method signature does not match the passed arguments. |
Sources: lib/sidekiq_unique_jobs/lock_args.rb, spec/sidekiq_unique_jobs/lock_args_spec.rb:104-120
The Lock Digest Relationship
The filtered arguments are a critical input for the SidekiqUniqueJobs::LockDigest. The digest calculation uses the output of the filtering process to create the final Redis key. If unique_across_queues or unique_across_workers is set to true, the digestable hash is further modified to exclude the queue or class name respectively, but the filtered arguments remain the core of the uniqueness check.
Implementation Details
The following implementation highlights how the gem resolves which arguments to use. If no custom method is found or enabled, it defaults to the full set of arguments.
# From lib/sidekiq_unique_jobs/lock_args.rb:40
def filtered_args
return args if lock_args_method.nil?
case lock_args_method
when Proc
filter_by_proc(args)
when Symbol
filter_by_symbol(args)
else
args
end
end
Sources: lib/sidekiq_unique_jobs/lock_args.rb:40-52
When filtering by symbol, the gem checks if the job_class responds to that specific method. If it does not, it falls back to the original arguments to avoid breaking job enqueuing.
Sources: lib/sidekiq_unique_jobs/lock_args.rb:75-80, spec/sidekiq_unique_jobs/lock_args_spec.rb:147-152
Conclusion
Custom Lock Arguments provide the granular control necessary to manage uniqueness in complex background processing environments. By allowing developers to exclude transient data from the lock digest, the system prevents "false positive" uniqueness conflicts while ensuring that truly identical jobs are correctly identified and handled according to the configured conflict strategy.
Sources: README.md:126-138, CLAUDE.md:188-190