mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
feat(cache): make Multiplexing Leasable; share lease logic in Redis\Leasable base
Redis\Multiplexing was not Leasable, so through the Cache facade getGeneration() returned '0' and saveWithLease() fell back to an unconditional save() — the generation lease and purge tombstone were inert on any redis-multiplexing deployment (the cloud platform cache in every region). Extract the shared lease behaviour — reserved fields, the three atomic single-key Lua scripts, the grace window, and getGeneration()/saveWithLease()/ purge() — into an abstract base class Utopia\Cache\Adapter\Redis\Leasable with abstract leaseEval()/leaseHget() transport hooks (it implements the transport-agnostic \Utopia\Cache\Feature\Leasable capability, referenced by FQN to avoid shadowing its own short name). Both Redis and Multiplexing extend it and supply the transport (phpredis eval/hGet vs the multiplexed EVAL command), so the Lua can't drift between adapters. tests/Cache/E2E/Redis/LeasableMultiplexingTest.php mirrors LeasableTest against the multiplexing transport. Full redis E2E suite: 52 tests green. PHPStan max + Pint clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
1 parent
9511d854dc
commit
92d2291669
5 files changed
+584
-185
No files matched your search
+8
-175
@@ -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));
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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'));
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -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(
|
||||
|
||||
Reference in new issue
Block a user