feat: Add RefreshableLock interface for long-running task support

[binaryfire]

Problem

Laravel's cache lock implementation provides basic locking primitives (acquire, release, forceRelease), but lacks support for long-running tasks that may exceed the lock's TTL. This is a known gap that developers have requested - the ability to refresh a lock's TTL without releasing and reacquiring it. The current workaround of release-then-reacquire is non-atomic and creates a race condition window where another process can steal the lock.

Real-world scenarios where this matters:

• Workflows with activities that may run longer than expected
• Long-running queue jobs that need exclusive access to a resource
• Batch processing where completion time is unpredictable
• Distributed cron implementations

Solution

Introduce a RefreshableLock interface that extends the base Lock contract with two methods:

interface RefreshableLock extends Lock
{
    /**
     * Atomically refresh the lock's TTL if still owned by this process.
     *
     * @throws \InvalidArgumentException If $seconds is explicitly <= 0
     */
    public function refresh(?int $seconds = null): bool;

    /**
     * Get the number of seconds until the lock expires.
     */
    public function getRemainingLifetime(): ?float;
}

refresh() Behavior

Call	Behavior
refresh()	Extends TTL using original value from construction
refresh(30)	Extends TTL to 30 seconds
refresh() on permanent lock	No-op, returns true (nothing to refresh)
refresh(0) or refresh(-1)	Throws InvalidArgumentException

Why throw for refresh(0)?

Passing zero is not "renewing a lease" - it's changing the lock into something fundamentally different (permanent). This is a semantic cliff that can cause operational issues: accidentally converting a TTL lock into a permanent lock can wedge work until someone manually force-releases it.

If you need a permanent lock, acquire it that way: Cache::lock('key', 0). The refresh() method is strictly for extending existing TTLs.

Why an interface instead of adding to the base class?

Not all lock drivers can implement atomic refresh. CacheLock and FileLock use the generic Store interface which lacks atomic check-and-update operations. Adding methods that throw "not supported" would violate Liskov Substitution Principle.

The interface approach:

• Provides type safety - you can typehint RefreshableLock when you need refresh capability
• Is honest - drivers that can't implement it atomically simply don't implement the interface
• Follows Interface Segregation Principle - not every lock consumer needs refresh

Implementation

Driver	Implements	Atomic?	How
RedisLock	✅	✅	Lua script: if GET == owner then EXPIRE
DatabaseLock	✅	✅	UPDATE ... WHERE key = ? AND owner = ?
ArrayLock	✅	✅	In-memory check and update
NoLock	✅	N/A	No-op (always succeeds)
CacheLock	❌	-	Cannot guarantee atomicity
FileLock	❌	-	Inherits CacheLock limitation

Redis Implementation

Uses an inline Lua script for atomicity:

if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("expire", KEYS[1], ARGV[2])
else
    return 0
end

TTL Semantics

getRemainingLifetime() returns:

• float - seconds remaining
• null - lock doesn't exist, has expired, or has no expiry (infinite lock)

For Redis, this correctly handles the TTL command's special return values (-1 for no expiry, -2 for missing key).

Usage

use Hypervel\Cache\Contracts\RefreshableLock;

$lock = Cache::lock('long-running-task', 60);

if ($lock->acquire()) {
    try {
        while (!$finished) {
            // Do a chunk of work...

            // Refresh the lock to prevent expiry
            if ($lock instanceof RefreshableLock) {
                $lock->refresh();      // Extends by original TTL (60s)
                $lock->refresh(120);   // Or extend to 120 seconds

                // Check remaining time if needed
                $remaining = $lock->getRemainingLifetime();
            }
        }
    } finally {
        $lock->release();
    }
}

For code that requires refreshable locks:

function processWithHeartbeat(RefreshableLock $lock, callable $work): mixed
{
    // Type system guarantees refresh() is available
    // Works with any lock - permanent locks just return true (no-op)
}

Tests

Added comprehensive tests for all implementing drivers:

• CacheRedisLockTest - New file with 15 tests
• CacheDatabaseLockTest - 10 new tests added to existing file
• CacheArrayStoreTest - 12 new tests added to existing file
• CacheNoLockTest - New file with 10 tests

Tests cover: TTL refresh, custom TTL, ownership checks, permanent lock no-op behavior, and InvalidArgumentException for invalid TTL values.

Cleanup

• Deleted LuaScripts.php from the cache package. It contained only one method (releaseLock()) used in one place. The Lua script is now inlined in RedisLock::release() for better locality.

References

• Laravel Framework Discussion #52778: Cache lock refresh() for long-running operations
• Symfony Lock Component - Expiring Locks (prior art - Symfony has refresh())

[Copilot]

Pull request overview

This PR introduces a RefreshableLock interface to support long-running tasks that need to refresh lock TTLs without releasing and reacquiring. The interface adds two methods: refresh() for atomically extending a lock's TTL, and getRemainingLifetime() for checking expiration time.

Key Changes:

• New RefreshableLock interface extending the base Lock contract
• Implementation in RedisLock, DatabaseLock, ArrayLock, and NoLock using atomic operations
• Comprehensive test coverage for all implementing drivers
• Removal of LuaScripts.php utility class with Lua script inlined for better locality

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/cache/src/Contracts/RefreshableLock.php	New interface defining refresh() and getRemainingLifetime() methods with clear contract documentation
src/cache/src/RedisLock.php	Implements RefreshableLock with Lua scripts for atomic ownership checking; inlines release script previously in LuaScripts
src/cache/src/DatabaseLock.php	Implements RefreshableLock using UPDATE with WHERE conditions for atomic refresh
src/cache/src/ArrayLock.php	Implements RefreshableLock with in-memory ownership and expiration checks
src/cache/src/NoLock.php	Implements RefreshableLock as no-op for testing/disabled scenarios
src/cache/src/LuaScripts.php	Deleted - single method inlined in RedisLock for better code locality
tests/Cache/CacheRedisLockTest.php	New test file with 15 tests covering all RedisLock refresh functionality
tests/Cache/CacheNoLockTest.php	New test file with 10 tests for NoLock refresh behavior
tests/Cache/CacheDatabaseLockTest.php	Added 10 tests for DatabaseLock refresh operations
tests/Cache/CacheArrayStoreTest.php	Added 12 tests for ArrayLock refresh functionality

---

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

[Copilot]

Inconsistent parameter validation order. In ArrayLock, the ownership check happens before parameter validation (lines 101-107 before 111-115), but in RedisLock, DatabaseLock, and NoLock, parameter validation happens first (line 90-94 before the ownership check in the Lua script at line 104). This means ArrayLock will return false for invalid parameters when not owning the lock, while other implementations will throw InvalidArgumentException. The validation should happen first for consistency across all implementations.

[albertcht]

Hi @binaryfire , thanks for this pull request. I personally like this idea and I think it will be pretty useful in long-running tasks.