refactor(lock): polish lock store review feedback

- Rename the lock store provider contract for interface consistency
- Finalize immutable lock manager and lock implementations
- Add native service return type and interface method docs
- Localize lock exception messages
- Clarify file lock cleanup and custom store docs
- Address file force-release race pre-check and Predis prefix notes

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

system/Cache/Handlers/FileHandler.php

@@ -15,7 +15,7 @@
 
 use CodeIgniter\Cache\Exceptions\CacheException;
 use CodeIgniter\Cache\LockStoreInterface;
-use CodeIgniter\Cache\LockStoreProvider;
+use CodeIgniter\Cache\LockStoreProviderInterface;
 use CodeIgniter\Cache\LockStores\FileLockStore;
 use CodeIgniter\I18n\Time;
 use Config\Cache;
@@ -26,7 +26,7 @@
  *
  * @see \CodeIgniter\Cache\Handlers\FileHandlerTest
  */
-class FileHandler extends BaseHandler implements LockStoreProvider
+class FileHandler extends BaseHandler implements LockStoreProviderInterface
 {
     /**
      * Maximum key length.
@@ -50,7 +50,7 @@ class FileHandler extends BaseHandler implements LockStoreProvider
      */
     protected $mode;
 
-    private ?LockStoreInterface $lockStore = null;
+    private readonly LockStoreInterface $lockStore;
 
     /**
      * Note: Use `CacheFactory::getHandler()` to instantiate.
@@ -74,6 +74,8 @@ public function __construct(Cache $config)
         $this->mode   = $options['mode'];
         $this->prefix = $config->prefix;
 
+        $this->lockStore = new FileLockStore($this->path, $this->mode, $this->prefix);
+
         helper('filesystem');
     }
 
@@ -192,7 +194,7 @@ public function isSupported(): bool
 
     public function lockStore(): LockStoreInterface
     {
-        return $this->lockStore ??= new FileLockStore($this->path, $this->mode, $this->prefix);
+        return $this->lockStore;
     }
 
     /**

system/Cache/Handlers/PredisHandler.php

@@ -14,7 +14,7 @@
 namespace CodeIgniter\Cache\Handlers;
 
 use CodeIgniter\Cache\LockStoreInterface;
-use CodeIgniter\Cache\LockStoreProvider;
+use CodeIgniter\Cache\LockStoreProviderInterface;
 use CodeIgniter\Cache\LockStores\PredisLockStore;
 use CodeIgniter\Exceptions\CriticalError;
 use CodeIgniter\I18n\Time;
@@ -29,7 +29,7 @@
  *
  * @see \CodeIgniter\Cache\Handlers\PredisHandlerTest
  */
-class PredisHandler extends BaseHandler implements LockStoreProvider
+class PredisHandler extends BaseHandler implements LockStoreProviderInterface
 {
     /**
      * Default config
@@ -210,6 +210,7 @@ public function isSupported(): bool
 
     public function lockStore(): LockStoreInterface
     {
+        // Predis applies the configured prefix at the client level.
         return $this->lockStore ??= new PredisLockStore($this->redis);
     }
 

system/Cache/Handlers/RedisHandler.php

@@ -14,7 +14,7 @@
 namespace CodeIgniter\Cache\Handlers;
 
 use CodeIgniter\Cache\LockStoreInterface;
-use CodeIgniter\Cache\LockStoreProvider;
+use CodeIgniter\Cache\LockStoreProviderInterface;
 use CodeIgniter\Cache\LockStores\RedisLockStore;
 use CodeIgniter\Exceptions\CriticalError;
 use CodeIgniter\I18n\Time;
@@ -27,7 +27,7 @@
  *
  * @see \CodeIgniter\Cache\Handlers\RedisHandlerTest
  */
-class RedisHandler extends BaseHandler implements LockStoreProvider
+class RedisHandler extends BaseHandler implements LockStoreProviderInterface
 {
     /**
      * Default config

system/Cache/LockStoreInterface.php

@@ -15,13 +15,28 @@
 
 interface LockStoreInterface
 {
+    /**
+     * Attempts to acquire a lock for the given owner and TTL.
+     */
     public function acquireLock(string $key, string $owner, int $ttl): bool;
 
+    /**
+     * Releases the lock only when it is currently held by the given owner.
+     */
     public function releaseLock(string $key, string $owner): bool;
 
+    /**
+     * Releases the lock without checking ownership.
+     */
     public function forceReleaseLock(string $key): bool;
 
+    /**
+     * Extends the lock TTL only when it is currently held by the given owner.
+     */
     public function refreshLock(string $key, string $owner, int $ttl): bool;
 
+    /**
+     * Returns the current owner token, or null when the lock is not held.
+     */
     public function getLockOwner(string $key): ?string;
 }

system/Cache/LockStoreProvider.php …tem/Cache/LockStoreProviderInterface.phpsystem/Cache/LockStoreProvider.php renamed to system/Cache/LockStoreProviderInterface.php system/Cache/LockStoreProvider.php renamed to system/Cache/LockStoreProviderInterface.php

@@ -13,7 +13,10 @@
 
 namespace CodeIgniter\Cache;
 
-interface LockStoreProvider
+interface LockStoreProviderInterface
 {
+    /**
+     * Returns the atomic lock store for this cache handler.
+     */
     public function lockStore(): LockStoreInterface;
 }

system/Cache/LockStores/FileLockStore.php

@@ -56,8 +56,7 @@ public function releaseLock(string $key, string $owner): bool
 
     public function forceReleaseLock(string $key): bool
     {
-        return ! is_file($this->path . FileHandler::validateKey($key, $this->prefix))
-            || $this->withLockFile($key, static fn ($handle): bool => self::clearLockFile($handle), false);
+        return $this->withLockFile($key, static fn ($handle): bool => self::clearLockFile($handle));
     }
 
     public function refreshLock(string $key, string $owner, int $ttl): bool

system/Config/Services.php

@@ -134,10 +134,8 @@ public static function cache(?Cache $config = null, bool $getShared = true)
 
     /**
      * The locks service provides atomic locks backed by supported cache handlers.
-     *
-     * @return LockManager
      */
-    public static function locks(?CacheInterface $cache = null, bool $getShared = true)
+    public static function locks(?CacheInterface $cache = null, bool $getShared = true): LockManager
     {
         if ($getShared) {
             return static::getSharedInstance('locks', $cache);

system/Language/en/Lock.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+// Lock language settings
+return [
+    'unsupportedStore' => 'The cache handler "{0}" does not support locks.',
+];

system/Lock/Exceptions/LockException.php

@@ -19,6 +19,6 @@ class LockException extends FrameworkException
 {
     public static function forUnsupportedStore(string $class): self
     {
-        return new self(sprintf('The cache handler "%s" does not support locks.', $class));
+        return new self(lang('Lock.unsupportedStore', [$class]));
     }
 }

system/Lock/Lock.php

@@ -17,13 +17,15 @@
 use CodeIgniter\Cache\LockStoreInterface;
 use CodeIgniter\Exceptions\InvalidArgumentException;
 
-class Lock implements LockInterface
+final readonly class Lock implements LockInterface
 {
+    private const BLOCK_RETRY_MICROSECONDS = 100_000;
+
     public function __construct(
-        private readonly LockStoreInterface $store,
-        private readonly string $key,
-        private readonly int $ttl,
-        private readonly string $owner,
+        private LockStoreInterface $store,
+        private string $key,
+        private int $ttl,
+        private string $owner,
     ) {
         if ($ttl < 1) {
             throw new InvalidArgumentException('Lock TTL must be a positive integer.');
@@ -52,7 +54,7 @@ public function block(int $seconds): bool
                 return true;
             }
 
-            usleep(100_000);
+            usleep(self::BLOCK_RETRY_MICROSECONDS);
         } while (microtime(true) < $expiresAt);
 
         return false;