diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index e3429194d1..e67c544dcf 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,36 @@ 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) { + // Client-side reset (no round trip) so the getLastError() check below + // reflects only this evalSha, not an error left by a prior command. + $this->redis->clearLastError(); + + try { + $result = $this->redis->evalSha($sha, [$key, ...$args], 1); + } catch (\RedisException $e) { + // php-redis may throw NOSCRIPT rather than returning false. + if (NoScript::matches($e->getMessage())) { + throw NoScript::from($e); + } + + throw $e; + } + + // ...or it reports the same error as false + getLastError(). A lease + // script always returns an int on success, so false is an error to + // inspect; NOSCRIPT means leaseRun() should resend the body. + $error = (string) $this->redis->getLastError(); + if ($result === false && NoScript::matches($error)) { + throw NoScript::from($error); + } + + 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..94865fbc22 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 + */ + private 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..3f4ac90d2e 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 code, so reconnect handling is unaffected. + if (NoScript::matches($e->getMessage())) { + throw NoScript::from($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..90d395e561 --- /dev/null +++ b/src/Cache/Adapter/Redis/NoScript.php @@ -0,0 +1,38 @@ +getMessage(), 0, $reason) + : new self($reason); + } +} diff --git a/tests/Cache/E2E/Redis/LeasableMultiplexingTest.php b/tests/Cache/E2E/Redis/LeasableMultiplexingTest.php index 98144ead4e..fb6c41078d 100644 --- a/tests/Cache/E2E/Redis/LeasableMultiplexingTest.php +++ b/tests/Cache/E2E/Redis/LeasableMultiplexingTest.php @@ -152,6 +152,39 @@ class LeasableMultiplexingTest extends TestCase }); } + /** + * 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->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'); diff --git a/tests/Cache/Unit/Redis/NoScriptTest.php b/tests/Cache/Unit/Redis/NoScriptTest.php new file mode 100644 index 0000000000..b0b593fdce --- /dev/null +++ b/tests/Cache/Unit/Redis/NoScriptTest.php @@ -0,0 +1,41 @@ +assertTrue(NoScript::matches('NOSCRIPT No matching script. Please use EVAL.')); + $this->assertTrue(NoScript::matches('NOSCRIPT')); + } + + public function testDoesNotMatchWhenNoScriptIsNotTheCode(): void + { + // A substring check would wrongly trip on echoed key/value text or a + // different error code — the code is only ever the leading token. + $this->assertFalse(NoScript::matches('ERR user set key to "NOSCRIPT"')); + $this->assertFalse(NoScript::matches('WRONGTYPE Operation against a key holding the wrong kind of value')); + $this->assertFalse(NoScript::matches('')); + } + + public function testFromExceptionPreservesMessageAndCause(): void + { + $cause = new \RedisException('NOSCRIPT No matching script. Please use EVAL.'); + $signal = NoScript::from($cause); + + $this->assertSame($cause->getMessage(), $signal->getMessage()); + $this->assertSame($cause, $signal->getPrevious()); + } + + public function testFromStringCarriesMessage(): void + { + $signal = NoScript::from('NOSCRIPT No matching script. Please use EVAL.'); + + $this->assertSame('NOSCRIPT No matching script. Please use EVAL.', $signal->getMessage()); + $this->assertNull($signal->getPrevious()); + } +}