From b30259d5d74b4dbc9721337b8d5db6b7c57d09cd Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 04:01:56 +1200 Subject: [PATCH 1/9] feat(cache): add Leasable primitive to close the cache-aside read-after-write race MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Under concurrency a reader that fetched a row from the database just before a concurrent purge could re-populate the cache with that now-stale row *after* the purge ran, so later reads served stale data. Purging alone cannot prevent this: the stale reader's write lands after the purge. Adds a Leasable capability. Each key carries a monotonic generation that advances on purge. A reader captures the generation before its DB read and presents it when saving; saveWithLease() persists only if the generation is unchanged (atomic CAS via a Redis Lua script), so a write racing with a purge is rejected rather than caching stale data. The hit path is unchanged — a present value can only be current, since purge atomically drops the value and bumps the generation in one step. Redis implements the capability; Sharding/Pool delegate; the Cache facade exposes getGeneration()/saveWithLease() with a graceful fallback to an unconditional save for non-leasable adapters, so existing behaviour is preserved for everyone who does not opt in. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Pool.php | 23 +++++++- src/Cache/Adapter/Redis.php | 72 +++++++++++++++++++++++++- src/Cache/Adapter/Sharding.php | 19 ++++++- src/Cache/Cache.php | 52 +++++++++++++++++++ src/Cache/Feature/Leasable.php | 33 ++++++++++++ tests/Cache/E2E/Redis/LeasableTest.php | 71 +++++++++++++++++++++++++ 6 files changed, 266 insertions(+), 4 deletions(-) create mode 100644 src/Cache/Feature/Leasable.php create mode 100644 tests/Cache/E2E/Redis/LeasableTest.php diff --git a/src/Cache/Adapter/Pool.php b/src/Cache/Adapter/Pool.php index 5dc4714129..0b98d1e833 100644 --- a/src/Cache/Adapter/Pool.php +++ b/src/Cache/Adapter/Pool.php @@ -3,9 +3,10 @@ namespace Utopia\Cache\Adapter; use Utopia\Cache\Adapter; +use Utopia\Cache\Feature\Leasable; use Utopia\Pools\Pool as UtopiaPool; -class Pool implements Adapter +class Pool implements Adapter, Leasable { /** * @var UtopiaPool @@ -59,6 +60,26 @@ class Pool implements Adapter return $result; } + public function getGeneration(string $key): string + { + /** + * @var string $result + */ + $result = $this->delegate(__FUNCTION__, \func_get_args()); + + return $result; + } + + public function saveWithLease(string $key, array|string $data, string $hash, string $generation): bool|string|array + { + /** + * @var bool|string|array $result + */ + $result = $this->delegate(__FUNCTION__, \func_get_args()); + + return $result; + } + public function touch(string $key, string $hash = ''): bool { /** diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 4427e99639..bd7da6463d 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -7,10 +7,40 @@ use Redis as Client; use Throwable; use Utopia\Cache\Adapter; use Utopia\Cache\Adapter\Redis\Envelope; +use Utopia\Cache\Feature\Leasable; use Utopia\Cache\Feature\Retryable; -class Redis implements Adapter, Retryable +class Redis implements Adapter, Leasable, Retryable { + private const GENERATION_SUFFIX = ':__gen'; + + /** + * Save $hash field into hash $key only when generation key still equals the + * caller's token. KEYS[1]=key, KEYS[2]=generationKey; ARGV[1]=hash, + * ARGV[2]=value, ARGV[3]=expected generation, ARGV[4]=generation ttl seconds. + */ + private const LUA_SAVE_WITH_LEASE = <<<'LUA' + local current = redis.call('GET', KEYS[2]) + if current == false then current = '0' end + if current ~= ARGV[3] then return 0 end + redis.call('HSET', KEYS[1], ARGV[1], ARGV[2]) + return 1 + LUA; + + /** + * Atomically drop $key and advance its generation so any in-flight reader + * that read the previous generation cannot re-cache stale data. + * KEYS[1]=key, KEYS[2]=generationKey; ARGV[1]=generation ttl seconds. + */ + private const LUA_PURGE_BUMP = <<<'LUA' + redis.call('DEL', KEYS[1]) + local gen = redis.call('INCR', KEYS[2]) + redis.call('EXPIRE', KEYS[2], ARGV[1]) + return gen + LUA; + + private const GENERATION_TTL = 86400; + /** * @var Client */ @@ -136,6 +166,37 @@ class Redis implements Adapter, Retryable } } + public function getGeneration(string $key): string + { + $gen = $this->execute(fn () => $this->redis->get($key.self::GENERATION_SUFFIX)); + + return \is_string($gen) ? $gen : '0'; + } + + public function saveWithLease(string $key, array|string $data, string $hash, string $generation): bool|string|array + { + if (empty($key) || empty($data)) { + return false; + } + + if (empty($hash)) { + $hash = $key; + } + + try { + $value = Envelope::encode($data, time()); + $stored = $this->execute(fn () => $this->redis->eval( + self::LUA_SAVE_WITH_LEASE, + [$key, $key.self::GENERATION_SUFFIX, $hash, $value, $generation], + 2 + )); + + return $stored ? $data : false; + } catch (Throwable $th) { + return false; + } + } + /** * @param string $key * @param string $hash optional @@ -188,7 +249,14 @@ class Redis implements Adapter, Retryable return (bool) $this->execute(fn () => $this->redis->hdel($key, $hash)); } - return (bool) $this->execute(fn () => $this->redis->del($key)); + // Drop the key and advance its generation in one atomic step (Redis Lua) + // so an in-flight reader holding the previous generation cannot re-cache + // stale data after this purge. + return (bool) $this->execute(fn () => $this->redis->eval( + self::LUA_PURGE_BUMP, + [$key, $key.self::GENERATION_SUFFIX, (string) self::GENERATION_TTL], + 2 + )); } /** diff --git a/src/Cache/Adapter/Sharding.php b/src/Cache/Adapter/Sharding.php index 53f9c8b3da..e267362d2a 100644 --- a/src/Cache/Adapter/Sharding.php +++ b/src/Cache/Adapter/Sharding.php @@ -3,8 +3,9 @@ namespace Utopia\Cache\Adapter; use Utopia\Cache\Adapter; +use Utopia\Cache\Feature\Leasable; -class Sharding implements Adapter +class Sharding implements Adapter, Leasable { /** * @var Adapter[] @@ -66,6 +67,22 @@ class Sharding implements Adapter return $this->getAdapter($key)->save($key, $data, $hash); } + public function getGeneration(string $key): string + { + $adapter = $this->getAdapter($key); + + return $adapter instanceof Leasable ? $adapter->getGeneration($key) : '0'; + } + + public function saveWithLease(string $key, array|string $data, string $hash, string $generation): bool|string|array + { + $adapter = $this->getAdapter($key); + + return $adapter instanceof Leasable + ? $adapter->saveWithLease($key, $data, $hash, $generation) + : $adapter->save($key, $data, $hash); + } + /** * @param string $key * @param string $hash optional diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index 177e53fd90..4da205deac 100644 --- a/src/Cache/Cache.php +++ b/src/Cache/Cache.php @@ -2,6 +2,7 @@ namespace Utopia\Cache; +use Utopia\Cache\Feature\Leasable; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Telemetry\Adapter\None as NoTelemetry; use Utopia\Telemetry\Counter; @@ -140,6 +141,57 @@ class Cache } } + /** + * Current generation token for $key (advances on each purge). Returns '0' + * when the underlying adapter does not support leasing. + * + * @param string $key + * @return string + */ + public function getGeneration(string $key): string + { + if (! $this->adapter instanceof Leasable) { + return '0'; + } + + $key = $this->caseSensitive ? $key : \strtolower($key); + + return $this->adapter->getGeneration($key); + } + + /** + * Save $data only if the key's generation still equals $generation (i.e. no + * purge happened since the caller captured it via getGeneration). Closes the + * cache-aside read-after-write race. Falls back to an unconditional save when + * the adapter does not support leasing. + * + * @param string $key + * @param string|array $data + * @param string $hash + * @param string $generation + * @return bool|string|array + */ + public function saveWithLease(string $key, mixed $data, string $hash, string $generation): bool|string|array + { + $key = $this->caseSensitive ? $key : \strtolower($key); + $hash = $this->caseSensitive ? $hash : \strtolower($hash); + $start = microtime(true); + + try { + if (! $this->adapter instanceof Leasable) { + return $this->adapter->save($key, $data, $hash); + } + + return $this->adapter->saveWithLease($key, $data, $hash, $generation); + } finally { + $duration = microtime(true) - $start; + $this->getOperationDuration()->record($duration, [ + 'operation' => 'saveWithLease', + 'adapter' => $this->adapter->getName($key), + ]); + } + } + /** * Refresh a cache entry timestamp without replacing its data. * diff --git a/src/Cache/Feature/Leasable.php b/src/Cache/Feature/Leasable.php new file mode 100644 index 0000000000..c838e8f6a7 --- /dev/null +++ b/src/Cache/Feature/Leasable.php @@ -0,0 +1,33 @@ +|string $data + * @return bool|string|array + */ + public function saveWithLease(string $key, array|string $data, string $hash, string $generation): bool|string|array; +} diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php new file mode 100644 index 0000000000..3e2ce7c3ff --- /dev/null +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -0,0 +1,71 @@ +connect('redis', 6379); + $this->cache = new Cache(new RedisAdapter($redis)); + $this->cache->flush(); + } + + public function testFreshKeyHasZeroGeneration(): void + { + $this->assertSame('0', $this->cache->getGeneration('doc:1')); + } + + public function testSaveWithLeaseStoresWhenGenerationUnchanged(): void + { + $generation = $this->cache->getGeneration('doc:1'); + + $this->assertNotFalse($this->cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $generation)); + $this->assertSame(['v' => 1], $this->cache->load('doc:1', 60, 'doc:1')); + } + + public function testPurgeAdvancesGeneration(): void + { + $before = $this->cache->getGeneration('doc:1'); + $this->cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $before); + $this->cache->purge('doc:1'); + + $this->assertNotSame($before, $this->cache->getGeneration('doc:1')); + } + + /** + * The core read-after-write guarantee: a reader that captured the generation + * BEFORE a concurrent purge must NOT be able to re-cache its now-stale value + * AFTER the purge. Ordering here simulates the race deterministically. + */ + public function testStaleSaveAfterPurgeIsRejected(): void + { + $captured = $this->cache->getGeneration('doc:1'); + + // A writer commits and purges; the generation advances. + $this->cache->purge('doc:1'); + + // The reader tries to re-cache the value it read before the purge. + $result = $this->cache->saveWithLease('doc:1', ['stale' => true], 'doc:1', $captured); + + $this->assertFalse($result, 'Stale re-cache must be rejected after a purge advanced the generation'); + $this->assertFalse($this->cache->load('doc:1', 60, 'doc:1'), 'Cache must not hold the stale value'); + } + + public function testFreshSaveAfterPurgeSucceeds(): void + { + $this->cache->purge('doc:1'); + + $generation = $this->cache->getGeneration('doc:1'); + $this->assertNotFalse($this->cache->saveWithLease('doc:1', ['v' => 2], 'doc:1', $generation)); + $this->assertSame(['v' => 2], $this->cache->load('doc:1', 60, 'doc:1')); + } +} From 2428877bcf5f4bcbeb99e8ba37edb7966761a69c Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 16:31:22 +1200 Subject: [PATCH 2/9] fix(cache): guard Pool lease delegation for non-Leasable adapters; drop stale Lua docblock Addresses review on #75: - Pool::getGeneration()/saveWithLease() no longer blindly delegate; they guard with `instanceof Leasable` (mirroring Sharding) and fall back to '0' / unconditional save(), so a pool holding a non-Leasable adapter (Filesystem, Memory, Memcached, None, ...) no longer triggers a "Call to undefined method" fatal. Covered by a new PoolTest case (the pool there holds Filesystem). - Remove the stale `ARGV[4]=generation ttl seconds` line from the LUA_SAVE_WITH_LEASE docblock; the save script takes only ARGV[1..3]. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Pool.php | 15 ++++++++------- src/Cache/Adapter/Redis.php | 2 +- tests/Cache/E2E/PoolTest.php | 10 ++++++++++ 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/src/Cache/Adapter/Pool.php b/src/Cache/Adapter/Pool.php index 0b98d1e833..a2f8b3c367 100644 --- a/src/Cache/Adapter/Pool.php +++ b/src/Cache/Adapter/Pool.php @@ -62,12 +62,9 @@ class Pool implements Adapter, Leasable public function getGeneration(string $key): string { - /** - * @var string $result - */ - $result = $this->delegate(__FUNCTION__, \func_get_args()); - - return $result; + return $this->pool->use(function (Adapter $adapter) use ($key): string { + return $adapter instanceof Leasable ? $adapter->getGeneration($key) : '0'; + }); } public function saveWithLease(string $key, array|string $data, string $hash, string $generation): bool|string|array @@ -75,7 +72,11 @@ class Pool implements Adapter, Leasable /** * @var bool|string|array $result */ - $result = $this->delegate(__FUNCTION__, \func_get_args()); + $result = $this->pool->use(function (Adapter $adapter) use ($key, $data, $hash, $generation) { + return $adapter instanceof Leasable + ? $adapter->saveWithLease($key, $data, $hash, $generation) + : $adapter->save($key, $data, $hash); + }); return $result; } diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index bd7da6463d..8d586a29e3 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -17,7 +17,7 @@ class Redis implements Adapter, Leasable, Retryable /** * Save $hash field into hash $key only when generation key still equals the * caller's token. KEYS[1]=key, KEYS[2]=generationKey; ARGV[1]=hash, - * ARGV[2]=value, ARGV[3]=expected generation, ARGV[4]=generation ttl seconds. + * ARGV[2]=value, ARGV[3]=expected generation. */ private const LUA_SAVE_WITH_LEASE = <<<'LUA' local current = redis.call('GET', KEYS[2]) diff --git a/tests/Cache/E2E/PoolTest.php b/tests/Cache/E2E/PoolTest.php index b52c7790ee..90663533cd 100644 --- a/tests/Cache/E2E/PoolTest.php +++ b/tests/Cache/E2E/PoolTest.php @@ -29,4 +29,14 @@ class PoolTest extends Base self::$cache->save('test', 'test'); $this->assertEquals(4, self::$cache->getSize()); } + + public function testLeaseFallbackForNonLeasableAdapter(): void + { + // The pool holds Filesystem adapters, which are not Leasable. The Pool + // adapter must degrade gracefully (no "Call to undefined method" fatal): + // getGeneration() returns '0' and saveWithLease() falls back to save(). + $this->assertSame('0', self::$cache->getGeneration('lease:fallback')); + $this->assertNotFalse(self::$cache->saveWithLease('lease:fallback', 'value', 'lease:fallback', '0')); + $this->assertSame('value', self::$cache->load('lease:fallback', 60, 'lease:fallback')); + } } From 48c728948bc1eb8ff6715883ecf184c99341c544 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 17:39:52 +1200 Subject: [PATCH 3/9] =?UTF-8?q?fix(cache):=20harden=20lease=20=E2=80=94=20?= =?UTF-8?q?persist=20generation,=20preserve=20purge()=20return,=20reserved?= =?UTF-8?q?=20key,=20decorator=20support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Second review round on #75: - Generation marker no longer expires (was 1d TTL). A long-TTL reader whose marker expired before saveWithLease() could have a stale write accepted; the marker must outlive any reader, so it persists. - purge() returns the DEL result again (number of value keys removed), not the INCR, preserving the documented false-for-missing-key semantics. - Generation markers use a reserved key prefix (`_utopia_cache_gen:`) instead of a `:__gen` suffix, so they cannot collide with a real cache entry (a hash) and cause WRONGTYPE errors. - CircuitBreaker now implements Leasable and delegates to the wrapped adapter, so a CircuitBreaker-wrapped Redis keeps lease semantics instead of silently falling back to an unconditional save. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/CircuitBreaker.php | 26 ++++++++++++++++++- src/Cache/Adapter/Redis.php | 31 +++++++++++++---------- tests/Cache/E2E/Redis/LeasableTest.php | 8 ++++++ tests/Cache/E2E/tests/pool/lease:fallback | 1 + 4 files changed, 52 insertions(+), 14 deletions(-) create mode 100644 tests/Cache/E2E/tests/pool/lease:fallback diff --git a/src/Cache/Adapter/CircuitBreaker.php b/src/Cache/Adapter/CircuitBreaker.php index 4e79c91059..fa9275936e 100644 --- a/src/Cache/Adapter/CircuitBreaker.php +++ b/src/Cache/Adapter/CircuitBreaker.php @@ -7,7 +7,7 @@ use Utopia\Cache\Feature; use Utopia\CircuitBreaker\CircuitBreaker as UtopiaCircuitBreaker; use Utopia\Telemetry\Adapter as Telemetry; -class CircuitBreaker implements Adapter, Feature\Telemetry +class CircuitBreaker implements Adapter, Feature\Leasable, Feature\Telemetry { public function __construct( private readonly Adapter $adapter, @@ -45,6 +45,30 @@ class CircuitBreaker implements Adapter, Feature\Telemetry return $result; } + public function getGeneration(string $key): string + { + if (! $this->adapter instanceof Feature\Leasable) { + return '0'; + } + + /** @var string $result */ + $result = $this->delegate(__FUNCTION__, \func_get_args(), '0'); + + return $result; + } + + public function saveWithLease(string $key, array|string $data, string $hash, string $generation): bool|string|array + { + if (! $this->adapter instanceof Feature\Leasable) { + return $this->save($key, $data, $hash); + } + + /** @var bool|string|array $result */ + $result = $this->delegate(__FUNCTION__, \func_get_args(), false); + + return $result; + } + public function touch(string $key, string $hash = ''): bool { /** @var bool $result */ diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 8d586a29e3..e30a911544 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -12,7 +12,12 @@ use Utopia\Cache\Feature\Retryable; class Redis implements Adapter, Leasable, Retryable { - private const GENERATION_SUFFIX = ':__gen'; + /** + * Reserved key namespace for per-key generation markers. Prefixed (not + * suffixed) so a marker can never collide with a real cache entry — which is + * stored as a Redis hash — and trigger a WRONGTYPE error. + */ + private const GENERATION_PREFIX = '_utopia_cache_gen:'; /** * Save $hash field into hash $key only when generation key still equals the @@ -28,19 +33,19 @@ class Redis implements Adapter, Leasable, Retryable LUA; /** - * Atomically drop $key and advance its generation so any in-flight reader - * that read the previous generation cannot re-cache stale data. - * KEYS[1]=key, KEYS[2]=generationKey; ARGV[1]=generation ttl seconds. + * Atomically drop $key and advance its generation, so an in-flight reader + * holding the previous generation cannot re-cache stale data. Returns the + * number of value keys removed, preserving purge() semantics. The generation + * marker never expires: it must outlive any reader still holding an older + * generation (cache entries may be read with very long TTLs). + * KEYS[1]=key, KEYS[2]=generationKey. */ private const LUA_PURGE_BUMP = <<<'LUA' - redis.call('DEL', KEYS[1]) - local gen = redis.call('INCR', KEYS[2]) - redis.call('EXPIRE', KEYS[2], ARGV[1]) - return gen + local deleted = redis.call('DEL', KEYS[1]) + redis.call('INCR', KEYS[2]) + return deleted LUA; - private const GENERATION_TTL = 86400; - /** * @var Client */ @@ -168,7 +173,7 @@ class Redis implements Adapter, Leasable, Retryable public function getGeneration(string $key): string { - $gen = $this->execute(fn () => $this->redis->get($key.self::GENERATION_SUFFIX)); + $gen = $this->execute(fn () => $this->redis->get(self::GENERATION_PREFIX.$key)); return \is_string($gen) ? $gen : '0'; } @@ -187,7 +192,7 @@ class Redis implements Adapter, Leasable, Retryable $value = Envelope::encode($data, time()); $stored = $this->execute(fn () => $this->redis->eval( self::LUA_SAVE_WITH_LEASE, - [$key, $key.self::GENERATION_SUFFIX, $hash, $value, $generation], + [$key, self::GENERATION_PREFIX.$key, $hash, $value, $generation], 2 )); @@ -254,7 +259,7 @@ class Redis implements Adapter, Leasable, Retryable // stale data after this purge. return (bool) $this->execute(fn () => $this->redis->eval( self::LUA_PURGE_BUMP, - [$key, $key.self::GENERATION_SUFFIX, (string) self::GENERATION_TTL], + [$key, self::GENERATION_PREFIX.$key], 2 )); } diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index 3e2ce7c3ff..e9957776f7 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -68,4 +68,12 @@ class LeasableTest extends TestCase $this->assertNotFalse($this->cache->saveWithLease('doc:1', ['v' => 2], 'doc:1', $generation)); $this->assertSame(['v' => 2], $this->cache->load('doc:1', 60, 'doc:1')); } + + public function testPurgePreservesDeletionResult(): void + { + $this->assertFalse($this->cache->purge('doc:absent'), 'Purging a missing key returns false'); + + $this->cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $this->cache->getGeneration('doc:1')); + $this->assertTrue($this->cache->purge('doc:1'), 'Purging an existing key returns true'); + } } diff --git a/tests/Cache/E2E/tests/pool/lease:fallback b/tests/Cache/E2E/tests/pool/lease:fallback new file mode 100644 index 0000000000..2890eead23 --- /dev/null +++ b/tests/Cache/E2E/tests/pool/lease:fallback @@ -0,0 +1 @@ +value \ No newline at end of file From 7da8ea7432db13c50102f5751d8098733ee6e742 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 17:40:44 +1200 Subject: [PATCH 4/9] chore(cache): ignore PoolTest filesystem artifacts, drop accidentally committed one Co-Authored-By: Claude Opus 4.8 --- .gitignore | 3 ++- tests/Cache/E2E/tests/pool/lease:fallback | 1 - 2 files changed, 2 insertions(+), 2 deletions(-) delete mode 100644 tests/Cache/E2E/tests/pool/lease:fallback diff --git a/.gitignore b/.gitignore index 62899f334c..56506c35eb 100755 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /vendor/ /.idea/ .phpunit.result.cache -tests/data \ No newline at end of file +tests/data +tests/Cache/E2E/tests/pool/ diff --git a/tests/Cache/E2E/tests/pool/lease:fallback b/tests/Cache/E2E/tests/pool/lease:fallback deleted file mode 100644 index 2890eead23..0000000000 --- a/tests/Cache/E2E/tests/pool/lease:fallback +++ /dev/null @@ -1 +0,0 @@ -value \ No newline at end of file From 600e39e4e3c8448902c07b1efe02f58c2a50f413 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 17:53:58 +1200 Subject: [PATCH 5/9] fix(cache): exclude generation markers from getSize() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Third review round on #75: the persisted generation markers were counted by getSize() (which returns Redis DBSIZE), so a purge could leave getSize() non-zero after the value was gone, and purging absent keys inflated it. getSize() now subtracts the generation namespace (SCAN over the reserved prefix) so it reports only real cache entries. The generation bump stays unconditional on purge — a reader may have read a row the writer is now deleting before anything was cached, so the generation must advance even when DEL removed nothing (skipping it reintroduced a stale-write window, caught by the existing lease test). Covered by a new size test. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 27 ++++++++++++++++++++------ tests/Cache/E2E/Redis/LeasableTest.php | 15 ++++++++++++++ 2 files changed, 36 insertions(+), 6 deletions(-) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index e30a911544..7d68a0c925 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -34,10 +34,12 @@ class Redis implements Adapter, Leasable, Retryable /** * Atomically drop $key and advance its generation, so an in-flight reader - * holding the previous generation cannot re-cache stale data. Returns the - * number of value keys removed, preserving purge() semantics. The generation - * marker never expires: it must outlive any reader still holding an older - * generation (cache entries may be read with very long TTLs). + * holding the previous generation cannot re-cache stale data. The bump is + * unconditional: a reader may have read a row the writer is now deleting + * before anything was cached, so the generation must move even when DEL + * removed nothing. Returns the number of value keys removed, preserving + * purge() semantics. The marker never expires (it must outlive any reader + * holding an older generation); getSize() excludes markers from the count. * KEYS[1]=key, KEYS[2]=generationKey. */ private const LUA_PURGE_BUMP = <<<'LUA' @@ -293,10 +295,23 @@ class Redis implements Adapter, Leasable, Retryable */ public function getSize(): int { - /** @var int */ + /** @var int $size */ $size = $this->execute(fn () => $this->redis->dbSize()); - return $size; + // Generation markers are internal bookkeeping, not cache entries, so + // exclude them from the reported size. + $generations = 0; + $iterator = null; + do { + $keys = $this->execute(function () use (&$iterator) { + return $this->redis->scan($iterator, self::GENERATION_PREFIX.'*', 1000); + }); + if (\is_array($keys)) { + $generations += \count($keys); + } + } while ($iterator > 0); + + return \max(0, $size - $generations); } /** diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index e9957776f7..8549d03cb0 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -76,4 +76,19 @@ class LeasableTest extends TestCase $this->cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $this->cache->getGeneration('doc:1')); $this->assertTrue($this->cache->purge('doc:1'), 'Purging an existing key returns true'); } + + public function testSizeExcludesGenerationMarkers(): void + { + $this->cache->flush(); + $this->cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $this->cache->getGeneration('doc:1')); + $this->assertSame(1, $this->cache->getSize()); + + // A purge writes a generation marker; it must be excluded from the size. + $this->cache->purge('doc:absent'); + $this->assertSame(1, $this->cache->getSize(), 'Generation markers must not inflate the reported size'); + + // After a real purge the marker persists but must not count as an entry. + $this->cache->purge('doc:1'); + $this->assertSame(0, $this->cache->getSize(), 'Generation markers must not count toward cache size'); + } } From 56dad6d6855c3955cfb555694f1356c3c9e3b6eb Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 21:51:53 +1200 Subject: [PATCH 6/9] spike(cache): store generation in-hash (single-key lease) instead of a sidecar key MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Alternative to the sidecar-key generation in #75, for comparison. The generation lives in a reserved field (`__utopia_gen__`) inside the value's own hash, so every lease op is single-key: - saveWithLease / purge are single-key Lua scripts → one shard → correct under Redis Cluster and multi-threaded backends (Dragonfly) with no cross-shard span. - No sidecar key → deletes the reserved-prefix collision handling and the getSize() prefix-scan exclusion entirely. Interface is unchanged (same getGeneration + saveWithLease). Trade-offs vs the sidecar approach: - getSize() can no longer cleanly exclude the generation: a purged key keeps a tiny gen-only hash until re-cached, so DBSIZE slightly over-counts purged-but-not-yet-recached keys (filtering would need an O(N) scan). - purge() does a small HLEN/HEXISTS dance to keep "true iff a value was removed". Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 79 +++++++++++++------------- tests/Cache/E2E/Redis/LeasableTest.php | 18 +++--- 2 files changed, 49 insertions(+), 48 deletions(-) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 7d68a0c925..6cc7cb796a 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -13,19 +13,22 @@ use Utopia\Cache\Feature\Retryable; class Redis implements Adapter, Leasable, Retryable { /** - * Reserved key namespace for per-key generation markers. Prefixed (not - * suffixed) so a marker can never collide with a real cache entry — which is - * stored as a Redis hash — and trigger a WRONGTYPE error. + * Reserved hash field that holds a key's generation alongside its value + * fields. Keeping the generation inside the value's own hash makes every + * lease operation single-key (one shard): no sidecar key to collide with or + * scan, and the scripts stay correct under Redis Cluster / multi-threaded + * backends (e.g. Dragonfly), where a multi-key script would span shards. + * Callers must not use this as a cache hash/field. */ - private const GENERATION_PREFIX = '_utopia_cache_gen:'; + private const GENERATION_FIELD = '__utopia_gen__'; /** - * Save $hash field into hash $key only when generation key still equals the - * caller's token. KEYS[1]=key, KEYS[2]=generationKey; ARGV[1]=hash, + * Save $hash field into hash $key only when the key's generation field still + * equals the caller's token. Single-key. KEYS[1]=key; ARGV[1]=hash, * ARGV[2]=value, ARGV[3]=expected generation. */ private const LUA_SAVE_WITH_LEASE = <<<'LUA' - local current = redis.call('GET', KEYS[2]) + local current = redis.call('HGET', KEYS[1], '__utopia_gen__') if current == false then current = '0' end if current ~= ARGV[3] then return 0 end redis.call('HSET', KEYS[1], ARGV[1], ARGV[2]) @@ -33,19 +36,23 @@ class Redis implements Adapter, Leasable, Retryable LUA; /** - * Atomically drop $key and advance its generation, so an in-flight reader - * holding the previous generation cannot re-cache stale data. The bump is - * unconditional: a reader may have read a row the writer is now deleting - * before anything was cached, so the generation must move even when DEL - * removed nothing. Returns the number of value keys removed, preserving - * purge() semantics. The marker never expires (it must outlive any reader - * holding an older generation); getSize() excludes markers from the count. - * KEYS[1]=key, KEYS[2]=generationKey. + * Drop $key's value fields and advance its generation in one step, so an + * in-flight reader holding the previous generation cannot re-cache stale + * data. The bump is unconditional: a reader may have read a row the writer is + * now deleting before anything was cached, so the generation must move even + * when nothing was cached. Returns the number of value fields removed (the + * generation field is excluded), preserving purge() semantics. The + * generation field is the only thing that survives a purge, so it outlives + * any reader holding an older generation. Single-key. KEYS[1]=key. */ private const LUA_PURGE_BUMP = <<<'LUA' - local deleted = redis.call('DEL', KEYS[1]) - redis.call('INCR', KEYS[2]) - return deleted + local field = '__utopia_gen__' + local removed = redis.call('HLEN', KEYS[1]) - redis.call('HEXISTS', KEYS[1], field) + local current = redis.call('HGET', KEYS[1], field) + local next = (tonumber(current) or 0) + 1 + redis.call('DEL', KEYS[1]) + redis.call('HSET', KEYS[1], field, next) + return removed LUA; /** @@ -175,7 +182,7 @@ class Redis implements Adapter, Leasable, Retryable public function getGeneration(string $key): string { - $gen = $this->execute(fn () => $this->redis->get(self::GENERATION_PREFIX.$key)); + $gen = $this->execute(fn () => $this->redis->hGet($key, self::GENERATION_FIELD)); return \is_string($gen) ? $gen : '0'; } @@ -194,8 +201,8 @@ class Redis implements Adapter, Leasable, Retryable $value = Envelope::encode($data, time()); $stored = $this->execute(fn () => $this->redis->eval( self::LUA_SAVE_WITH_LEASE, - [$key, self::GENERATION_PREFIX.$key, $hash, $value, $generation], - 2 + [$key, $hash, $value, $generation], + 1 )); return $stored ? $data : false; @@ -256,13 +263,13 @@ class Redis implements Adapter, Leasable, Retryable return (bool) $this->execute(fn () => $this->redis->hdel($key, $hash)); } - // Drop the key and advance its generation in one atomic step (Redis Lua) - // so an in-flight reader holding the previous generation cannot re-cache - // stale data after this purge. + // Drop the value fields and advance the in-hash generation in one atomic + // step (single-key Redis Lua) so an in-flight reader holding the previous + // generation cannot re-cache stale data after this purge. return (bool) $this->execute(fn () => $this->redis->eval( self::LUA_PURGE_BUMP, - [$key, self::GENERATION_PREFIX.$key], - 2 + [$key], + 1 )); } @@ -295,23 +302,15 @@ class Redis implements Adapter, Leasable, Retryable */ public function getSize(): int { + // Trade-off of the in-hash generation: a purged key keeps a tiny hash + // holding only its generation field until it is re-cached, so it still + // counts here. Filtering those out would need an O(N) scan with a per-key + // HLEN check; for a diagnostic counter that isn't worth it, so DBSIZE may + // slightly over-count purged-but-not-yet-recached keys. /** @var int $size */ $size = $this->execute(fn () => $this->redis->dbSize()); - // Generation markers are internal bookkeeping, not cache entries, so - // exclude them from the reported size. - $generations = 0; - $iterator = null; - do { - $keys = $this->execute(function () use (&$iterator) { - return $this->redis->scan($iterator, self::GENERATION_PREFIX.'*', 1000); - }); - if (\is_array($keys)) { - $generations += \count($keys); - } - } while ($iterator > 0); - - return \max(0, $size - $generations); + return $size; } /** diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index 8549d03cb0..e1a46b0df9 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -77,18 +77,20 @@ class LeasableTest extends TestCase $this->assertTrue($this->cache->purge('doc:1'), 'Purging an existing key returns true'); } - public function testSizeExcludesGenerationMarkers(): void + public function testPurgeDropsValueButKeepsGenerationField(): void { $this->cache->flush(); $this->cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $this->cache->getGeneration('doc:1')); - $this->assertSame(1, $this->cache->getSize()); + $this->assertSame(['v' => 1], $this->cache->load('doc:1', 60, 'doc:1')); - // A purge writes a generation marker; it must be excluded from the size. - $this->cache->purge('doc:absent'); - $this->assertSame(1, $this->cache->getSize(), 'Generation markers must not inflate the reported size'); - - // After a real purge the marker persists but must not count as an entry. $this->cache->purge('doc:1'); - $this->assertSame(0, $this->cache->getSize(), 'Generation markers must not count toward cache size'); + + // The value is gone, but the key keeps its in-hash generation so a stale + // reader is still rejected. The residual hash therefore persists and is + // counted by getSize() — the documented trade-off of storing the + // generation in-hash rather than in a separately-countable sidecar key. + $this->assertFalse($this->cache->load('doc:1', 60, 'doc:1')); + $this->assertSame('1', $this->cache->getGeneration('doc:1')); + $this->assertSame(1, $this->cache->getSize()); } } From 6f0557b42af9c544be30d50f04c24db2408e0601 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 22:27:55 +1200 Subject: [PATCH 7/9] fix(cache): protect the reserved generation field from public hash operations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review on #75 (in-hash generation): the generation lives in a reserved field (__utopia_gen__) inside the value's own hash, but callers can address any field via load/save/touch/purge. A caller writing under that field would overwrite the generation with a cache envelope; the next purge then read a non-numeric value, fell back through `tonumber(current) or 0`, and reset the generation — reviving stale lease tokens. Reject the reserved field on every public field path (load/save/saveWithLease/ touch/purge-with-hash) so it can't be read, written, or deleted by callers, and can only be managed by the lease scripts. Covered by a regression test. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 32 ++++++++++++++++++++++++++ tests/Cache/E2E/Redis/LeasableTest.php | 20 ++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 6cc7cb796a..1df8d119d3 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -145,6 +145,13 @@ class Redis implements Adapter, Leasable, Retryable $hash = $key; } + // The generation lives in this same hash; never let a caller read, write + // or delete it through the public field API, or they could reset the + // generation and revive stale lease tokens. + if ($hash === self::GENERATION_FIELD) { + return false; + } + $redis_string = $this->execute(fn () => $this->redis->hGet($key, $hash)); if (! is_string($redis_string)) { @@ -170,6 +177,13 @@ class Redis implements Adapter, Leasable, Retryable $hash = $key; } + // The generation lives in this same hash; never let a caller read, write + // or delete it through the public field API, or they could reset the + // generation and revive stale lease tokens. + if ($hash === self::GENERATION_FIELD) { + return false; + } + try { $value = Envelope::encode($data, time()); $this->execute(fn () => $this->redis->hSet($key, $hash, $value)); @@ -197,6 +211,13 @@ class Redis implements Adapter, Leasable, Retryable $hash = $key; } + // The generation lives in this same hash; never let a caller read, write + // or delete it through the public field API, or they could reset the + // generation and revive stale lease tokens. + if ($hash === self::GENERATION_FIELD) { + return false; + } + try { $value = Envelope::encode($data, time()); $stored = $this->execute(fn () => $this->redis->eval( @@ -222,6 +243,13 @@ class Redis implements Adapter, Leasable, Retryable $hash = $key; } + // The generation lives in this same hash; never let a caller read, write + // or delete it through the public field API, or they could reset the + // generation and revive stale lease tokens. + if ($hash === self::GENERATION_FIELD) { + return false; + } + $redis_string = $this->execute(fn () => $this->redis->hGet($key, $hash)); if (! is_string($redis_string)) { @@ -260,6 +288,10 @@ class Redis implements Adapter, Leasable, Retryable public function purge(string $key, string $hash = ''): bool { if (! empty($hash)) { + if ($hash === self::GENERATION_FIELD) { + return false; + } + return (bool) $this->execute(fn () => $this->redis->hdel($key, $hash)); } diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index e1a46b0df9..e2ae7389a7 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -93,4 +93,24 @@ class LeasableTest extends TestCase $this->assertSame('1', $this->cache->getGeneration('doc:1')); $this->assertSame(1, $this->cache->getSize()); } + + public function testReservedGenerationFieldIsProtected(): void + { + $this->cache->flush(); + $this->cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $this->cache->getGeneration('doc:1')); + $this->cache->purge('doc:1'); + $this->assertSame('1', $this->cache->getGeneration('doc:1')); + + // Reading, writing, or deleting the reserved generation field through the + // public API must be rejected, so a caller can't clobber it and reset the + // generation sequence (which would revive stale lease tokens). + $this->assertFalse($this->cache->save('doc:1', 'attacker', '__utopia_gen__')); + $this->assertFalse($this->cache->saveWithLease('doc:1', 'attacker', '__utopia_gen__', '1')); + $this->assertFalse($this->cache->purge('doc:1', '__utopia_gen__')); + $this->assertFalse($this->cache->load('doc:1', 60, '__utopia_gen__')); + + // Generation is untouched, so an old token is still rejected. + $this->assertSame('1', $this->cache->getGeneration('doc:1')); + $this->assertFalse($this->cache->saveWithLease('doc:1', 'stale', 'doc:1', '0')); + } } From de42073a963557cc55736d984a6950d802b6ea67 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 22:31:34 +1200 Subject: [PATCH 8/9] fix(cache): hide the reserved generation field from list() list() (hKeys) would surface the internal __utopia_gen__ field as a listable cache field, leaking the lease internals to callers. Filter it out so the reserved field is fully invisible to the public API. Covered by a test. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 3 ++- tests/Cache/E2E/Redis/LeasableTest.php | 12 ++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 1df8d119d3..67dd8ee979 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -277,7 +277,8 @@ class Redis implements Adapter, Leasable, Retryable return []; } - return $keys; + // Don't expose the internal generation field as a listable cache field. + return \array_values(\array_filter($keys, fn (string $field): bool => $field !== self::GENERATION_FIELD)); } /** diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index e2ae7389a7..187c352131 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -113,4 +113,16 @@ class LeasableTest extends TestCase $this->assertSame('1', $this->cache->getGeneration('doc:1')); $this->assertFalse($this->cache->saveWithLease('doc:1', 'stale', 'doc:1', '0')); } + + public function testListHidesGenerationField(): void + { + $this->cache->flush(); + $this->cache->saveWithLease('doc:1', ['v' => 1], 'field-a', $this->cache->getGeneration('doc:1')); + $this->assertSame(['field-a'], $this->cache->list('doc:1')); + + // After a purge the key holds only its internal generation field, which + // must not surface as a listable cache field. + $this->cache->purge('doc:1'); + $this->assertSame([], $this->cache->list('doc:1')); + } } From e02fa05594c145aee6e8cb5124fd3a46c8aff478 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 23 Jun 2026 22:43:23 +1200 Subject: [PATCH 9/9] fix(cache): advance the generation on field-level purges too MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review on #75: purge($key, $hash) only ran HDEL on the field and left the per-key generation untouched, so the lease was bypassed for hashed entries — a reader could capture the generation, a concurrent field-purge would delete the field without advancing the generation, and the reader's saveWithLease(..., $hash, capturedGeneration) would still pass the CAS and re-cache stale data. Field-level purge now deletes the field and advances the generation in one single-key Lua step (LUA_PURGE_FIELD), mirroring the full-purge bump, while preserving purge()'s deletion-result return. Over-invalidating sibling fields of the same key is safe: it only costs cache misses, never staleness. Covered by a regression test. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 20 +++++++++++++++++++- tests/Cache/E2E/Redis/LeasableTest.php | 16 ++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 67dd8ee979..ae14401f98 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -55,6 +55,20 @@ class Redis implements Adapter, Leasable, Retryable return removed LUA; + /** + * Delete a single $hash field and advance the key's generation in one step, + * so a field-level purge invalidates in-flight leases just like a full purge. + * Returns the number of fields removed, preserving purge()'s deletion-result + * semantics. Single-key. KEYS[1]=key; ARGV[1]=field. + */ + private const LUA_PURGE_FIELD = <<<'LUA' + local removed = redis.call('HDEL', KEYS[1], ARGV[1]) + local current = redis.call('HGET', KEYS[1], '__utopia_gen__') + local next = (tonumber(current) or 0) + 1 + redis.call('HSET', KEYS[1], '__utopia_gen__', next) + return removed + LUA; + /** * @var Client */ @@ -293,7 +307,11 @@ class Redis implements Adapter, Leasable, Retryable return false; } - return (bool) $this->execute(fn () => $this->redis->hdel($key, $hash)); + return (bool) $this->execute(fn () => $this->redis->eval( + self::LUA_PURGE_FIELD, + [$key, $hash], + 1 + )); } // Drop the value fields and advance the in-hash generation in one atomic diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index 187c352131..e33ac11aae 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -41,6 +41,22 @@ class LeasableTest extends TestCase $this->assertNotSame($before, $this->cache->getGeneration('doc:1')); } + public function testHashPurgeAdvancesGeneration(): void + { + $captured = $this->cache->getGeneration('doc:1'); + $this->assertNotFalse($this->cache->saveWithLease('doc:1', ['v' => 1], 'field-a', $captured)); + + // A field-level purge must advance the per-key generation, just like a + // full purge, or the lease is bypassed for hashed entries. + $this->assertTrue($this->cache->purge('doc:1', 'field-a')); + $this->assertNotSame($captured, $this->cache->getGeneration('doc:1')); + + // A reader holding the pre-purge generation can no longer re-cache a + // stale field via saveWithLease. + $this->assertFalse($this->cache->saveWithLease('doc:1', ['stale' => true], 'field-a', $captured)); + $this->assertFalse($this->cache->load('doc:1', 60, 'field-a')); + } + /** * The core read-after-write guarantee: a reader that captured the generation * BEFORE a concurrent purge must NOT be able to re-cache its now-stale value