Merge pull request #80 from utopia-php/feat/leasable-multiplexing-adapter

feat(cache): make the Multiplexing adapter Leasable (lease + purge tombstone)
This commit is contained in:
Jake Barnby authored and GitHub committed 2026-07-01 23:37:30 +12:00
commit fa5ee921eb
7 files changed
+593 -187

No files matched your search

+3 -2
View File
@@ -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
+6
View File
@@ -42,9 +42,15 @@
<testsuite name="redis">
<directory>./tests/Cache/E2E/Redis</directory>
<exclude>./tests/Cache/E2E/Redis/RedisClusterTest.php</exclude>
<exclude>./tests/Cache/E2E/Redis/MultiplexingTest.php</exclude>
<exclude>./tests/Cache/E2E/Redis/LeasableMultiplexingTest.php</exclude>
</testsuite>
<testsuite name="redis-cluster">
<file>./tests/Cache/E2E/Redis/RedisClusterTest.php</file>
</testsuite>
<testsuite name="redis-multiplexing">
<file>./tests/Cache/E2E/Redis/MultiplexingTest.php</file>
<file>./tests/Cache/E2E/Redis/LeasableMultiplexingTest.php</file>
</testsuite>
</testsuites>
</phpunit>
+8 -175
View File
@@ -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));
}
/**
+193
View File
@@ -0,0 +1,193 @@
<?php
namespace Utopia\Cache\Adapter\Redis;
use Throwable;
/**
* Shared generation-lease + purge-tombstone behaviour for the Redis-protocol
* cache adapters (Redis and Redis\Multiplexing). Subclasses supply the transport
* by implementing leaseEval()/leaseHget(); everything lease-related — the
* reserved fields, the three atomic single-key Lua scripts, the grace window,
* getGeneration(), saveWithLease() and purge() — lives here so it can't drift
* between adapters.
*
* Implements the transport-agnostic \Utopia\Cache\Feature\Leasable capability,
* referenced by FQN to avoid shadowing this class's own short name.
*/
abstract class Leasable implements \Utopia\Cache\Feature\Leasable
{
/**
* 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.
*/
protected 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.
*/
protected 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).
*/
protected 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.
*/
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<int, int|string> $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;
}
+20 -7
View File
@@ -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
@@ -0,0 +1,358 @@
<?php
namespace Utopia\Tests\E2E\Redis;
use PHPUnit\Framework\TestCase;
use Redis as Redis;
use function Swoole\Coroutine\run;
use Utopia\Cache\Adapter\Redis\Multiplexing as RedisMultiplexing;
use Utopia\Cache\Cache;
class LeasableMultiplexingTest extends TestCase
{
private RedisMultiplexing $adapter;
/**
* Run the entire test body inside a Swoole coroutine context, surfacing any
* exception as a real test failure and disconnecting the multiplexed
* connection afterwards.
*/
private function runCo(callable $fn): void
{
$error = null;
run(function () use ($fn, &$error) {
try {
$fn();
} catch (\Throwable $th) {
$error = $th;
} finally {
$this->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'));
});
}
}
+5 -3
View File
@@ -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(