feat: raise error when advisory lock cannot be acquired within configured timeout

[Farjaad]

Overview

This PR introduces an :advisory_lock_timeout_seconds configuration option that triggers an error when an advisory lock cannot be obtained within the specified time limit.

Motivation

We experienced jobs that would wait for several minutes executing SELECT GET_LOCK until Sidekiq terminated them. This created queue blockages and led to significant job backlogs. Implementing a timeout enables jobs to fail quickly and retry during periods of lower contention, ultimately completing successfully.

Example Usage

class Tag < ApplicationRecord
  has_closure_tree advisory_lock_timeout_seconds: 30
end

Behavior

When advisory_lock_timeout_seconds is configured, a WithAdvisoryLock::FailedToAcquireLock exception is raised if the lock cannot be secured within the designated timeframe, creating explicit failure handling for lock contention scenarios.

Without this configuration, the system maintains the default behavior of waiting indefinitely until lock acquisition.

Implementation Details

• Introduces advisory_lock_timeout_seconds configuration option
• Invokes with_advisory_lock! with lock parameters when advisory_lock_timeout_seconds is specified

Backward Compatibility

The advisory_lock_timeout_seconds option defaults to nil, and with_advisory_lock! is only invoked when a non-null value is supplied.

[Copilot]

Pull request overview

This PR introduces an advisory_lock_timeout_seconds configuration option that allows closure_tree to raise an error when an advisory lock cannot be acquired within a specified timeout period, preventing indefinite blocking and enabling jobs to fail fast and retry during lower contention.

Changes:

• Added advisory_lock_timeout_seconds configuration option with validation
• Implemented logic to call with_advisory_lock! instead of with_advisory_lock when timeout is configured
• Added tests to verify the new timeout functionality
• Updated documentation to describe the new option

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
lib/closure_tree/support.rb	Adds default option, validation logic, and conditional method selection based on timeout configuration
lib/closure_tree/support_attributes.rb	Implements advisory_lock_options helper method to build options hash with timeout
lib/closure_tree/has_closure_tree.rb	Adds advisory_lock_timeout_seconds to the list of valid configuration keys
test/closure_tree/support_test.rb	Adds unit tests for initialization and method selection based on timeout configuration
test/closure_tree/parallel_test.rb	Updates stub signature to accept options parameter for backward compatibility
README.md	Documents the new advisory_lock_timeout_seconds configuration option

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.