Skip to content
CAI
Software that uses CAICheck a score

zoolutions/sidekiq-unique-jobs

39.7

Weak · 6 November 2026

12.1k

lines of production code

Ruby

primary language

4

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

This system is a Ruby gem that enforces uniqueness constraints on Sidekiq background jobs to prevent duplicate execution. It manages job locking through a modular architecture with multiple strategies, handling conflicts via configurable actions like rejecting, replacing, or rescheduling jobs. The library ensures reliability by preventing job loss during crashes and provides tools for monitoring active locks and cleaning up stale entries.

How it got here

2012–2015 — Architectural modernization and reliability

12 changes.

This period focused on a major architectural refactor to replace legacy middleware with a modular locking strategy and modern dependencies like concurrent-ruby. It introduced robust features such as reliable fetch mechanisms with atomic operations and batch deletion to prevent job loss. The work also included comprehensive test suite upgrades and development tooling to support the transition to Sidekiq 8 and Rails 8.

2018–2019 — Locking architecture and conflict strategies

25 changes.

This period focused on a comprehensive overhaul of the unique job locking mechanism, introducing explicit on-conflict strategies and refactoring the core middleware and Lua scripts for better performance and Sidekiq 8 compatibility. The work included rebuilding the Redis interaction layer, enhancing the web UI for lock management, and restoring the orphan reaper to prevent premature job deletion. Extensive test coverage was added to validate the new locking behaviors, conflict resolutions, and performance benchmarks.

2021–2026 — Release automation and test expansion

5 changes.

This period focused on automating the gem release process through a new Zoolutions-based rake task and significantly expanding test coverage. The work included adding integration tests for lock behavior under high latency, comprehensive tests for job fetch and lock validation logic, and support for testing against Sidekiq 8.0 and 8.1.

Features

Add RSpec matchers for Sidekiq worker validation

The library now provides RSpec matchers to help validate Sidekiq worker configuration. A new \matchers.rb\ file defines the \SidekiqUniqueJobs::RSpec::Matchers\ module and conditionally includes it in RSpec configurations only when RSpec is present. This enables users to use specific matchers, such as \have\_valid\_sidekiq\_options\, to test their workers' Sidekiq options during development.

_lib/sidekiq\_unique\jobs/rspec · high confidence

Added changelog generation task

A new Rake task named \changelog\ has been added to \lib/tasks/changelog.rake\. This task automates the generation of the project's changelog by checking out the main branch, running the \github\_changelog\_generator\ tool with the provided GitHub token, and committing the resulting changes. This provides a convenient way for maintainers to update the changelog without manually executing the generator command.

lib/tasks · high confidence

Added development and maintenance tooling scripts

The repository now includes a suite of new executable scripts in the \bin/\ directory to support development workflows. This includes a new \bin/uniquejobs\ CLI entry point, comprehensive benchmarking tools (\bin/benchmark\, \bin/benchmark\_improvements\, \bin/compare\_performance\, \bin/memory\_compare\, \bin/memory\_profile\) for measuring lock contention, throughput, and memory usage, and operational utilities such as \bin/release\ for version management and \bin/labels\ for synchronizing GitHub labels with the repository manifest.

bin · high confidence

Initial project scaffolding and configuration

This change introduces the foundational configuration files for the sidekiq-unique-jobs gem, including \.editorconfig\, \.rubocop.yml\, \.rspec\, \.simplecov\, and \Appraisals\ for testing against Sidekiq 8.0 and 8.1. It also adds documentation and tooling files such as \AGENTS.md\, \BENCHMARKING.md\, \RELEASING.md\, and \UPGRADING.md\, along with standard project files like \LICENSE.txt\ and \CODE\_OF\_CONDUCT.md\.

(repo-wide) · high confidence

Introduce reliable fetch strategy and batch deletion for unique locks

The gem now includes a new \SidekiqUniqueJobs::Fetch::Reliable\ fetcher that uses atomic LMOVE operations and per-process heartbeats to prevent job loss during crashes, recovering orphaned jobs on startup. Additionally, a \BatchDelete\ class has been added to efficiently remove multiple lock digests in batches via pipelined Redis commands, and a new CLI (\lib/sidekiq\_unique\_jobs/cli.rb\) provides commands to list and delete unique digests by pattern, including a dry-run mode.

