feat: add cache locks

Author: innocenzi

packages/cache/src/Cache.php

@@ -20,6 +20,15 @@ interface Cache
         set;
     }
 
+    /**
+     * Returns a lock for the specified key. The lock is not acquired until `acquire()` is called.
+     *
+     * @param Stringable|string $key The identifier of the lock.
+     * @param null|Duration|DateTimeInterface $expiration The expiration time for the lock. If not specified, the lock will not expire.
+     * @param null|Stringable|string $owner The owner of the lock, which will be used to identify the process releasing it. If not specified, a random string will be used.
+     */
+    public function lock(Stringable|string $key, null|Duration|DateTimeInterface $expiration = null, null|Stringable|string $owner = null): Lock;
+
     /**
      * Sets the specified key to the specified value in the cache. Optionally, specify an expiration.
      */
@@ -52,6 +61,11 @@ public function get(Stringable|string $key): mixed;
      */
     public function getMany(iterable $key): array;
 
+    /**
+     * Determines whether the cache contains the specified key.
+     */
+    public function has(Stringable|string $key): bool;
+
     /**
      * Increments the value associated with the specified key by the specified amount. If the key does not exist, it is created with the specified amount.
      */

packages/cache/src/GenericCache.php

@@ -11,6 +11,7 @@
 use Tempest\DateTime\DateTimeInterface;
 use Tempest\DateTime\Duration;
 use Tempest\Support\Arr;
