diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index d93f9afe9d..3108583e8b 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -89,8 +89,9 @@ jobs:
- { name: Memcached, suite: memcached, services: 'memcached', wait: 3 }
- { name: Hazelcast, suite: hazelcast, services: 'hazelcast', wait: 30 }
- { name: Sharding, suite: sharding, services: 'shardA shardB shardC', wait: 0 }
- - { name: Redis, suite: redis, services: 'redis', wait: 0 }
- - { name: RedisCluster, suite: redis-cluster, services: 'redis-cluster', wait: 0 }
+ - { name: Redis, suite: redis, services: 'redis', wait: 0 }
+ - { name: RedisMultiplexing, suite: redis-multiplexing, services: 'redis', wait: 0 }
+ - { name: RedisCluster, suite: redis-cluster, services: 'redis-cluster', wait: 0 }
steps:
- name: Checkout repository
uses: actions/checkout@v3
diff --git a/phpunit.xml b/phpunit.xml
index c9029ccf90..c1e27d05b2 100644
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -42,9 +42,15 @@
./tests/Cache/E2E/Redis
./tests/Cache/E2E/Redis/RedisClusterTest.php
+ ./tests/Cache/E2E/Redis/MultiplexingTest.php
+ ./tests/Cache/E2E/Redis/LeasableMultiplexingTest.php
./tests/Cache/E2E/Redis/RedisClusterTest.php
+
+ ./tests/Cache/E2E/Redis/MultiplexingTest.php
+ ./tests/Cache/E2E/Redis/LeasableMultiplexingTest.php
+
diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php
index fff5949edd..e3429194d1 100644
--- a/src/Cache/Adapter/Redis.php
+++ b/src/Cache/Adapter/Redis.php
@@ -7,99 +7,11 @@ use Redis as Client;
use Throwable;
use Utopia\Cache\Adapter;
use Utopia\Cache\Adapter\Redis\Envelope;
-use Utopia\Cache\Feature\Leasable;
+use Utopia\Cache\Adapter\Redis\Leasable;
use Utopia\Cache\Feature\Retryable;
-class Redis implements Adapter, Leasable, Retryable
+class Redis extends Leasable implements Adapter, Retryable
{
- /**
- * 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_FIELD = '__utopia_gen__';
-
- /**
- * Reserved hash field: epoch-µs deadline until which saveWithLease() is
- * refused after a purge, so a reader whose DB read lagged the write can't
- * re-cache stale data under a still-valid generation token. Not a cache field.
- */
- private const TOMBSTONE_FIELD = '__utopia_tomb__';
-
- /**
- * Save $hash only if the generation token matches and the key is past its
- * post-purge tombstone. Single-key. KEYS[1]=key; ARGV[1]=hash, ARGV[2]=value,
- * ARGV[3]=expected generation, ARGV[4]=grace window ms (0 = tombstone off).
- */
- private const LUA_SAVE_WITH_LEASE = <<<'LUA'
- local current = redis.call('HGET', KEYS[1], '__utopia_gen__')
- if current == false then current = '0' end
- if current ~= ARGV[3] then return 0 end
- local window = tonumber(ARGV[4]) or 0
- if window > 0 then
- local tomb = redis.call('HGET', KEYS[1], '__utopia_tomb__')
- if tomb ~= false then
- local deadline = tonumber(tomb)
- if deadline ~= nil then
- local t = redis.call('TIME')
- local now = tonumber(t[1]) * 1000000 + tonumber(t[2])
- -- 2nd clause ignores a deadline left by a since-rewound clock
- if now < deadline and (deadline - now) <= window * 1000 then
- return 0
- end
- end
- redis.call('HDEL', KEYS[1], '__utopia_tomb__')
- end
- end
- redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
- return 1
- LUA;
-
- /**
- * Drop $key's value fields, advance its generation (so an in-flight reader
- * can't re-cache stale data), and stamp the tombstone when ARGV[1] > 0.
- * Returns value fields removed (reserved fields excluded), preserving purge()
- * semantics. Single-key. KEYS[1]=key; ARGV[1]=grace window ms.
- */
- private const LUA_PURGE_BUMP = <<<'LUA'
- local gen = '__utopia_gen__'
- local tomb = '__utopia_tomb__'
- local removed = redis.call('HLEN', KEYS[1]) - redis.call('HEXISTS', KEYS[1], gen) - redis.call('HEXISTS', KEYS[1], tomb)
- local current = redis.call('HGET', KEYS[1], gen)
- local next = (tonumber(current) or 0) + 1
- redis.call('DEL', KEYS[1])
- redis.call('HSET', KEYS[1], gen, next)
- local window = tonumber(ARGV[1]) or 0
- if window > 0 then
- local t = redis.call('TIME')
- local now = tonumber(t[1]) * 1000000 + tonumber(t[2])
- redis.call('HSET', KEYS[1], tomb, now + window * 1000)
- end
- return removed
- LUA;
-
- /**
- * Delete one $hash field, advance the generation, and stamp the tombstone when
- * ARGV[2] > 0 (key-level, so it also briefly blocks re-caching sibling fields).
- * Single-key. KEYS[1]=key; ARGV[1]=field, ARGV[2]=grace window ms.
- */
- 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)
- local window = tonumber(ARGV[2]) or 0
- if window > 0 then
- local t = redis.call('TIME')
- local now = tonumber(t[1]) * 1000000 + tonumber(t[2])
- redis.call('HSET', KEYS[1], '__utopia_tomb__', now + window * 1000)
- end
- return removed
- LUA;
-
/**
* @var Client
*/
@@ -109,12 +21,6 @@ class Redis implements Adapter, Leasable, Retryable
private int $retryDelay = 1000; // milliseconds
- /**
- * Milliseconds after a purge during which saveWithLease() is refused. Size to
- * the worst-case read-after-write staleness; 0 disables the tombstone.
- */
- private int $leaseGraceWindow = 0;
-
private string $host;
private int $port;
@@ -184,28 +90,6 @@ class Redis implements Adapter, Leasable, Retryable
return $this;
}
- /**
- * @param int $milliseconds grace window after a purge (0 disables the tombstone)
- * @return self
- */
- public function setLeaseGraceWindow(int $milliseconds): self
- {
- $this->leaseGraceWindow = max(0, $milliseconds);
-
- return $this;
- }
-
- public function getLeaseGraceWindow(): int
- {
- return $this->leaseGraceWindow;
- }
-
- /** Reserved internal fields must never be reachable through the public field API. */
- private function isReserved(string $hash): bool
- {
- return $hash === self::GENERATION_FIELD || $hash === self::TOMBSTONE_FIELD;
- }
-
/**
* @param string $key
* @param int $ttl time in seconds
@@ -261,41 +145,6 @@ class Redis implements Adapter, Leasable, Retryable
}
}
- public function getGeneration(string $key): string
- {
- $gen = $this->execute(fn () => $this->redis->hGet($key, self::GENERATION_FIELD));
-
- 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;
- }
-
- if ($this->isReserved($hash)) {
- return false;
- }
-
- try {
- $value = Envelope::encode($data, time());
- $stored = $this->execute(fn () => $this->redis->eval(
- self::LUA_SAVE_WITH_LEASE,
- [$key, $hash, $value, $generation, $this->leaseGraceWindow],
- 1
- ));
-
- return $stored ? $data : false;
- } catch (Throwable $th) {
- return false;
- }
- }
-
/**
* @param string $key
* @param string $hash optional
@@ -342,30 +191,14 @@ class Redis implements Adapter, Leasable, Retryable
return \array_values(\array_filter($keys, fn (string $field): bool => ! $this->isReserved($field)));
}
- /**
- * @param string $key
- * @param string $hash optional
- * @return bool
- */
- public function purge(string $key, string $hash = ''): bool
+ protected function leaseEval(string $script, string $key, array $args): mixed
{
- if (! empty($hash)) {
- if ($this->isReserved($hash)) {
- return false;
- }
+ return $this->execute(fn () => $this->redis->eval($script, [$key, ...$args], 1));
+ }
- return (bool) $this->execute(fn () => $this->redis->eval(
- self::LUA_PURGE_FIELD,
- [$key, $hash, $this->leaseGraceWindow],
- 1
- ));
- }
-
- return (bool) $this->execute(fn () => $this->redis->eval(
- self::LUA_PURGE_BUMP,
- [$key, $this->leaseGraceWindow],
- 1
- ));
+ protected function leaseHget(string $key, string $field): mixed
+ {
+ return $this->execute(fn () => $this->redis->hGet($key, $field));
}
/**
diff --git a/src/Cache/Adapter/Redis/Leasable.php b/src/Cache/Adapter/Redis/Leasable.php
new file mode 100644
index 0000000000..0c28b8a719
--- /dev/null
+++ b/src/Cache/Adapter/Redis/Leasable.php
@@ -0,0 +1,193 @@
+ 0 then
+ local tomb = redis.call('HGET', KEYS[1], '__utopia_tomb__')
+ if tomb ~= false then
+ local deadline = tonumber(tomb)
+ if deadline ~= nil then
+ local t = redis.call('TIME')
+ local now = tonumber(t[1]) * 1000000 + tonumber(t[2])
+ -- 2nd clause ignores a deadline left by a since-rewound clock
+ if now < deadline and (deadline - now) <= window * 1000 then
+ return 0
+ end
+ end
+ redis.call('HDEL', KEYS[1], '__utopia_tomb__')
+ end
+ end
+ redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+ return 1
+ LUA;
+
+ /**
+ * Drop $key's value fields, advance its generation (so an in-flight reader
+ * can't re-cache stale data), and stamp the tombstone when ARGV[1] > 0.
+ * Returns value fields removed (reserved fields excluded), preserving purge()
+ * semantics. Single-key. KEYS[1]=key; ARGV[1]=grace window ms.
+ */
+ protected const LUA_PURGE_BUMP = <<<'LUA'
+ local gen = '__utopia_gen__'
+ local tomb = '__utopia_tomb__'
+ local removed = redis.call('HLEN', KEYS[1]) - redis.call('HEXISTS', KEYS[1], gen) - redis.call('HEXISTS', KEYS[1], tomb)
+ local current = redis.call('HGET', KEYS[1], gen)
+ local next = (tonumber(current) or 0) + 1
+ redis.call('DEL', KEYS[1])
+ redis.call('HSET', KEYS[1], gen, next)
+ local window = tonumber(ARGV[1]) or 0
+ if window > 0 then
+ local t = redis.call('TIME')
+ local now = tonumber(t[1]) * 1000000 + tonumber(t[2])
+ redis.call('HSET', KEYS[1], tomb, now + window * 1000)
+ end
+ return removed
+ LUA;
+
+ /**
+ * Delete one $hash field, advance the generation, and stamp the tombstone when
+ * ARGV[2] > 0 (key-level, so it also briefly blocks re-caching sibling fields).
+ * Single-key. KEYS[1]=key; ARGV[1]=field, ARGV[2]=grace window ms.
+ */
+ protected 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)
+ local window = tonumber(ARGV[2]) or 0
+ if window > 0 then
+ local t = redis.call('TIME')
+ local now = tonumber(t[1]) * 1000000 + tonumber(t[2])
+ redis.call('HSET', KEYS[1], '__utopia_tomb__', now + window * 1000)
+ end
+ return removed
+ LUA;
+
+ /**
+ * Milliseconds after a purge during which saveWithLease() is refused. Size to
+ * the worst-case read-after-write staleness; 0 disables the tombstone.
+ */
+ protected int $leaseGraceWindow = 0;
+
+ /**
+ * @param int $milliseconds grace window after a purge (0 disables the tombstone)
+ */
+ public function setLeaseGraceWindow(int $milliseconds): static
+ {
+ $this->leaseGraceWindow = max(0, $milliseconds);
+
+ return $this;
+ }
+
+ public function getLeaseGraceWindow(): int
+ {
+ return $this->leaseGraceWindow;
+ }
+
+ public function getGeneration(string $key): string
+ {
+ $gen = $this->leaseHget($key, self::GENERATION_FIELD);
+
+ 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;
+ }
+
+ if ($this->isReserved($hash)) {
+ return false;
+ }
+
+ try {
+ $value = Envelope::encode($data, time());
+ $stored = $this->leaseEval(self::LUA_SAVE_WITH_LEASE, $key, [
+ $hash, $value, $generation, (string) $this->leaseGraceWindow,
+ ]);
+
+ return $stored ? $data : false;
+ } catch (Throwable $th) {
+ return false;
+ }
+ }
+
+ public function purge(string $key, string $hash = ''): bool
+ {
+ if (! empty($hash)) {
+ if ($this->isReserved($hash)) {
+ return false;
+ }
+
+ return (bool) $this->leaseEval(self::LUA_PURGE_FIELD, $key, [$hash, (string) $this->leaseGraceWindow]);
+ }
+
+ return (bool) $this->leaseEval(self::LUA_PURGE_BUMP, $key, [(string) $this->leaseGraceWindow]);
+ }
+
+ /** Reserved internal fields must never be reachable through the public field API. */
+ protected function isReserved(string $hash): bool
+ {
+ return $hash === self::GENERATION_FIELD || $hash === self::TOMBSTONE_FIELD;
+ }
+
+ /**
+ * Run a single-key Redis EVAL — KEYS[1] = $key, ARGV = $args in order — over
+ * the concrete adapter's transport, returning the script's reply.
+ *
+ * @param array $args
+ */
+ abstract protected function leaseEval(string $script, string $key, array $args): mixed;
+
+ /**
+ * HGET $field from hash $key; returns the raw value, or false when absent.
+ */
+ abstract protected function leaseHget(string $key, string $field): mixed;
+}
diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php
index 722d392aca..229bb52606 100644
--- a/src/Cache/Adapter/Redis/Multiplexing.php
+++ b/src/Cache/Adapter/Redis/Multiplexing.php
@@ -23,7 +23,7 @@ use Utopia\Telemetry\UpDownCounter;
* single reader coroutine parses inbound frames and dispatches each one to
* the next pending Channel, exploiting Redis's guarantee of in-order replies.
*/
-class Multiplexing implements Adapter, TelemetryFeature
+class Multiplexing extends Leasable implements Adapter, TelemetryFeature
{
private ?ConnectionContext $connection = null;
@@ -106,6 +106,10 @@ class Multiplexing implements Adapter, TelemetryFeature
$hash = $key;
}
+ if ($this->isReserved($hash)) {
+ return false;
+ }
+
$value = $this->command(['HGET', $key, $hash]);
if (! is_string($value)) {
@@ -125,6 +129,10 @@ class Multiplexing implements Adapter, TelemetryFeature
$hash = $key;
}
+ if ($this->isReserved($hash)) {
+ return false;
+ }
+
$value = Envelope::encode($data, time());
$this->command(['HSET', $key, $hash, $value]);
@@ -137,6 +145,10 @@ class Multiplexing implements Adapter, TelemetryFeature
$hash = $key;
}
+ if ($this->isReserved($hash)) {
+ return false;
+ }
+
$value = $this->command(['HGET', $key, $hash]);
if (! is_string($value)) {
return false;
@@ -161,16 +173,17 @@ class Multiplexing implements Adapter, TelemetryFeature
}
/** @var string[] $keys */
- return $keys;
+ return \array_values(\array_filter($keys, fn (string $field): bool => ! $this->isReserved($field)));
}
- public function purge(string $key, string $hash = ''): bool
+ protected function leaseEval(string $script, string $key, array $args): mixed
{
- if (! empty($hash)) {
- return (bool) $this->command(['HDEL', $key, $hash]);
- }
+ return $this->command(['EVAL', $script, '1', $key, ...$args]);
+ }
- return (bool) $this->command(['DEL', $key]);
+ protected function leaseHget(string $key, string $field): mixed
+ {
+ return $this->command(['HGET', $key, $field]);
}
public function flush(): bool
diff --git a/tests/Cache/E2E/Redis/LeasableMultiplexingTest.php b/tests/Cache/E2E/Redis/LeasableMultiplexingTest.php
new file mode 100644
index 0000000000..98144ead4e
--- /dev/null
+++ b/tests/Cache/E2E/Redis/LeasableMultiplexingTest.php
@@ -0,0 +1,358 @@
+close();
+ }
+ });
+ if ($error !== null) {
+ throw $error;
+ }
+ }
+
+ private function makeCache(): Cache
+ {
+ $this->adapter = new RedisMultiplexing('redis', 6379);
+
+ return new Cache($this->adapter);
+ }
+
+ private function graceCache(int $milliseconds): Cache
+ {
+ $this->adapter = new RedisMultiplexing('redis', 6379);
+ $this->adapter->setLeaseGraceWindow($milliseconds);
+
+ return new Cache($this->adapter);
+ }
+
+ private function close(): void
+ {
+ if (isset($this->adapter)) {
+ $this->adapter->disconnect();
+ }
+ }
+
+ public function testFreshKeyHasZeroGeneration(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $this->assertSame('0', $cache->getGeneration('doc:1'));
+ });
+ }
+
+ public function testSaveWithLeaseStoresWhenGenerationUnchanged(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $generation = $cache->getGeneration('doc:1');
+
+ $this->assertNotFalse($cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $generation));
+ $this->assertSame(['v' => 1], $cache->load('doc:1', 60, 'doc:1'));
+ });
+ }
+
+ public function testPurgeAdvancesGeneration(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $before = $cache->getGeneration('doc:1');
+ $cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $before);
+ $cache->purge('doc:1');
+
+ $this->assertNotSame($before, $cache->getGeneration('doc:1'));
+ });
+ }
+
+ public function testHashPurgeAdvancesGeneration(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $captured = $cache->getGeneration('doc:1');
+ $this->assertNotFalse($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($cache->purge('doc:1', 'field-a'));
+ $this->assertNotSame($captured, $cache->getGeneration('doc:1'));
+
+ // A reader holding the pre-purge generation can no longer re-cache a
+ // stale field via saveWithLease.
+ $this->assertFalse($cache->saveWithLease('doc:1', ['stale' => true], 'field-a', $captured));
+ $this->assertFalse($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
+ * AFTER the purge. Ordering here simulates the race deterministically.
+ */
+ public function testStaleSaveAfterPurgeIsRejected(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $captured = $cache->getGeneration('doc:1');
+
+ // A writer commits and purges; the generation advances.
+ $cache->purge('doc:1');
+
+ // The reader tries to re-cache the value it read before the purge.
+ $result = $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($cache->load('doc:1', 60, 'doc:1'), 'Cache must not hold the stale value');
+ });
+ }
+
+ public function testFreshSaveAfterPurgeSucceeds(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $cache->purge('doc:1');
+
+ $generation = $cache->getGeneration('doc:1');
+ $this->assertNotFalse($cache->saveWithLease('doc:1', ['v' => 2], 'doc:1', $generation));
+ $this->assertSame(['v' => 2], $cache->load('doc:1', 60, 'doc:1'));
+ });
+ }
+
+ public function testPurgePreservesDeletionResult(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $this->assertFalse($cache->purge('doc:absent'), 'Purging a missing key returns false');
+
+ $cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $cache->getGeneration('doc:1'));
+ $this->assertTrue($cache->purge('doc:1'), 'Purging an existing key returns true');
+ });
+ }
+
+ public function testPurgeDropsValueButKeepsGenerationField(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $cache->getGeneration('doc:1'));
+ $this->assertSame(['v' => 1], $cache->load('doc:1', 60, 'doc:1'));
+
+ $cache->purge('doc:1');
+
+ // 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($cache->load('doc:1', 60, 'doc:1'));
+ $this->assertSame('1', $cache->getGeneration('doc:1'));
+ $this->assertSame(1, $cache->getSize());
+ });
+ }
+
+ public function testReservedGenerationFieldIsProtected(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $cache->getGeneration('doc:1'));
+ $cache->purge('doc:1');
+ $this->assertSame('1', $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($cache->save('doc:1', 'attacker', '__utopia_gen__'));
+ $this->assertFalse($cache->saveWithLease('doc:1', 'attacker', '__utopia_gen__', '1'));
+ $this->assertFalse($cache->purge('doc:1', '__utopia_gen__'));
+ $this->assertFalse($cache->load('doc:1', 60, '__utopia_gen__'));
+
+ // Generation is untouched, so an old token is still rejected.
+ $this->assertSame('1', $cache->getGeneration('doc:1'));
+ $this->assertFalse($cache->saveWithLease('doc:1', 'stale', 'doc:1', '0'));
+ });
+ }
+
+ public function testListHidesGenerationField(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->makeCache();
+ $cache->flush();
+
+ $cache->saveWithLease('doc:1', ['v' => 1], 'field-a', $cache->getGeneration('doc:1'));
+ $this->assertSame(['field-a'], $cache->list('doc:1'));
+
+ // After a purge the key holds only its internal generation field, which
+ // must not surface as a listable cache field.
+ $cache->purge('doc:1');
+ $this->assertSame([], $cache->list('doc:1'));
+ });
+ }
+
+ public function testLeaseGraceWindowDefaultsToZero(): void
+ {
+ $this->runCo(function () {
+ $this->adapter = new RedisMultiplexing('redis', 6379);
+ $this->assertSame(0, $this->adapter->getLeaseGraceWindow());
+ });
+ }
+
+ /**
+ * A token-valid save (generation captured post-purge) must still be refused
+ * within the grace window, then allowed once the deadline passes.
+ */
+ public function testTombstoneRejectsTokenValidSaveWithinGraceWindow(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->graceCache(500);
+ $cache->flush();
+
+ $cache->purge('doc:1');
+
+ $generation = $cache->getGeneration('doc:1');
+ $this->assertFalse(
+ $cache->saveWithLease('doc:1', ['stale' => true], 'doc:1', $generation),
+ 'A token-valid save inside the grace window must be refused by the tombstone'
+ );
+ $this->assertFalse($cache->load('doc:1', 60, 'doc:1'), 'Cache must not hold the stale value');
+
+ // Expire the tombstone directly (no sleep) to resume saves. The
+ // multiplexing adapter exposes no raw write, so use a temporary
+ // synchronous php-redis client for this out-of-band poke.
+ $raw = new Redis();
+ $raw->connect('redis', 6379);
+ // Derive from the Redis server clock (what the tombstone Lua uses via
+ // TIME), not the PHP wall clock, so a client/server skew can't flake it.
+ $past = ((int) $raw->time()[0] - 60) * 1000000;
+ $raw->hSet('doc:1', '__utopia_tomb__', (string) $past);
+ $raw->close();
+
+ $this->assertNotFalse(
+ $cache->saveWithLease('doc:1', ['fresh' => true], 'doc:1', $generation),
+ 'After the grace window a token-valid save must succeed'
+ );
+ $this->assertSame(['fresh' => true], $cache->load('doc:1', 60, 'doc:1'));
+
+ $raw = new Redis();
+ $raw->connect('redis', 6379);
+ $lingering = (bool) $raw->hExists('doc:1', '__utopia_tomb__');
+ $raw->close();
+ $this->assertFalse(
+ $lingering,
+ 'The spent tombstone must be dropped on the next save, not linger in the hash'
+ );
+ });
+ }
+
+ /** A field-level purge must open the tombstone too. */
+ public function testFieldPurgeAlsoOpensTombstone(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->graceCache(500);
+ $cache->flush();
+
+ $cache->saveWithLease('doc:1', ['v' => 1], 'field-a', $cache->getGeneration('doc:1'));
+ $cache->purge('doc:1', 'field-a');
+
+ $generation = $cache->getGeneration('doc:1');
+ $this->assertFalse(
+ $cache->saveWithLease('doc:1', ['stale' => true], 'field-a', $generation),
+ 'A token-valid field save inside the grace window must be refused'
+ );
+ $this->assertFalse($cache->load('doc:1', 60, 'field-a'));
+ });
+ }
+
+ public function testListHidesTombstoneField(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->graceCache(500);
+ $cache->flush();
+
+ $cache->saveWithLease('doc:1', ['v' => 1], 'field-a', $cache->getGeneration('doc:1'));
+ $cache->purge('doc:1');
+
+ $this->assertSame([], $cache->list('doc:1'));
+ });
+ }
+
+ public function testReservedTombstoneFieldIsProtected(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->graceCache(500);
+ $cache->flush();
+
+ $this->assertFalse($cache->save('doc:1', 'attacker', '__utopia_tomb__'));
+ $this->assertFalse($cache->saveWithLease('doc:1', 'attacker', '__utopia_tomb__', '0'));
+ $this->assertFalse($cache->purge('doc:1', '__utopia_tomb__'));
+ $this->assertFalse($cache->load('doc:1', 60, '__utopia_tomb__'));
+ });
+ }
+
+ /**
+ * A deadline more than the window ahead of now (a since-rewound clock) must
+ * be ignored, not wedge saves.
+ */
+ public function testTombstoneIgnoresImplausibleFutureDeadline(): void
+ {
+ $this->runCo(function () {
+ $cache = $this->graceCache(500);
+ $cache->flush();
+
+ $cache->purge('doc:1');
+ $generation = $cache->getGeneration('doc:1');
+
+ // 1h-ahead deadline (µs), far beyond the window: a since-rewound clock.
+ // The multiplexing adapter exposes no raw write, so stamp it via a
+ // temporary synchronous php-redis client.
+ $raw = new Redis();
+ $raw->connect('redis', 6379);
+ $farFutureMicros = ((int) $raw->time()[0] + 3600) * 1000000;
+ $raw->hSet('doc:1', '__utopia_tomb__', (string) $farFutureMicros);
+ $raw->close();
+
+ $this->assertNotFalse(
+ $cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $generation),
+ 'An implausibly far-future deadline (backward clock step) must be ignored, not wedge saves'
+ );
+ $this->assertSame(['v' => 1], $cache->load('doc:1', 60, 'doc:1'));
+ });
+ }
+}
diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php
index cb6991bfa2..18f0be8b6d 100644
--- a/tests/Cache/E2E/Redis/LeasableTest.php
+++ b/tests/Cache/E2E/Redis/LeasableTest.php
@@ -181,8 +181,10 @@ class LeasableTest extends TestCase
);
$this->assertFalse($cache->load('doc:1', 60, 'doc:1'), 'Cache must not hold the stale value');
- // Expire the tombstone directly (no sleep) to resume saves.
- $past = ((int) \time() - 60) * 1000000;
+ // Expire the tombstone directly (no sleep) to resume saves. Derive from the
+ // Redis server clock (what the tombstone Lua uses via TIME), not the PHP
+ // wall clock, so a client/server skew can't flake it.
+ $past = ((int) $redis->time()[0] - 60) * 1000000;
$redis->hSet('doc:1', '__utopia_tomb__', (string) $past);
$this->assertNotFalse(
@@ -252,7 +254,7 @@ class LeasableTest extends TestCase
$generation = $cache->getGeneration('doc:1');
// 1h-ahead deadline (µs), far beyond the window: a since-rewound clock.
- $farFutureMicros = ((int) \time() + 3600) * 1000000;
+ $farFutureMicros = ((int) $redis->time()[0] + 3600) * 1000000;
$redis->hSet('doc:1', '__utopia_tomb__', (string) $farFutureMicros);
$this->assertNotFalse(