_lib/sidekiq\_unique\jobs · high confidence

New Redis data-type wrapper classes

The library now includes dedicated wrapper classes for Redis data structures (Hash, List, Set, SortedSet, String) under the SidekiqUniqueJobs::Redis namespace. These classes provide a consistent, object-oriented interface for interacting with Redis keys, exposing methods like entries, count, and del, which simplifies how the library manages unique job locks and metadata in Redis.

_lib/sidekiq\_unique\jobs/redis · high confidence

New release automation task via Zoolutions release kit

A new \release.rake\ file has been added to the \rakelib\ directory, implementing the shared release workflow from the Zoolutions release kit. This introduces the \rake release\[version\]\ task, which automates the process of bumping the gem version, updating local lockfile pins, committing changes, pushing to the main branch, and publishing a GitHub Release (which triggers signing and RubyGems publishing via OIDC). The task supports pre-release flags and a force mode to re-create existing tags/releases, while enforcing that releases are only run from a clean main branch.

rakelib · high confidence

New web UI for monitoring and managing locks

The Sidekiq web interface now includes a dedicated Locks section, allowing users to view a list of active locks with details such as digest, type, holder count, and creation time. Users can filter the lock list, paginate through results, and inspect individual lock information including worker, queue, TTL, and locked job IDs. From this view, users can unlock specific jobs or delete all locks directly via the web interface.

_lib/sidekiq\_unique\jobs/web/views · high confidence

Removals

Removal of legacy unique jobs middleware

The \SidekiqUniqueJobs::Middleware::Server::UniqueJobs\ middleware class has been removed. This component previously handled uniqueness by deleting a Redis key (hashed from the job arguments) in the ensure block after job execution, a mechanism that is no longer part of the library's current architecture.

_lib/sidekiq\_unique\jobs/middleware/server · high confidence

Behavioural changes

Introduce dedicated client and server middleware classes for job locking

The library now uses explicit \SidekiqUniqueJobs::Middleware::Client\ and \SidekiqUniqueJobs::Middleware::Server\ classes to handle job uniqueness. The client middleware intercepts jobs before they are pushed to Sidekiq, acquiring a lock and yielding execution only if the lock is successfully obtained. The server middleware processes jobs on the worker side, delegating execution to the lock instance. This separation ensures that uniqueness checks are applied consistently at both the push and processing stages.

_lib/sidekiq\_unique\jobs/middleware · high confidence

Major architectural refactor and dependency update

The library has been significantly refactored to support a more modular and robust architecture. The main entry point now loads a comprehensive set of components, including new lock strategies (until\_executed, until\_executing, until\_expired, while\_executing, while\_executing\_reject, until\_and\_while\_executing), a new lock configuration system, and a reliable fetch mechanism. The old client middleware implementation has been removed, indicating a shift in how uniqueness is enforced. Additionally, the gem now explicitly depends on the \concurrent-ruby\ and \redis-client\ libraries, moving away from older or implicit dependencies.

lib · high confidence

New on-conflict strategies for handling unique job collisions

The library now provides explicit strategies for handling job conflicts, allowing users to define specific behaviors when a unique job lock is detected. New classes include \Log\ to simply record the conflict, \Raise\ to trigger a retry by throwing an error, \Reject\ to move conflicting jobs to the dead queue (with compatibility for different Sidekiq versions), \Replace\ to delete the existing job and lock before re-queuing, and \Reschedule\ to delay and re-execute the job while preventing infinite recursion. These strategies replace the previous implicit or less granular conflict handling mechanisms.

_lib/sidekiq\_unique\_jobs/on\conflict · high confidence

Redesigned Lua scripts for Sidekiq Unique Jobs with optimized lock lifecycle and recovery

The Lua scripts in lib/sidekiq\_unique\_jobs/lua have been rewritten to streamline the lock lifecycle, reduce Redis command overhead, and improve reliability. The new lock and unlock logic uses sorted sets for digest tracking with scores based on expiration time, enabling faster cleanup and preventing premature removal of lock information. A new ack script handles job acknowledgment with specific logic for different lock types, while a dedicated unlock script ensures primed keys are correctly removed. Additionally, a new recover script allows for the safe recovery of jobs from failed workers by scanning working queues and returning jobs to their original queues if the worker is no longer alive. These changes collectively enhance performance and robustness for unique job enforcement.

