From 85eab206704584b0a2645500f730e3d26e8ac127 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Wed, 1 Jul 2026 16:45:54 +1200 Subject: [PATCH 1/3] feat(cache): purge tombstone to shrink the sub-case-B read-after-write window The generation lease rejects a reader that captured the generation BEFORE a concurrent purge. It cannot reject a reader that captured the generation AFTER the purge (token valid) but whose database read lagged the write: a read replica behind the primary, or an older MVCC snapshot on a pooled connection. Its token matches, so the stale row would be cached. saveWithLease now also refuses any lease save for a configurable grace window after a purge, stamped in-hash off the Redis clock (single-key, atomic). It is a bounded mitigation, not a proof: size the window to the worst-case read-after-write staleness; fully closing the race needs a DB freshness token (LSN/GTID). TIME is CLOCK_REALTIME, so a deadline more than the window ahead of now is treated as a backward clock step and ignored, bounding any block to the window and never wedging saves. A non-numeric deadline fails open. Default window 0 preserves the exact prior lease behaviour. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 163 +++++++++++++++++++------ tests/Cache/E2E/Redis/LeasableTest.php | 124 +++++++++++++++++++ 2 files changed, 247 insertions(+), 40 deletions(-) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index ae14401f98..cd9673ca88 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -22,15 +22,50 @@ class Redis implements Adapter, Leasable, Retryable */ private const GENERATION_FIELD = '__utopia_gen__'; + /** + * Reserved hash field holding the epoch-microsecond deadline until which + * saveWithLease() is refused after a purge. The generation lease alone cannot + * reject a reader that captured the post-purge generation yet read the row + * from a source lagging behind the write (a replica, or an older MVCC + * snapshot on a pooled connection): its token matches, so the stale value + * would be cached. This tombstone shrinks that window by refusing every lease + * save for graceWindow ms after a purge, regardless of token. It is a bounded + * mitigation, not a proof: a reader whose read stays stale for longer than + * graceWindow can still slip through, so size graceWindow to the worst-case + * read-after-write staleness (replica lag / snapshot lifetime). Fully closing + * the race needs a database freshness token (LSN/GTID), not a wall clock. + * Lives in the same hash to keep operations single-key. Not a usable field. + */ + private const TOMBSTONE_FIELD = '__utopia_tomb__'; + /** * 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. + * equals the caller's token AND, when a grace window is set, the key is past + * its post-purge tombstone. redis.call('TIME') is CLOCK_REALTIME, so a + * deadline more than the window ahead of now means the wall clock stepped + * backward since the stamp; it is ignored rather than wedging saves, which + * also bounds any block to graceWindow of real time. A non-numeric deadline + * is ignored (fail open). Single-key. KEYS[1]=key; ARGV[1]=hash, ARGV[2]=value, + * ARGV[3]=expected generation, ARGV[4]=grace window in ms (0 disables it). */ 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]) + 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]) + if now < deadline and (deadline - now) <= window * 1000 then + return 0 + end + end + end + end redis.call('HSET', KEYS[1], ARGV[1], ARGV[2]) return 1 LUA; @@ -40,32 +75,51 @@ class Redis implements Adapter, Leasable, Retryable * 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. + * when nothing was cached. When ARGV[1] (grace window, ms) is > 0 the key is + * also stamped with a tombstone that refuses lease saves for that long, so a + * reader whose read lags the write cannot repopulate stale data even with a + * matching token. Returns the number of value fields removed (the reserved + * generation and tombstone fields are excluded), preserving purge() + * semantics. Single-key. KEYS[1]=key; ARGV[1]=grace window in ms. */ private const LUA_PURGE_BUMP = <<<'LUA' - 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 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], field, next) + redis.call('HSET', KEYS[1], gen, next) + local window = tonumber(ARGV[1]) + 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 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. + * so a field-level purge invalidates in-flight leases just like a full purge, + * and stamp the post-purge tombstone when a grace window is set. The tombstone + * is key-level, so it also briefly blocks lease re-caching of the key's other + * fields (conservative: never caches stale, may skip a fresh sibling save + * within the window). Returns the number of fields removed, preserving + * purge()'s deletion-result semantics. Single-key. KEYS[1]=key; ARGV[1]=field, + * ARGV[2]=grace window in 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]) + 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; @@ -78,6 +132,16 @@ class Redis implements Adapter, Leasable, Retryable private int $retryDelay = 1000; // milliseconds + /** + * Milliseconds after a purge during which saveWithLease() is refused, to + * defend against a reader whose read lags the purge's write (replica lag or a + * stale MVCC snapshot on a pooled connection). Size it to the worst-case + * read-after-write staleness horizon: a read that stays stale longer than + * this can still slip through. 0 disables the tombstone and preserves the + * pure generation-lease behaviour. + */ + private int $leaseGraceWindow = 0; + private string $host; private int $port; @@ -147,6 +211,35 @@ class Redis implements Adapter, Leasable, Retryable return $this; } + /** + * @param int $milliseconds window after a purge during which lease saves are + * refused; size it to the worst-case read-after-write + * staleness horizon (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; + } + + /** + * The generation and tombstone live in each key's own hash; a caller must + * never read, write or delete them through the public field API, or they + * could reset the generation and revive stale lease tokens, or tamper with + * the post-purge tombstone. + */ + private function isReserved(string $hash): bool + { + return $hash === self::GENERATION_FIELD || $hash === self::TOMBSTONE_FIELD; + } + /** * @param string $key * @param int $ttl time in seconds @@ -159,10 +252,7 @@ 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) { + if ($this->isReserved($hash)) { return false; } @@ -191,10 +281,7 @@ 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) { + if ($this->isReserved($hash)) { return false; } @@ -225,10 +312,7 @@ 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) { + if ($this->isReserved($hash)) { return false; } @@ -236,7 +320,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, $hash, $value, $generation], + [$key, $hash, $value, $generation, $this->leaseGraceWindow], 1 )); @@ -257,10 +341,7 @@ 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) { + if ($this->isReserved($hash)) { return false; } @@ -291,8 +372,8 @@ class Redis implements Adapter, Leasable, Retryable return []; } - // 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)); + // Don't expose reserved internal fields (generation, tombstone) as listable cache fields. + return \array_values(\array_filter($keys, fn (string $field): bool => ! $this->isReserved($field))); } /** @@ -303,23 +384,24 @@ class Redis implements Adapter, Leasable, Retryable public function purge(string $key, string $hash = ''): bool { if (! empty($hash)) { - if ($hash === self::GENERATION_FIELD) { + if ($this->isReserved($hash)) { return false; } return (bool) $this->execute(fn () => $this->redis->eval( self::LUA_PURGE_FIELD, - [$key, $hash], + [$key, $hash, $this->leaseGraceWindow], 1 )); } // 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. + // generation cannot re-cache stale data after this purge, and stamp the + // post-purge tombstone when a grace window is configured. return (bool) $this->execute(fn () => $this->redis->eval( self::LUA_PURGE_BUMP, - [$key], + [$key, $this->leaseGraceWindow], 1 )); } @@ -354,10 +436,11 @@ 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. + // holding its reserved generation (and, when a grace window is set, + // tombstone) 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()); diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index e33ac11aae..f38069e541 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -141,4 +141,128 @@ class LeasableTest extends TestCase $this->cache->purge('doc:1'); $this->assertSame([], $this->cache->list('doc:1')); } + + private function graceCache(int $milliseconds): Cache + { + $redis = new Redis(); + $redis->connect('redis', 6379); + $adapter = new RedisAdapter($redis); + $adapter->setLeaseGraceWindow($milliseconds); + + return new Cache($adapter); + } + + public function testLeaseGraceWindowDefaultsToZero(): void + { + $redis = new Redis(); + $redis->connect('redis', 6379); + $this->assertSame(0, (new RedisAdapter($redis))->getLeaseGraceWindow()); + } + + /** + * The tombstone closes the residual gap the generation lease cannot: a reader + * that captured the CURRENT (post-purge) generation but whose read lagged the + * write (a replica, or a stale MVCC snapshot on a pooled connection) would + * otherwise re-cache stale data, because its token matches. Within the + * post-purge grace window, saveWithLease must refuse even a token-valid save. + */ + public function testTombstoneRejectsTokenValidSaveWithinGraceWindow(): void + { + $cache = $this->graceCache(500); + $cache->flush(); + + // A writer commits and purges; the tombstone opens. + $cache->purge('doc:1'); + + // The reader's token is valid (captured post-purge) but its read lagged + // the write, so the value it wants to cache is stale. + $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'); + + // Once the grace window elapses, lease saves resume normally. + \usleep(600 * 1000); + $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')); + } + + /** + * A field-level purge must open the same tombstone as a full purge, so a + * lagging reader cannot repopulate a stale hash field either. + */ + public function testFieldPurgeAlsoOpensTombstone(): void + { + $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 + { + $cache = $this->graceCache(500); + $cache->flush(); + + $cache->saveWithLease('doc:1', ['v' => 1], 'field-a', $cache->getGeneration('doc:1')); + $cache->purge('doc:1'); + + // The purged key holds only its reserved generation and tombstone + // fields; neither may surface as a listable cache field. + $this->assertSame([], $cache->list('doc:1')); + } + + public function testReservedTombstoneFieldIsProtected(): void + { + $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__')); + } + + /** + * TIME is CLOCK_REALTIME, so a backward wall-clock step could leave a stamped + * deadline far in the future and wedge every lease save until real time + * caught up. A deadline more than the window ahead of now must be treated as + * a clock anomaly and ignored, not honoured. + */ + public function testTombstoneIgnoresImplausibleFutureDeadline(): void + { + $redis = new Redis(); + $redis->connect('redis', 6379); + $adapter = new RedisAdapter($redis); + $adapter->setLeaseGraceWindow(500); + $cache = new Cache($adapter); + $cache->flush(); + + $cache->purge('doc:1'); + $generation = $cache->getGeneration('doc:1'); + + // A deadline 1h ahead (in microseconds) — far beyond the 500ms window — + // stands in for a backward clock step after the stamp. + $farFutureMicros = ((int) \time() + 3600) * 1000000; + $redis->hSet('doc:1', '__utopia_tomb__', (string) $farFutureMicros); + + $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')); + } } From e834c54eea9eed17a171f3cd12307b821f9c41a7 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Wed, 1 Jul 2026 20:14:10 +1200 Subject: [PATCH 2/3] =?UTF-8?q?fix(cache):=20address=20review=20=E2=80=94?= =?UTF-8?q?=20nil-guard=20window,=20self-heal=20spent=20tombstone,=20drop?= =?UTF-8?q?=20test=20sleep?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - window: `tonumber(ARGV[n]) or 0` in all three Lua scripts, so a missing or non-numeric window fails open (treated as 0/disabled) instead of raising a Lua error that would fail the save closed. - saveWithLease now HDELs a spent/invalid/anomalous tombstone before writing, so a field-purged hash doesn't keep the tombstone forever (Redis hashes have no per-field TTL). - LeasableTest: expire the tombstone via a direct past-deadline write instead of usleep(600ms) — faster and not timing-flaky — and assert the spent field is dropped. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 15 +++++++++------ tests/Cache/E2E/Redis/LeasableTest.php | 18 +++++++++++++++--- 2 files changed, 24 insertions(+), 9 deletions(-) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index cd9673ca88..007bca7ba9 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -44,15 +44,17 @@ class Redis implements Adapter, Leasable, Retryable * its post-purge tombstone. redis.call('TIME') is CLOCK_REALTIME, so a * deadline more than the window ahead of now means the wall clock stepped * backward since the stamp; it is ignored rather than wedging saves, which - * also bounds any block to graceWindow of real time. A non-numeric deadline - * is ignored (fail open). Single-key. KEYS[1]=key; ARGV[1]=hash, ARGV[2]=value, - * ARGV[3]=expected generation, ARGV[4]=grace window in ms (0 disables it). + * also bounds any block to graceWindow of real time. A non-numeric window or + * deadline is treated as absent (fail open), and a spent/invalid deadline is + * dropped so a field-purged hash doesn't keep the tombstone forever. + * Single-key. KEYS[1]=key; ARGV[1]=hash, ARGV[2]=value, ARGV[3]=expected + * generation, ARGV[4]=grace window in ms (0 disables it). */ 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]) + local window = tonumber(ARGV[4]) or 0 if window > 0 then local tomb = redis.call('HGET', KEYS[1], '__utopia_tomb__') if tomb ~= false then @@ -64,6 +66,7 @@ class Redis implements Adapter, Leasable, Retryable return 0 end end + redis.call('HDEL', KEYS[1], '__utopia_tomb__') end end redis.call('HSET', KEYS[1], ARGV[1], ARGV[2]) @@ -90,7 +93,7 @@ class Redis implements Adapter, Leasable, Retryable local next = (tonumber(current) or 0) + 1 redis.call('DEL', KEYS[1]) redis.call('HSET', KEYS[1], gen, next) - local window = tonumber(ARGV[1]) + 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]) @@ -114,7 +117,7 @@ class Redis implements Adapter, Leasable, Retryable 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]) + 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]) diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index f38069e541..c47d6e4d72 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -168,7 +168,11 @@ class LeasableTest extends TestCase */ public function testTombstoneRejectsTokenValidSaveWithinGraceWindow(): void { - $cache = $this->graceCache(500); + $redis = new Redis(); + $redis->connect('redis', 6379); + $adapter = new RedisAdapter($redis); + $adapter->setLeaseGraceWindow(500); + $cache = new Cache($adapter); $cache->flush(); // A writer commits and purges; the tombstone opens. @@ -183,13 +187,21 @@ class LeasableTest extends TestCase ); $this->assertFalse($cache->load('doc:1', 60, 'doc:1'), 'Cache must not hold the stale value'); - // Once the grace window elapses, lease saves resume normally. - \usleep(600 * 1000); + // Simulate the window elapsing by moving the deadline into the past (a + // direct write, no sleep): lease saves resume, and the spent tombstone is + // dropped rather than lingering in the hash. + $past = ((int) \time() - 60) * 1000000; + $redis->hSet('doc:1', '__utopia_tomb__', (string) $past); + $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')); + $this->assertFalse( + (bool) $redis->hExists('doc:1', '__utopia_tomb__'), + 'The spent tombstone must be dropped on the next save, not linger in the hash' + ); } /** From 38c0b57e7240797f767460a030aca1e35cc38f75 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Wed, 1 Jul 2026 20:25:53 +1200 Subject: [PATCH 3/3] docs(cache): trim verbose comments to concise intent + KEYS/ARGV specs Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 85 ++++++-------------------- tests/Cache/E2E/Redis/LeasableTest.php | 30 +++------ 2 files changed, 27 insertions(+), 88 deletions(-) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 007bca7ba9..fff5949edd 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -23,32 +23,16 @@ class Redis implements Adapter, Leasable, Retryable private const GENERATION_FIELD = '__utopia_gen__'; /** - * Reserved hash field holding the epoch-microsecond deadline until which - * saveWithLease() is refused after a purge. The generation lease alone cannot - * reject a reader that captured the post-purge generation yet read the row - * from a source lagging behind the write (a replica, or an older MVCC - * snapshot on a pooled connection): its token matches, so the stale value - * would be cached. This tombstone shrinks that window by refusing every lease - * save for graceWindow ms after a purge, regardless of token. It is a bounded - * mitigation, not a proof: a reader whose read stays stale for longer than - * graceWindow can still slip through, so size graceWindow to the worst-case - * read-after-write staleness (replica lag / snapshot lifetime). Fully closing - * the race needs a database freshness token (LSN/GTID), not a wall clock. - * Lives in the same hash to keep operations single-key. Not a usable field. + * 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 field into hash $key only when the key's generation field still - * equals the caller's token AND, when a grace window is set, the key is past - * its post-purge tombstone. redis.call('TIME') is CLOCK_REALTIME, so a - * deadline more than the window ahead of now means the wall clock stepped - * backward since the stamp; it is ignored rather than wedging saves, which - * also bounds any block to graceWindow of real time. A non-numeric window or - * deadline is treated as absent (fail open), and a spent/invalid deadline is - * dropped so a field-purged hash doesn't keep the tombstone forever. - * Single-key. KEYS[1]=key; ARGV[1]=hash, ARGV[2]=value, ARGV[3]=expected - * generation, ARGV[4]=grace window in ms (0 disables it). + * 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__') @@ -62,6 +46,7 @@ class Redis implements Adapter, Leasable, Retryable 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 @@ -74,16 +59,10 @@ class Redis implements Adapter, Leasable, Retryable LUA; /** - * 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. When ARGV[1] (grace window, ms) is > 0 the key is - * also stamped with a tombstone that refuses lease saves for that long, so a - * reader whose read lags the write cannot repopulate stale data even with a - * matching token. Returns the number of value fields removed (the reserved - * generation and tombstone fields are excluded), preserving purge() - * semantics. Single-key. KEYS[1]=key; ARGV[1]=grace window in ms. + * 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__' @@ -103,14 +82,9 @@ class Redis implements Adapter, Leasable, Retryable 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, - * and stamp the post-purge tombstone when a grace window is set. The tombstone - * is key-level, so it also briefly blocks lease re-caching of the key's other - * fields (conservative: never caches stale, may skip a fresh sibling save - * within the window). Returns the number of fields removed, preserving - * purge()'s deletion-result semantics. Single-key. KEYS[1]=key; ARGV[1]=field, - * ARGV[2]=grace window in ms. + * 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]) @@ -136,12 +110,8 @@ class Redis implements Adapter, Leasable, Retryable private int $retryDelay = 1000; // milliseconds /** - * Milliseconds after a purge during which saveWithLease() is refused, to - * defend against a reader whose read lags the purge's write (replica lag or a - * stale MVCC snapshot on a pooled connection). Size it to the worst-case - * read-after-write staleness horizon: a read that stays stale longer than - * this can still slip through. 0 disables the tombstone and preserves the - * pure generation-lease behaviour. + * 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; @@ -215,9 +185,7 @@ class Redis implements Adapter, Leasable, Retryable } /** - * @param int $milliseconds window after a purge during which lease saves are - * refused; size it to the worst-case read-after-write - * staleness horizon (0 disables the tombstone) + * @param int $milliseconds grace window after a purge (0 disables the tombstone) * @return self */ public function setLeaseGraceWindow(int $milliseconds): self @@ -232,12 +200,7 @@ class Redis implements Adapter, Leasable, Retryable return $this->leaseGraceWindow; } - /** - * The generation and tombstone live in each key's own hash; a caller must - * never read, write or delete them through the public field API, or they - * could reset the generation and revive stale lease tokens, or tamper with - * the post-purge tombstone. - */ + /** 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; @@ -398,10 +361,6 @@ class Redis implements Adapter, Leasable, Retryable )); } - // 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, and stamp the - // post-purge tombstone when a grace window is configured. return (bool) $this->execute(fn () => $this->redis->eval( self::LUA_PURGE_BUMP, [$key, $this->leaseGraceWindow], @@ -438,12 +397,8 @@ 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 its reserved generation (and, when a grace window is set, - // tombstone) 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. + // A purged key keeps its reserved field(s) until re-cached, so DBSIZE can + // slightly over-count purged-but-not-yet-recached keys. /** @var int $size */ $size = $this->execute(fn () => $this->redis->dbSize()); diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index c47d6e4d72..cb6991bfa2 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -160,11 +160,8 @@ class LeasableTest extends TestCase } /** - * The tombstone closes the residual gap the generation lease cannot: a reader - * that captured the CURRENT (post-purge) generation but whose read lagged the - * write (a replica, or a stale MVCC snapshot on a pooled connection) would - * otherwise re-cache stale data, because its token matches. Within the - * post-purge grace window, saveWithLease must refuse even a token-valid save. + * 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 { @@ -175,11 +172,8 @@ class LeasableTest extends TestCase $cache = new Cache($adapter); $cache->flush(); - // A writer commits and purges; the tombstone opens. $cache->purge('doc:1'); - // The reader's token is valid (captured post-purge) but its read lagged - // the write, so the value it wants to cache is stale. $generation = $cache->getGeneration('doc:1'); $this->assertFalse( $cache->saveWithLease('doc:1', ['stale' => true], 'doc:1', $generation), @@ -187,9 +181,7 @@ class LeasableTest extends TestCase ); $this->assertFalse($cache->load('doc:1', 60, 'doc:1'), 'Cache must not hold the stale value'); - // Simulate the window elapsing by moving the deadline into the past (a - // direct write, no sleep): lease saves resume, and the spent tombstone is - // dropped rather than lingering in the hash. + // Expire the tombstone directly (no sleep) to resume saves. $past = ((int) \time() - 60) * 1000000; $redis->hSet('doc:1', '__utopia_tomb__', (string) $past); @@ -204,10 +196,7 @@ class LeasableTest extends TestCase ); } - /** - * A field-level purge must open the same tombstone as a full purge, so a - * lagging reader cannot repopulate a stale hash field either. - */ + /** A field-level purge must open the tombstone too. */ public function testFieldPurgeAlsoOpensTombstone(): void { $cache = $this->graceCache(500); @@ -232,8 +221,6 @@ class LeasableTest extends TestCase $cache->saveWithLease('doc:1', ['v' => 1], 'field-a', $cache->getGeneration('doc:1')); $cache->purge('doc:1'); - // The purged key holds only its reserved generation and tombstone - // fields; neither may surface as a listable cache field. $this->assertSame([], $cache->list('doc:1')); } @@ -249,10 +236,8 @@ class LeasableTest extends TestCase } /** - * TIME is CLOCK_REALTIME, so a backward wall-clock step could leave a stamped - * deadline far in the future and wedge every lease save until real time - * caught up. A deadline more than the window ahead of now must be treated as - * a clock anomaly and ignored, not honoured. + * A deadline more than the window ahead of now (a since-rewound clock) must + * be ignored, not wedge saves. */ public function testTombstoneIgnoresImplausibleFutureDeadline(): void { @@ -266,8 +251,7 @@ class LeasableTest extends TestCase $cache->purge('doc:1'); $generation = $cache->getGeneration('doc:1'); - // A deadline 1h ahead (in microseconds) — far beyond the 500ms window — - // stands in for a backward clock step after the stamp. + // 1h-ahead deadline (µs), far beyond the window: a since-rewound clock. $farFutureMicros = ((int) \time() + 3600) * 1000000; $redis->hSet('doc:1', '__utopia_tomb__', (string) $farFutureMicros);