From 6725ef6b8a984068752717bdf6a69674e9c0bdd5 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Thu, 2 Jul 2026 03:10:49 +1200 Subject: [PATCH 1/4] perf(cache): dispatch lease scripts via EVALSHA to unblock the shared connection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit purge and saveWithLease shipped the full Lua body on every EVAL, and on the Multiplexing adapter's single FIFO connection each fat frame head-of-line-blocked every other operation — inflating load/save/list latency too, not just the lease ops. Send EVALSHA of the locally-computed digest instead, falling back to EVAL once on NOSCRIPT so the server re-caches the body. Steady-state frames drop from ~600B to ~40B. Centralized in Redis\Leasable::leaseRun(); implemented for both the Multiplexing and php-redis adapters. Adds a SCRIPT FLUSH regression test proving the fallback. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 29 +++++++++ src/Cache/Adapter/Redis/Leasable.php | 64 ++++++++++++++++--- src/Cache/Adapter/Redis/Multiplexing.php | 16 +++++ src/Cache/Adapter/Redis/NoScript.php | 13 ++++ .../E2E/Redis/LeasableMultiplexingTest.php | 33 ++++++++++ tests/Cache/E2E/Redis/LeasableTest.php | 30 +++++++++ 6 files changed, 177 insertions(+), 8 deletions(-) create mode 100644 src/Cache/Adapter/Redis/NoScript.php 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'); From 7cde69437ed0288898dfd8fa16ed8d9c6de68850 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Thu, 2 Jul 2026 03:22:01 +1200 Subject: [PATCH 2/4] refactor(cache): narrow leaseRun to private MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Only saveWithLease and purge call it, both inside Leasable — no concrete adapter needs to call or override it, so private keeps the EVALSHA→EVAL contract from leaking into the extension surface. Addresses review. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis/Leasable.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Cache/Adapter/Redis/Leasable.php b/src/Cache/Adapter/Redis/Leasable.php index 89b6446910..94865fbc22 100644 --- a/src/Cache/Adapter/Redis/Leasable.php +++ b/src/Cache/Adapter/Redis/Leasable.php @@ -199,7 +199,7 @@ abstract class Leasable implements \Utopia\Cache\Feature\Leasable * * @param array $args */ - protected function leaseRun(string $script, string $key, array $args): mixed + private function leaseRun(string $script, string $key, array $args): mixed { try { return $this->leaseEvalSha($this->shaFor($script), $key, $args); From a494130eea0c8d73c370ea9d8fe7b5a3e3c6eaca Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Thu, 2 Jul 2026 03:31:26 +1200 Subject: [PATCH 3/4] refactor(cache): match the NOSCRIPT error code, not a substring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Redis error replies carry no numeric code (getCode() is 0 on both the raw socket and php-redis); the code is the reply's leading token — "NOSCRIPT No matching script." Match that token via NoScript::matches() instead of a substring anywhere in the message, so echoed key/value text containing the word can't false-trigger the EVAL fallback. Centralizes the literal and the NoScript construction (NoScript::from) across both adapters. Addresses review. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 16 +++++---- src/Cache/Adapter/Redis/Multiplexing.php | 6 ++-- src/Cache/Adapter/Redis/NoScript.php | 25 +++++++++++++++ tests/Cache/Unit/Redis/NoScriptTest.php | 41 ++++++++++++++++++++++++ 4 files changed, 78 insertions(+), 10 deletions(-) create mode 100644 tests/Cache/Unit/Redis/NoScriptTest.php diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 1df070895b..e457d55790 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -200,20 +200,22 @@ class Redis extends Leasable implements Adapter, Retryable 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); + // php-redis may throw NOSCRIPT rather than returning false. + if (NoScript::matches($e->getMessage())) { + throw NoScript::from($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')) { + // ...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)) { $this->redis->clearLastError(); - throw new NoScript('NOSCRIPT'); + throw NoScript::from($error); } return $result; diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php index 45a9b2a9d6..3f4ac90d2e 100644 --- a/src/Cache/Adapter/Redis/Multiplexing.php +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -183,9 +183,9 @@ class Multiplexing extends Leasable implements Adapter, TelemetryFeature } 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); + // never carries this code, so reconnect handling is unaffected. + if (NoScript::matches($e->getMessage())) { + throw NoScript::from($e); } throw $e; diff --git a/src/Cache/Adapter/Redis/NoScript.php b/src/Cache/Adapter/Redis/NoScript.php index 3c830cc0c2..90d395e561 100644 --- a/src/Cache/Adapter/Redis/NoScript.php +++ b/src/Cache/Adapter/Redis/NoScript.php @@ -10,4 +10,29 @@ namespace Utopia\Cache\Adapter\Redis; */ final class NoScript extends \RuntimeException { + /** + * RESP error code for an EVALSHA cache miss. Redis error replies carry no + * numeric code (getCode() is 0 on both the raw socket and php-redis), so the + * code is the reply's leading token — "NOSCRIPT No matching script." — the + * same across the raw RESP frame and php-redis getLastError(). + */ + private const CODE = 'NOSCRIPT'; + + /** + * True when a Redis error string's code (its leading token) is NOSCRIPT. + * Matching the token, not a substring, avoids false positives on echoed key + * or value text that merely contains the word. + */ + public static function matches(string $error): bool + { + return \explode(' ', $error, 2)[0] === self::CODE; + } + + /** Build the signal from the underlying Redis error (exception or message). */ + public static function from(\Throwable|string $reason): self + { + return $reason instanceof \Throwable + ? new self($reason->getMessage(), 0, $reason) + : new self($reason); + } } 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()); + } +} From 56803fcfea15088f9aad0530f593e35602757426 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Thu, 2 Jul 2026 03:38:29 +1200 Subject: [PATCH 4/4] refactor(cache): drop the redundant second clearLastError in leaseEvalSha MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit getLastError()/clearLastError() are client-side accessors (~16ns, no round trip), so cost was never the issue — but the clear before throwing NoScript was dead: the EVAL fallback never reads getLastError() and the next leaseEvalSha clears again. Keep only the leading clear, which is what makes the getLastError() check reflect this call rather than a prior command. Addresses review. Co-Authored-By: Claude Opus 4.8 --- src/Cache/Adapter/Redis.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index e457d55790..e67c544dcf 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -195,6 +195,8 @@ class Redis extends Leasable implements Adapter, Retryable 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 { @@ -213,8 +215,6 @@ class Redis extends Leasable implements Adapter, Retryable // inspect; NOSCRIPT means leaseRun() should resend the body. $error = (string) $this->redis->getLastError(); if ($result === false && NoScript::matches($error)) { - $this->redis->clearLastError(); - throw NoScript::from($error); }