_lib/sidekiq\_unique\jobs/lua · high confidence

Refactored Lua shared utilities for performance and Sidekiq 7 compatibility

The Lua scripts in the shared library have been rewritten to improve performance and support Sidekiq v7. Key changes include replacing deprecated global argument handling with explicit \{...}\ in debug logging, implementing pagination for Redis commands (LRANGE, SSCAN, ZSCAN) to prevent blocking on large datasets, and optimizing digest lookups by caching string transformations. The code also introduces helper functions for parsing version strings and retrieving the current time, ensuring more robust handling of job reaping and active worker detection.

_lib/sidekiq\_unique\jobs/lua/shared · high confidence

Refactored Sidekiq Web UI helpers for v9 and Sidekiq 8 compatibility

The Sidekiq web interface helpers have been updated to support the v9 architecture and Sidekiq 8. This change removes the separate changelog and expiring digests views, merging expiring digests into the main digests collection and removing the changelog entirely. It also introduces robust time parsing and display helpers that handle various timestamp formats safely, ensuring compatibility with newer Sidekiq versions without requiring compatibility shims.

_lib/sidekiq\_unique\jobs/web · high confidence

Refactored locking logic and introduced Lua script caching

The library has been restructured to improve how locks are managed and executed. Lock configuration is now handled by dedicated classes (\LockTimeout\ and \LockType\) that calculate settings from job options, and the conflict strategy system has been abstracted into a base \Strategy\ class to support new behaviors like replacing existing locks. Additionally, Lua scripts are now cached in memory and Redis using a new \Script\ client, which reduces overhead by avoiding repeated script loads and includes retry logic for transient errors. A new RSpec matcher (\have\_valid\_sidekiq\_options\) is also provided to help users validate their worker configurations.

sidekiq-unique-jobs · high confidence

Refactored locking strategy into a modular class hierarchy with client/server validation

The locking logic in \lib/sidekiq\_unique\_jobs/lock\ has been restructured from a monolithic implementation into a clear class hierarchy (\BaseLock\, \UntilExecuted\, \UntilExecuting\, \WhileExecuting\, \UntilAndWhileExecuting\, \UntilExpired\) to separate concerns between client-side queuing and server-side execution. This change introduces dedicated \ClientValidator\ and \ServerValidator\ classes that enforce valid conflict strategies (e.g., preventing \:replace\ on the server or \:raise\/\:reject\/\:reschedule\ on the client) and handles deprecation warnings for legacy \unique:\ keys. For users, this means more robust lock management that prevents duplicate executions during retries and provides clearer configuration errors if incompatible lock options are set.

_lib/sidekiq\_unique\jobs/lock · high confidence

Restored Ruby-based orphan reaper to prevent premature job deletion

The orphan reaper logic has been restored as a Ruby-based implementation to ensure that active jobs are not incorrectly identified as orphans and deleted. This change introduces a reaper that validates candidate digests against Sidekiq queues, the retry set, the scheduled set, and active processes before removal, short-circuiting on the first match to avoid false positives. It also includes safeguards such as a grace period and queue-length thresholds to prevent performance issues during high load, ensuring that only truly stale locks are cleaned up.

_lib/sidekiq\_unique\jobs/orphans · high confidence

Upgrade to Ruby 4.0.2 and Rails 8.1 with Tailwind/DaisyUI styling

The application runtime has been upgraded to Ruby 4.0.2 and Rails 8.1. The frontend styling has been updated to use Tailwind CSS with the DaisyUI component library, including configuration for light, dark, and cyberpunk themes. Development tooling has also been updated to use Bun 1.3.11 for asset management.

myapp · high confidence

Test coverage

Added Redis testing support module; Added custom RSpec matchers for date validation and Sidekiq queue assertions; Added integration test for lock behavior under high latency; Added performance benchmarks for lock digest, locksmith, and conflict replacement; Added shared RSpec contexts for testing Sidekiq and Locksmith integration; Added shared test examples for lock and worker behavior; Added test coverage for lock implementations and validation logic; Added test coverage for on-conflict strategies; Added test coverage for the Sidekiq Lua script execution layer; Added test coverage for worker locking and uniqueness behaviors; Added test suite for client middleware and test configuration; Added test support for unique job execution; Added test support infrastructure for Lua scripts and lock simulation; Added test worker fixtures for unique locking strategies; Added tests for Sidekiq API and job lifecycle uniqueness lock cleanup; Added tests for Sidekiq Unique Jobs web helpers; Added tests for Sidekiq job fetch and lock validation logic; Added tests for the Ruby-based orphan reaper; Expanded test coverage for Sidekiq Unique Jobs core components; Removal of legacy test helper configuration; Removed test\_client.rb test file.