+use Tempest\Support\Random;
 
 final class GenericCache implements Cache
 {
@@ -22,6 +23,29 @@ public function __construct(
         $this->adapter ??= $this->cacheConfig->createAdapter();
     }
 
+    public function lock(Stringable|string $key, null|Duration|DateTimeInterface $expiration = null, null|Stringable|string $owner = null): Lock
+    {
+        if ($expiration instanceof Duration) {
+            $expiration = DateTime::now()->plus($expiration);
+        }
+
+        return new GenericLock(
+            key: (string) $key,
+            owner: $owner ? ((string) $owner) : Random\secure_string(length: 10),
+            cache: $this,
+            expiration: $expiration,
+        );
+    }
+
+    public function has(Stringable|string $key): bool
+    {
+        if (! $this->enabled) {
+            return false;
+        }
+
+        return $this->adapter->getItem((string) $key)->isHit();
+    }
+
     public function put(Stringable|string $key, mixed $value, null|Duration|DateTimeInterface $expiration = null): CacheItemInterface
     {
         $item = $this->adapter

packages/cache/src/GenericLock.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace Tempest\Cache;
+
+use Closure;
+use Stringable;
+use Tempest\DateTime\DateTime;
+use Tempest\DateTime\DateTimeInterface;
+use Tempest\DateTime\Duration;
+
+final class GenericLock implements Lock
+{
+    public function __construct(
+        private(set) string $key,
+        private(set) string $owner,
+        private readonly Cache $cache,
+        private(set) ?DateTimeInterface $expiration = null,
+    ) {}
+
+    public function locked(null|Stringable|string $by = null): bool
+    {
+        if ($by === null) {
+            return $this->cache->has($this->key);
+        }
+
+        return $this->cache->get($this->key) === ((string) $by);
+    }
+
+    public function acquire(): bool
+    {
+        if ($this->locked()) {
+            return false;
+        }
+
+        $this->cache->put(
+            key: $this->key,
+            value: $this->owner,
+            expiration: $this->expiration,
+        );
+
+        return true;
+    }
+
+    public function execute(Closure $callback, null|DateTimeInterface|Duration $wait = null): mixed
+    {
+        $wait ??= Datetime::now();
+        $waitUntil = ($wait instanceof Duration)
+            ? DateTime::now()->plus($wait)
+            : $wait;
+
+        while (! $this->acquire()) {
+            if ($waitUntil->beforeOrAtTheSameTime(DateTime::now())) {
+                throw new LockAcquisitionTimedOutException($this->key);
+            }
+
+            usleep(250); // TODO: sleep from clock?
+        }
+
+        try {
+            return $callback();
+        } finally {
+            $this->release();
+        }
+    }
+
+    public function release(bool $force = false): bool
+    {
+        if (! $this->locked()) {
+            return false;
+        }
+
+        $lock = $this->cache->get($this->key);
+
+        if ($lock !== $this->owner && ! $force) {
+            return false;
+        }
+
+        $this->cache->remove($this->key);
+
+        return true;
+    }
+}

packages/cache/src/Lock.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Tempest\Cache;
+
+use Closure;
+use Stringable;
+use Tempest\DateTime\DateTimeInterface;
+use Tempest\DateTime\Duration;
+
+interface Lock
+{
+    /**
+     * The key used to identify the lock. This should be unique across all locks.
+     */
+    public string $key {
+        get;
+    }
+
+    /**
+     * The expiration date of the lock. If null, the lock will not expire.
+     */
+    public ?DateTimeInterface $expiration {
+        get;
+    }
+
+    /**
+     * The owner of the lock. This is used to verify that the lock is being released by the correct owner.
+     */
+    public string $owner {
+        get;
+    }
+
+    /**
+     * Attempts to acquire a lock.
+     */
+    public function acquire(): bool;
+
+    /**
+     * Checks if the lock is currently held.
+     */
+    public function locked(null|Stringable|string $by = null): bool;
+
+    /**
+     * Executes the given callback while holding the lock.
+     *
+     * @template TReturn
+     *
+     * @param Closure(): TReturn $callback The callback to execute while holding the lock.
+     * @param null|DateTimeInterface|Duration $wait The time to wait for the lock to be acquired. If null, the lock will not wait.
+     *
+     * @return TReturn The result of the callback.
+     */
+    public function execute(Closure $callback, null|DateTimeInterface|Duration $wait = null): mixed;
+
+    /**
+     * Releases the lock.
+     */
+    public function release(bool $force = false): bool;
+}

packages/cache/src/LockAcquisitionTimedOutException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Tempest\Cache;
+
+use Exception;
+
+final class LockAcquisitionTimedOutException extends Exception implements CacheException
+{
+    public function __construct(
+        public readonly string $key,
+    ) {
+        parent::__construct(
+            message: "Lock with key `{$key}` could not be acquired on time.",
+        );
+    }
+}

packages/cache/src/Testing/RestrictedCache.php

@@ -7,6 +7,7 @@
 use Stringable;
 use Tempest\Cache\Cache;
 use Tempest\Cache\ForbiddenCacheUsageException;
+use Tempest\Cache\Lock;
 use Tempest\DateTime\DateTimeInterface;
 use Tempest\DateTime\Duration;
 
@@ -17,6 +18,16 @@ public function __construct(
         private ?string $tag = null,
     ) {}
 
+    public function lock(Stringable|string $key, null|Duration|DateTimeInterface $expiration = null, null|Stringable|string $owner = null): Lock
+    {
+        throw new ForbiddenCacheUsageException($this->tag);
+    }
+
+    public function has(Stringable|string $key): bool
+    {
+        throw new ForbiddenCacheUsageException($this->tag);
+    }
+
     public function put(Stringable|string $key, mixed $value, null|Duration|DateTimeInterface $expiration = null): CacheItemInterface
     {
         throw new ForbiddenCacheUsageException($this->tag);

packages/cache/src/Testing/TestingCache.php

@@ -4,17 +4,17 @@
 
 use Closure;
 use PHPUnit\Framework\Assert;
-use PHPUnit\Framework\AssertionFailedError;
-use PHPUnit\Framework\ExpectationFailedException;
 use Psr\Cache\CacheItemInterface;
 use Psr\Clock\ClockInterface;
 use Stringable;
 use Symfony\Component\Cache\Adapter\ArrayAdapter;
 use Tempest\Cache\Cache;
 use Tempest\Cache\Config\CustomCacheConfig;
 use Tempest\Cache\GenericCache;
+use Tempest\Cache\GenericLock;
 use Tempest\DateTime\DateTimeInterface;
 use Tempest\DateTime\Duration;
+use Tempest\Support\Random;
 
 final class TestingCache implements Cache
 {
@@ -37,6 +37,21 @@ public function __construct(
         );
     }
 
+    public function lock(Stringable|string $key, null|Duration|DateTimeInterface $expiration = null, null|Stringable|string $owner = null): TestingLock
+    {
+        return new TestingLock(new GenericLock(
+            key: (string) $key,
+            owner: $owner ? ((string) $owner) : Random\secure_string(length: 10),
+            cache: $this->cache,
+            expiration: $expiration,
+        ));
+    }
+
+    public function has(Stringable|string $key): bool
+    {
+        return $this->cache->has($key);
+    }
+
     public function put(Stringable|string $key, mixed $value, null|Duration|DateTimeInterface $expiration = null): CacheItemInterface
     {
         return $this->cache->put($key, $value, $expiration);
@@ -171,4 +186,24 @@ public function assertNotEmpty(): self
 
         return $this;
     }
+
+    /**
+     * Asserts that the specified lock is being held.
+     */
+    public function assertLocked(string|Stringable $key, null|Stringable|string $by = null, null|DateTimeInterface|Duration $until = null): self
+    {
+        $this->lock($key)->assertLocked($by, $until);
+
+        return $this;
+    }
+
+    /**
+     * Asserts that the specified lock is not being held.
+     */
+    public function assertNotLocked(string|Stringable $key, null|Stringable|string $by = null): self
+    {
+        $this->lock($key)->assertNotLocked($by);
+
+        return $this;
+    }
 }