diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index e3429194d1..1df070895b 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -8,6 +8,7 @@ use Throwable; use Utopia\Cache\Adapter; use Utopia\Cache\Adapter\Redis\Envelope; use Utopia\Cache\Adapter\Redis\Leasable; +use Utopia\Cache\Adapter\Redis\NoScript; use Utopia\Cache\Feature\Retryable; class Redis extends Leasable implements Adapter, Retryable @@ -191,6 +192,34 @@ class Redis extends Leasable implements Adapter, Retryable return \array_values(\array_filter($keys, fn (string $field): bool => ! $this->isReserved($field))); } + protected function leaseEvalSha(string $sha, string $key, array $args): mixed + { + return $this->execute(function () use ($sha, $key, $args) { + $this->redis->clearLastError(); + + try { + $result = $this->redis->evalSha($sha, [$key, ...$args], 1); + } catch (\RedisException $e) { + if (\str_contains($e->getMessage(), 'NOSCRIPT')) { + throw new NoScript($e->getMessage(), 0, $e); + } + + throw $e; + } + + // php-redis reports a script error as false + getLastError() rather + // than a throw. A lease script always returns an int on success, so + // false is an error; NOSCRIPT means leaseRun() should resend the body. + if ($result === false && \str_contains((string) $this->redis->getLastError(), 'NOSCRIPT')) { + $this->redis->clearLastError(); + + throw new NoScript('NOSCRIPT'); + } + + return $result; + }); + } + protected function leaseEval(string $script, string $key, array $args): mixed { return $this->execute(fn () => $this->redis->eval($script, [$key, ...$args], 1)); diff --git a/src/Cache/Adapter/Redis/Leasable.php b/src/Cache/Adapter/Redis/Leasable.php index 0c28b8a719..89b6446910 100644 --- a/src/Cache/Adapter/Redis/Leasable.php +++ b/src/Cache/Adapter/Redis/Leasable.php @@ -7,10 +7,16 @@ 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. + * by implementing leaseEvalSha()/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. + * + * Scripts are dispatched through leaseRun(): EVALSHA of the (locally computed) + * body digest, falling back to EVAL once on NoScript so the server re-caches it. + * This keeps the hot path a ~40-byte frame instead of the full script body every + * call, which matters most on the multiplexed connection where a fat frame + * head-of-line-blocks every other operation queued behind it. * * Implements the transport-agnostic \Utopia\Cache\Feature\Leasable capability, * referenced by FQN to avoid shadowing this class's own short name. @@ -149,7 +155,7 @@ abstract class Leasable implements \Utopia\Cache\Feature\Leasable try { $value = Envelope::encode($data, time()); - $stored = $this->leaseEval(self::LUA_SAVE_WITH_LEASE, $key, [ + $stored = $this->leaseRun(self::LUA_SAVE_WITH_LEASE, $key, [ $hash, $value, $generation, (string) $this->leaseGraceWindow, ]); @@ -166,10 +172,10 @@ abstract class Leasable implements \Utopia\Cache\Feature\Leasable return false; } - return (bool) $this->leaseEval(self::LUA_PURGE_FIELD, $key, [$hash, (string) $this->leaseGraceWindow]); + return (bool) $this->leaseRun(self::LUA_PURGE_FIELD, $key, [$hash, (string) $this->leaseGraceWindow]); } - return (bool) $this->leaseEval(self::LUA_PURGE_BUMP, $key, [(string) $this->leaseGraceWindow]); + return (bool) $this->leaseRun(self::LUA_PURGE_BUMP, $key, [(string) $this->leaseGraceWindow]); } /** Reserved internal fields must never be reachable through the public field API. */ @@ -178,9 +184,51 @@ abstract class Leasable implements \Utopia\Cache\Feature\Leasable return $hash === self::GENERATION_FIELD || $hash === self::TOMBSTONE_FIELD; } + /** + * Memoized SHA1 digests of the Lua scripts, keyed by body. Only ever holds + * the three constants above; a plain cache to avoid re-hashing per call. + * + * @var array + */ + private static array $scriptSha = []; + + /** + * Dispatch a single-key script by digest — EVALSHA first, resending the body + * via EVAL only when the server hasn't cached it yet (NoScript). KEYS[1] = + * $key, ARGV = $args in order. Keeps the steady-state frame ~40 bytes. + * + * @param array $args + */ + protected function leaseRun(string $script, string $key, array $args): mixed + { + try { + return $this->leaseEvalSha($this->shaFor($script), $key, $args); + } catch (NoScript) { + return $this->leaseEval($script, $key, $args); + } + } + + /** SHA1 digest Redis identifies a cached script by — the digest of its body. */ + private function shaFor(string $script): string + { + return self::$scriptSha[$script] ??= \sha1($script); + } + + /** + * Run EVALSHA of $sha — KEYS[1] = $key, ARGV = $args in order — over the + * concrete adapter's transport, returning the script's reply. + * + * @param array $args + * + * @throws NoScript when the server has no script cached for $sha, so + * leaseRun() can resend the body via leaseEval() + */ + abstract protected function leaseEvalSha(string $sha, string $key, array $args): mixed; + /** * Run a single-key Redis EVAL — KEYS[1] = $key, ARGV = $args in order — over - * the concrete adapter's transport, returning the script's reply. + * the concrete adapter's transport, returning the script's reply. Used as the + * one-time fallback that re-caches the script after a NoScript. * * @param array $args */ diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php index 229bb52606..45a9b2a9d6 100644 --- a/src/Cache/Adapter/Redis/Multiplexing.php +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -176,6 +176,22 @@ class Multiplexing extends Leasable implements Adapter, TelemetryFeature return \array_values(\array_filter($keys, fn (string $field): bool => ! $this->isReserved($field))); } + protected function leaseEvalSha(string $sha, string $key, array $args): mixed + { + try { + return $this->command(['EVALSHA', $sha, '1', $key, ...$args]); + } catch (\RedisException $e) { + // NOSCRIPT is a server reply, not a connection fault: signal leaseRun() + // to resend the body. ConnectionException (a RedisException subclass) + // never carries this message, so reconnect handling is unaffected. + if (\str_contains($e->getMessage(), 'NOSCRIPT')) { + throw new NoScript($e->getMessage(), 0, $e); + } + + throw $e; + } + } + protected function leaseEval(string $script, string $key, array $args): mixed { return $this->command(['EVAL', $script, '1', $key, ...$args]); diff --git a/src/Cache/Adapter/Redis/NoScript.php b/src/Cache/Adapter/Redis/NoScript.php new file mode 100644 index 0000000000..3c830cc0c2 --- /dev/null +++ b/src/Cache/Adapter/Redis/NoScript.php @@ -0,0 +1,13 @@ +runCo(function () { + $cache = $this->makeCache(); + $cache->flush(); + + $generation = $cache->getGeneration('doc:1'); + $this->assertNotFalse($cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $generation)); + + // Evict every cached script server-side; the next EVALSHA now misses. + $raw = new Redis(); + $raw->connect('redis', 6379); + $raw->script('flush'); + $raw->close(); + + $this->assertTrue($cache->purge('doc:1'), 'purge must fall back to EVAL after NOSCRIPT'); + $this->assertNotSame($generation, $cache->getGeneration('doc:1')); + + $fresh = $cache->getGeneration('doc:1'); + $this->assertNotFalse( + $cache->saveWithLease('doc:1', ['v' => 2], 'doc:1', $fresh), + 'saveWithLease must fall back to EVAL after NOSCRIPT' + ); + $this->assertSame(['v' => 2], $cache->load('doc:1', 60, 'doc:1')); + }); + } + public function testPurgePreservesDeletionResult(): void { $this->runCo(function () { diff --git a/tests/Cache/E2E/Redis/LeasableTest.php b/tests/Cache/E2E/Redis/LeasableTest.php index 18f0be8b6d..4633d69ee6 100644 --- a/tests/Cache/E2E/Redis/LeasableTest.php +++ b/tests/Cache/E2E/Redis/LeasableTest.php @@ -85,6 +85,36 @@ class LeasableTest extends TestCase $this->assertSame(['v' => 2], $this->cache->load('doc:1', 60, 'doc:1')); } + /** + * The hot path sends EVALSHA (script digest) rather than the full body. After + * the server drops its script cache — a failover, restart, or SCRIPT FLUSH — + * that EVALSHA replies NOSCRIPT; leaseRun() must resend the body via EVAL so + * the lease and purge operations keep working instead of silently failing. + */ + public function testLeaseSurvivesScriptCacheFlush(): void + { + $this->cache->flush(); + + $generation = $this->cache->getGeneration('doc:1'); + $this->assertNotFalse($this->cache->saveWithLease('doc:1', ['v' => 1], 'doc:1', $generation)); + + // Evict every cached script server-side; the next EVALSHA now misses. + $raw = new Redis(); + $raw->connect('redis', 6379); + $raw->script('flush'); + $raw->close(); + + $this->assertTrue($this->cache->purge('doc:1'), 'purge must fall back to EVAL after NOSCRIPT'); + $this->assertNotSame($generation, $this->cache->getGeneration('doc:1')); + + $fresh = $this->cache->getGeneration('doc:1'); + $this->assertNotFalse( + $this->cache->saveWithLease('doc:1', ['v' => 2], 'doc:1', $fresh), + 'saveWithLease must fall back to EVAL after NOSCRIPT' + ); + $this->assertSame(['v' => 2], $this->cache->load('doc:1', 60, 'doc:1')); + } + public function testPurgePreservesDeletionResult(): void { $this->assertFalse($this->cache->purge('doc:absent'), 'Purging a missing key returns false');