fix(cache): report a cache that refuses an invalidation as unavailable

composer.json

@@ -51,7 +51,7 @@
         "ext-redis": "*",
         "utopia-php/validators": "^1.0 || ^2.0",
         "utopia-php/console": "^0.1 || ^0.2",
-        "utopia-php/cache": "^4.0 || ^5.0",
+        "utopia-php/cache": "^5.2",
         "utopia-php/pools": "^2.0",
         "utopia-php/mongo": "^1.5.4",
         "utopia-php/query": "^0.7.2",

src/Database/Cache/Query.php

@@ -5,6 +5,7 @@
 use InvalidArgumentException;
 use RuntimeException;
 use Utopia\Cache\Cache;
+use Utopia\Cache\Exception\Unavailable;
 use Utopia\Database\Document;
 
 /**
@@ -209,11 +210,11 @@ public function createToken(): string
     public function blockCollection(string $key, string $token): void
     {
         if (! (new Owners($this->cache))->register($key, $token)) {
-            throw new RuntimeException("Failed to register query cache owner for '{$key}'");
+            throw new Unavailable("Failed to register query cache owner for '{$key}'");
         }
 
         if ($this->cache->save($this->getEpochKey($key), self::BLOCKED_PREFIX.$token.self::SEPARATOR.\time()) === false) {
-            throw new RuntimeException("Failed to block query cache epoch for '{$key}'");
+            throw new Unavailable("Failed to block query cache epoch for '{$key}'");
         }
 
         $this->cache->purge($this->getStartedKey($key));
@@ -237,7 +238,7 @@ public function activateCollection(string $key, string $token, int $writerTimeou
         if ($owned && ! $this->cache->purge($registration->key, $registration->field)) {
             $owner = $this->cache->load($registration->key, self::PERMANENT, $registration->field);
             if ($owner !== false && $owner !== null) {
-                throw new RuntimeException("Failed to release query cache owner for '{$key}'");
+                throw new Unavailable("Failed to release query cache owner for '{$key}'");
             }
             $owned = false;
         }
@@ -277,7 +278,7 @@ public function activateCollection(string $key, string $token, int $writerTimeou
         }
 
         if ($nextFinished === $finished && $this->isTombstoneOf($this->cache->load($epochKey, self::PERMANENT), $token)) {
-            throw new RuntimeException("Failed to finish query cache invalidation for '{$key}'");
+            throw new Unavailable("Failed to finish query cache invalidation for '{$key}'");
         }
 
         if ($registration->field !== '' && $this->releaseAbandonedOwners($registration->key, $writerTimeout)) {
@@ -288,7 +289,7 @@ public function activateCollection(string $key, string $token, int $writerTimeou
     public function flush(): void
     {
         if (! $this->cache->flush()) {
-            throw new RuntimeException('Failed to flush query cache');
+            throw new Unavailable('Failed to flush query cache');
         }
     }
 
@@ -411,7 +412,7 @@ private function publish(string $key, string $finished): void
         $epoch = self::ACTIVE_PREFIX.\bin2hex(\random_bytes(16)).self::SEPARATOR.$finished;
 
         if ($this->cache->save($this->getEpochKey($key), $epoch) === false) {
-            throw new RuntimeException("Failed to activate query cache for '{$key}'");
+            throw new Unavailable("Failed to activate query cache for '{$key}'");
         }
     }
 

src/Database/Trait/Documents.php

@@ -8,6 +8,7 @@
 use Generator;
 use RuntimeException;
 use Throwable;
+use Utopia\Cache\Exception\Unavailable as CacheUnavailable;
 use Utopia\Console;
 use Utopia\Database\Adapter;
 use Utopia\Database\Adapter\Feature;
@@ -3799,7 +3800,7 @@ private function blockDocumentCacheEpoch(string $collectionKey, string $token, s
 
         $this->withRetries(function () use ($epochKey, $token): void {
             if ($this->cache->save($epochKey, self::DOCUMENT_CACHE_BLOCKED_PREFIX.$token.self::DOCUMENT_CACHE_SEPARATOR.\time()) === false) {
-                throw new RuntimeException("Failed to block document cache epoch '{$epochKey}'");
+                throw new CacheUnavailable("Failed to block document cache epoch '{$epochKey}'");
             }
         });
 
@@ -3920,7 +3921,7 @@ private function publishDocumentCacheEpoch(string $collectionKey, string $starte
         $epoch = self::DOCUMENT_CACHE_ACTIVE_PREFIX.\bin2hex(\random_bytes(16)).self::DOCUMENT_CACHE_SEPARATOR.$started;
         $this->withRetries(function () use ($epochKey, $epoch): void {
             if ($this->cache->save($epochKey, $epoch) === false) {
-                throw new RuntimeException("Failed to activate document cache epoch '{$epochKey}'");
+                throw new CacheUnavailable("Failed to activate document cache epoch '{$epochKey}'");
             }
         });
 
@@ -3941,7 +3942,7 @@ private function releaseDocumentCacheOwner(Registration $registration, string $c
 
             $owner = $this->cache->load($registration->key, self::TTL, $registration->field);
             if ($owner !== false && $owner !== null) {
-                throw new RuntimeException("Failed to release document cache owner '{$token}' for '{$collectionKey}'");
+                throw new CacheUnavailable("Failed to release document cache owner '{$token}' for '{$collectionKey}'");
             }
             $released = false;
         });
@@ -3975,7 +3976,7 @@ private function finishDocumentCacheWrite(string $collectionKey, string $finishe
                 && \is_string($epoch)
                 && $this->cache->load($epochKey, self::DOCUMENT_CACHE_PERMANENT) === $epoch
             ) {
-                throw new RuntimeException("Failed to finish document cache invalidation '{$epochKey}'");
+                throw new CacheUnavailable("Failed to finish document cache invalidation '{$epochKey}'");
             }
         });
 

tests/unit/Cache/QueryTest.php

@@ -7,6 +7,7 @@
 use PHPUnit\Framework\TestCase;
 use Utopia\Cache\Adapter\Memory;
 use Utopia\Cache\Cache;
+use Utopia\Cache\Exception\Unavailable;
 use Utopia\Database\Attribute;
 use Utopia\Database\Cache\Entry;
 use Utopia\Database\Cache\Invalidator;
@@ -940,7 +941,7 @@ public function save(string $key, mixed $data, string $hash = '', int $ttl = 0):
             }
         });
 
-        $this->expectException(\RuntimeException::class);
+        $this->expectException(Unavailable::class);
         $this->expectExceptionMessage('Failed to block query cache epoch');
         $queryCache->invalidateCollection(new Scope(), 'users');
     }

tests/unit/Cache/UnavailableCache.php

@@ -2,8 +2,8 @@
 
 namespace Tests\Unit\Cache;
 
-use RuntimeException;
 use Utopia\Cache\Adapter as CacheAdapter;
+use Utopia\Cache\Exception\Unavailable;
 use Utopia\Cache\Feature\Leasable;
 
 /**
@@ -70,11 +70,11 @@ private function confirmPurge(): void
         if ($this->failingPurges > 0) {
             $this->failingPurges--;
 
-            throw new RuntimeException('Cache purge could not be confirmed');
+            throw new Unavailable('Cache purge could not be confirmed');
         }
 
         if (! $this->writable()) {
-            throw new RuntimeException('Cache purge could not be confirmed');
+            throw new Unavailable('Cache purge could not be confirmed');
         }
     }
 

tests/unit/Documents/CacheUnavailableTest.php

@@ -9,6 +9,7 @@
 use Tests\Unit\Support\UncachedTwin;
 use Throwable;
 use Utopia\Cache\Cache;
+use Utopia\Cache\Exception\Unavailable;
 use Utopia\Database\Adapter\Memory as DatabaseMemory;
 use Utopia\Database\Attribute;
 use Utopia\Database\Collection;
@@ -63,7 +64,7 @@ public function testAWriteTheCacheCannotInvalidateIsRolledBack(string $outage, C
         $failure = $this->attempt(fn (): mixed => $write($database));
         $cache->recover();
 
-        $this->assertInstanceOf(Throwable::class, $failure, 'A write whose cache invalidation could not be confirmed must fail');
+        $this->assertInstanceOf(Unavailable::class, $failure, 'A write whose cache invalidation could not be confirmed must fail as unavailable, so a caller can tell it was refused');
 
         $this->assertSame('original', $this->stored($database), 'The write must be rolled back');
         $this->assertSame('original', $this->cached($database));