Dependencies

Add Appraisal gemfiles for Sidekiq 8.0 and 8.1

New gemfiles have been added to support testing against Sidekiq versions 8.0 and 8.1, enabling compatibility verification for these specific releases.

gemfiles · high confidence

Upgrade to Rails 8.1 and Sidekiq 8+ with modernized dependencies

The gemspec and application manifests have been updated to require Sidekiq 8 (\>= 8.0.0, \< 10.0.0) and Ruby 3.2+, replacing the legacy Sidekiq 2 dependency. The documentation site and example application now run on Rails 8.1, utilizing modern tooling such as Propshaft for assets, Phlex for views, and daisyUI for styling. Development tooling has been refreshed with RuboCop omakase, Brakeman, and Bundler Audit, while the old Rails 3.2 and Sprockets-based Gemfile has been removed.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 43 → 40 (-2.9)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 53 → 39 (-14.4)
  • Architecture 92 → 92 (-0.8)
  • Maturity 68 → 69 (+1.3)
  • Readiness 67 → 67 (-0.1)
  • Security 37 → 34 (-3.6)
  • Domain Modelling 100 → 100 (+0.0)
  • Accessibility 31 → 31 (+0.0)
  • Performance 95 → 95 (+0.0)

Resolved (5)

  • Ambiguous duplication: It is unclear if now_f and now serve distinct purposes (e.g., float vs integer timestamp, or different time sources) or if one is a legacy alias for the other. Without documentation, these appear to be redundant operations for retrieving the current time.
  • Ambiguous duplication: locked likely returns a boolean indicating if the lock is held, while locked_jids returns the IDs of jobs currently holding the lock. However, the naming locked is a predicate, while locked_jids is a data retrieval method. This is not strictly an inconsistency, but if locked returns a list of JIDs in some contexts, it would be a major issue. Assuming standard usage, this is likely consistent, but the naming locked vs locked_jids could be clearer (e.g., is_locked? vs holding_job_ids).
  • Ambiguous duplication: reflections (plural) suggests retrieving a collection or registry of reflections, while reflect (singular) suggests performing an action or retrieving a single item. However, without seeing the return types, it is unclear if reflect is a method on a specific object or a class method that does something entirely different. If reflect is a class method that triggers a reflection process, it's distinct. If it's meant to be a getter for a single reflection, the naming is inconsistent with reflections.
  • Standard Ruby convention violation: Similar to validate_worker, the ! suffix on delete implies a destructive operation or raising an exception. If delete returns a boolean and delete! raises, this is consistent. However, in many Ruby libraries, delete is the primary method and delete! is not used, or vice versa. Having both requires strict adherence to the convention to avoid confusion.
  • Standard Ruby convention violation: The ! suffix typically implies a destructive operation or raising an exception on failure, while the non-! version returns a boolean or nil. However, in validation contexts, this distinction is often confusing if both raise or both return booleans. If validate_worker returns a boolean and validate_worker! raises, this is consistent with Ruby, but if they behave similarly, it's redundant.

New (8)

  • High secret: WD-SECRET-0005 (my_app/dev.env)
  • High secret: WD-SECRET-0005 (myapp/db/seeds.rb)
  • High secret: WD-SECRET-0005 (myapp/db/seeds.rb)
  • High secret: WD-SECRET-0005 (myapp/dev.env)
  • High secret: WD-SECRET-0005 (rails_example/dev.env)
  • High secret: WD-SECRET-0005 (rails_example/docker-compose.yml)
  • Medium CVE: [GHSA redacted] (myapp/Gemfile.lock)
  • Outdated: bootsnap

Architecture

  • Unchanged — 0 containers · 1 contexts · 0 edges

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

zoolutions/sidekiq-unique-jobs was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 18473ac8d1e35b1611826d4496aeb0492217d3fe — the exact code this score is about.
  • Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.2+preprod-5c4e66d9318b.