perf(cache): dispatch lease scripts via EVALSHA to unblock the shared connection

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 <noreply@anthropic.com>
This commit is contained in:
Jake BarnbyandClaude Opus 4.8 committed 2026-07-02 03:10:49 +12:00
1 parent fa5ee921eb
commit 6725ef6b8a
6 files changed
+177 -8

No files matched your search

+29
View File
@@ -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));
+56 -8
View File
@@ -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<string, string>
*/
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<int, int|string> $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<int, int|string> $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<int, int|string> $args
*/
+16
View File
@@ -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]);
+13
View File
@@ -0,0 +1,13 @@
<?php
namespace Utopia\Cache\Adapter\Redis;
/**
* Internal signal: the server has no cached script for the SHA sent via EVALSHA,
* so the caller must resend the full body with EVAL (which also re-caches it).
* Deliberately not a RedisException subclass so the adapters' reconnect/retry
* paths — which key on RedisException — leave it alone and let leaseRun() catch it.
*/
final class NoScript extends \RuntimeException
{
}
@@ -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 () {
+30
View File
@@ -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');