mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
Merge pull request #81 from utopia-php/perf/lease-evalsha
perf(cache): dispatch lease scripts via EVALSHA to unblock the shared connection
This commit is contained in:
7 files changed
+245
-8
No files matched your search
@@ -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));
|
||||
|
||||
@@ -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
|
||||
*/
|
||||
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<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
|
||||
*/
|
||||
|
||||
@@ -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]);
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
<?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
|
||||
{
|
||||
/**
|
||||
* 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);
|
||||
}
|
||||
}
|
||||
@@ -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 () {
|
||||
|
||||
@@ -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');
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
<?php
|
||||
|
||||
namespace Utopia\Tests\Unit\Redis;
|
||||
|
||||
use PHPUnit\Framework\TestCase;
|
||||
use Utopia\Cache\Adapter\Redis\NoScript;
|
||||
|
||||
class NoScriptTest extends TestCase
|
||||
{
|
||||
public function testMatchesWhenNoScriptIsTheLeadingCodeToken(): void
|
||||
{
|
||||
$this->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());
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user