From d13eb236606a67d1271cd9b411dd43489194e5f8 Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Thu, 14 May 2026 15:01:00 +0100 Subject: [PATCH 1/2] refactor: extract Retryable into a Feature interface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move retry knobs off the base Adapter interface — they only make sense for adapters that actually own a network connection. Filesystem, Memory, None, Pool, Sharding, and CircuitBreaker no longer carry no-op or fan-out retry methods. Retryable is now a Feature interface implemented by Redis, RedisCluster, Memcached, and Hazelcast. Multiplexing drops its configurable retry knobs (configurable retry across a shared connection drops all in-flight callers anyway) but keeps a single transparent reconnect-and-retry on ConnectionException. Also fix Multiplexing::save() swallowing connection exceptions — encode errors now surface the underlying JsonException instead of being masked as a false return. --- src/Cache/Adapter.php | 26 ------- src/Cache/Adapter/CircuitBreaker.php | 23 ------ src/Cache/Adapter/Filesystem.php | 34 --------- src/Cache/Adapter/Hazelcast.php | 5 +- src/Cache/Adapter/Memcached.php | 5 +- src/Cache/Adapter/Memory.php | 34 --------- src/Cache/Adapter/None.php | 34 --------- src/Cache/Adapter/Pool.php | 33 --------- src/Cache/Adapter/Redis.php | 5 +- src/Cache/Adapter/Redis/Multiplexing.php | 93 ++++++------------------ src/Cache/Adapter/RedisCluster.php | 5 +- src/Cache/Adapter/Sharding.php | 42 ----------- src/Cache/Feature/Retryable.php | 32 ++++++++ tests/Cache/E2E/CircuitBreakerTest.php | 20 ----- 14 files changed, 67 insertions(+), 324 deletions(-) create mode 100644 src/Cache/Feature/Retryable.php diff --git a/src/Cache/Adapter.php b/src/Cache/Adapter.php index 91aa22d68a..2963d006d0 100644 --- a/src/Cache/Adapter.php +++ b/src/Cache/Adapter.php @@ -4,10 +4,6 @@ namespace Utopia\Cache; interface Adapter { - const MIN_RETRIES = 0; - - const MAX_RETRIES = 10; - /** * @param string $key * @param int $ttl time in seconds @@ -64,26 +60,4 @@ interface Adapter * @return string */ public function getName(?string $key = null): string; - - /** - * @param int $maxRetries (0-10) - * @return self - */ - public function setMaxRetries(int $maxRetries): self; - - /** - * @param int $retryDelay time in milliseconds - * @return self - */ - public function setRetryDelay(int $retryDelay): self; - - /** - * @return int - */ - public function getMaxRetries(): int; - - /** - * @return int - */ - public function getRetryDelay(): int; } diff --git a/src/Cache/Adapter/CircuitBreaker.php b/src/Cache/Adapter/CircuitBreaker.php index 3ef064689d..4a6a711aa9 100644 --- a/src/Cache/Adapter/CircuitBreaker.php +++ b/src/Cache/Adapter/CircuitBreaker.php @@ -111,27 +111,4 @@ class CircuitBreaker implements Adapter, Feature\Telemetry } } - public function setMaxRetries(int $maxRetries): self - { - $this->adapter->setMaxRetries($maxRetries); - - return $this; - } - - public function setRetryDelay(int $retryDelay): self - { - $this->adapter->setRetryDelay($retryDelay); - - return $this; - } - - public function getMaxRetries(): int - { - return $this->adapter->getMaxRetries(); - } - - public function getRetryDelay(): int - { - return $this->adapter->getRetryDelay(); - } } diff --git a/src/Cache/Adapter/Filesystem.php b/src/Cache/Adapter/Filesystem.php index 02c8649de9..c84ea2699e 100644 --- a/src/Cache/Adapter/Filesystem.php +++ b/src/Cache/Adapter/Filesystem.php @@ -29,24 +29,6 @@ class Filesystem implements Adapter $this->streaming = $streaming; } - /** - * @param int $maxRetries (0-10) - * @return self - */ - public function setMaxRetries(int $maxRetries): self - { - return $this; - } - - /** - * @param int $retryDelay time in milliseconds - * @return self - */ - public function setRetryDelay(int $retryDelay): self - { - return $this; - } - /** * @param string $key * @param int $ttl time in seconds @@ -246,20 +228,4 @@ class Filesystem implements Adapter { return 'filesystem'; } - - /** - * @return int - */ - public function getMaxRetries(): int - { - return 0; - } - - /** - * @return int - */ - public function getRetryDelay(): int - { - return 1000; - } } diff --git a/src/Cache/Adapter/Hazelcast.php b/src/Cache/Adapter/Hazelcast.php index 6818c069bb..8192b74817 100644 --- a/src/Cache/Adapter/Hazelcast.php +++ b/src/Cache/Adapter/Hazelcast.php @@ -4,8 +4,9 @@ namespace Utopia\Cache\Adapter; use Memcached as Client; use Utopia\Cache\Adapter; +use Utopia\Cache\Feature\Retryable; -class Hazelcast implements Adapter +class Hazelcast implements Adapter, Retryable { /** * @var Client @@ -27,7 +28,7 @@ class Hazelcast implements Adapter */ public function setMaxRetries(int $maxRetries): self { - $this->maxRetries = max(self::MIN_RETRIES, min($maxRetries, self::MAX_RETRIES)); + $this->maxRetries = max(Retryable::MIN_RETRIES, min($maxRetries, Retryable::MAX_RETRIES)); return $this; } diff --git a/src/Cache/Adapter/Memcached.php b/src/Cache/Adapter/Memcached.php index b80aa3fec0..50001674c3 100644 --- a/src/Cache/Adapter/Memcached.php +++ b/src/Cache/Adapter/Memcached.php @@ -4,8 +4,9 @@ namespace Utopia\Cache\Adapter; use Memcached as Client; use Utopia\Cache\Adapter; +use Utopia\Cache\Feature\Retryable; -class Memcached implements Adapter +class Memcached implements Adapter, Retryable { /** * @var Client @@ -32,7 +33,7 @@ class Memcached implements Adapter */ public function setMaxRetries(int $maxRetries): self { - $this->maxRetries = max(self::MIN_RETRIES, min($maxRetries, self::MAX_RETRIES)); + $this->maxRetries = max(Retryable::MIN_RETRIES, min($maxRetries, Retryable::MAX_RETRIES)); return $this; } diff --git a/src/Cache/Adapter/Memory.php b/src/Cache/Adapter/Memory.php index bb4a82a92d..2c224b2deb 100644 --- a/src/Cache/Adapter/Memory.php +++ b/src/Cache/Adapter/Memory.php @@ -18,24 +18,6 @@ class Memory implements Adapter { } - /** - * @param int $maxRetries (0-10) - * @return self - */ - public function setMaxRetries(int $maxRetries): self - { - return $this; - } - - /** - * @param int $retryDelay time in milliseconds - * @return self - */ - public function setRetryDelay(int $retryDelay): self - { - return $this; - } - /** * @param string $key * @param int $ttl @@ -156,20 +138,4 @@ class Memory implements Adapter { return 'memory'; } - - /** - * @return int - */ - public function getMaxRetries(): int - { - return 0; - } - - /** - * @return int - */ - public function getRetryDelay(): int - { - return 0; - } } diff --git a/src/Cache/Adapter/None.php b/src/Cache/Adapter/None.php index 76ec9ff672..d584fa0e3d 100644 --- a/src/Cache/Adapter/None.php +++ b/src/Cache/Adapter/None.php @@ -13,24 +13,6 @@ class None implements Adapter { } - /** - * @param int $maxRetries (0-10) - * @return self - */ - public function setMaxRetries(int $maxRetries): self - { - return $this; - } - - /** - * @param int $retryDelay time in milliseconds - * @return self - */ - public function setRetryDelay(int $retryDelay): self - { - return $this; - } - /** * @param string $key * @param int $ttl @@ -114,20 +96,4 @@ class None implements Adapter { return 'none'; } - - /** - * @return int - */ - public function getMaxRetries(): int - { - return 0; - } - - /** - * @return int - */ - public function getRetryDelay(): int - { - return 0; - } } diff --git a/src/Cache/Adapter/Pool.php b/src/Cache/Adapter/Pool.php index 851069830b..eb570abd33 100644 --- a/src/Cache/Adapter/Pool.php +++ b/src/Cache/Adapter/Pool.php @@ -129,37 +129,4 @@ class Pool implements Adapter return $result; } - public function setMaxRetries(int $maxRetries): self - { - $this->delegate(__FUNCTION__, \func_get_args()); - - return $this; - } - - public function setRetryDelay(int $retryDelay): self - { - $this->delegate(__FUNCTION__, \func_get_args()); - - return $this; - } - - public function getMaxRetries(): int - { - /** - * @var int $result - */ - $result = $this->delegate(__FUNCTION__, \func_get_args()); - - return $result; - } - - public function getRetryDelay(): int - { - /** - * @var int $result - */ - $result = $this->delegate(__FUNCTION__, \func_get_args()); - - return $result; - } } diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index e55674db17..4427e99639 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -7,8 +7,9 @@ use Redis as Client; use Throwable; use Utopia\Cache\Adapter; use Utopia\Cache\Adapter\Redis\Envelope; +use Utopia\Cache\Feature\Retryable; -class Redis implements Adapter +class Redis implements Adapter, Retryable { /** * @var Client @@ -72,7 +73,7 @@ class Redis implements Adapter */ public function setMaxRetries(int $maxRetries): self { - $this->maxRetries = max(self::MIN_RETRIES, min($maxRetries, self::MAX_RETRIES)); + $this->maxRetries = max(Retryable::MIN_RETRIES, min($maxRetries, Retryable::MAX_RETRIES)); return $this; } diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php index fcb9d9956c..388580704e 100644 --- a/src/Cache/Adapter/Redis/Multiplexing.php +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -25,10 +25,6 @@ use Utopia\Telemetry\Gauge; */ class Multiplexing implements Adapter, TelemetryFeature { - private int $maxRetries = 0; - - private int $retryDelay = 1000; // milliseconds - private ?ConnectionContext $connection = null; /** @@ -96,30 +92,6 @@ class Multiplexing implements Adapter, TelemetryFeature $this->shutdown(); } - public function setMaxRetries(int $maxRetries): self - { - $this->maxRetries = max(self::MIN_RETRIES, min($maxRetries, self::MAX_RETRIES)); - - return $this; - } - - public function setRetryDelay(int $retryDelay): self - { - $this->retryDelay = $retryDelay; - - return $this; - } - - public function getMaxRetries(): int - { - return $this->maxRetries; - } - - public function getRetryDelay(): int - { - return $this->retryDelay; - } - public function load(string $key, int $ttl, string $hash = ''): mixed { if (empty($hash)) { @@ -145,14 +117,10 @@ class Multiplexing implements Adapter, TelemetryFeature $hash = $key; } - try { - $value = Envelope::encode($data, time()); - $this->command(['HSET', $key, $hash, $value]); + $value = Envelope::encode($data, time()); + $this->command(['HSET', $key, $hash, $value]); - return $data; - } catch (Throwable $th) { - return false; - } + return $data; } public function touch(string $key, string $hash = ''): bool @@ -225,38 +193,23 @@ class Multiplexing implements Adapter, TelemetryFeature /** * Send a Redis command and block the calling coroutine until the response arrives. + * On a connection error, transparently reconnects once and retries — multiplexed + * connections drop all in-flight callers when they fail, so the only sensible + * recovery is to rebuild the connection before failing the call. * * @param array $args */ private function command(array $args): mixed { - $attempts = 0; - $maxAttempts = 1 + $this->maxRetries; + try { + return $this->dispatch($args); + } catch (ConnectionException $th) { + $this->ensureConnected(); - while (true) { - try { - return $this->dispatch($args); - } catch (ConnectionException $th) { - if (++$attempts >= $maxAttempts) { - throw $th; - } - - Coroutine::sleep($this->retryDelaySeconds()); - $this->ensureConnected(); - } + return $this->dispatch($args); } } - private function retryDelaySeconds(): float - { - $baseDelay = max(0, $this->retryDelay) / 1000; - if ($baseDelay === 0.0) { - return 0.0; - } - - return $baseDelay + mt_rand(0, 100) / 1000; - } - /** * Send a single command on the current connection and wait for its response. * Acquires the send lock; do not call from a context that already holds it. @@ -294,6 +247,18 @@ class Multiplexing implements Adapter, TelemetryFeature return $this->awaitResponse($context, $response); } + private function ensureConnected(): void + { + $locked = $this->lockSend(); + try { + if ($this->connection === null) { + $this->connect(); + } + } finally { + $this->unlockSend($locked); + } + } + /** * @param Channel $response */ @@ -310,18 +275,6 @@ class Multiplexing implements Adapter, TelemetryFeature return Client::unwrap($result); } - private function ensureConnected(): void - { - $locked = $this->lockSend(); - try { - if ($this->connection === null) { - $this->connect(); - } - } finally { - $this->unlockSend($locked); - } - } - /** * Caller must hold $sendLock when running inside a coroutine. */ diff --git a/src/Cache/Adapter/RedisCluster.php b/src/Cache/Adapter/RedisCluster.php index 7dcd4b51d5..e3a15552de 100644 --- a/src/Cache/Adapter/RedisCluster.php +++ b/src/Cache/Adapter/RedisCluster.php @@ -6,8 +6,9 @@ use Exception; use RedisCluster as Client; use Throwable; use Utopia\Cache\Adapter; +use Utopia\Cache\Feature\Retryable; -class RedisCluster implements Adapter +class RedisCluster implements Adapter, Retryable { /** * @var Client @@ -72,7 +73,7 @@ class RedisCluster implements Adapter */ public function setMaxRetries(int $maxRetries): self { - $this->maxRetries = max(self::MIN_RETRIES, min($maxRetries, self::MAX_RETRIES)); + $this->maxRetries = max(Retryable::MIN_RETRIES, min($maxRetries, Retryable::MAX_RETRIES)); return $this; } diff --git a/src/Cache/Adapter/Sharding.php b/src/Cache/Adapter/Sharding.php index 0521edff6a..53f9c8b3da 100644 --- a/src/Cache/Adapter/Sharding.php +++ b/src/Cache/Adapter/Sharding.php @@ -44,32 +44,6 @@ class Sharding implements Adapter $this->adapters = $adapters; } - /** - * @param int $maxRetries (0-10) - * @return self - */ - public function setMaxRetries(int $maxRetries): self - { - foreach ($this->adapters as $adapter) { - $adapter->setMaxRetries($maxRetries); - } - - return $this; - } - - /** - * @param int $retryDelay time in milliseconds - * @return self - */ - public function setRetryDelay(int $retryDelay): self - { - foreach ($this->adapters as $adapter) { - $adapter->setRetryDelay($retryDelay); - } - - return $this; - } - /** * @param string $key * @param int $ttl time in seconds @@ -186,20 +160,4 @@ class Sharding implements Adapter return $this->adapters[$index]; } - - /** - * @return int - */ - public function getMaxRetries(): int - { - return 0; - } - - /** - * @return int - */ - public function getRetryDelay(): int - { - return 0; - } } diff --git a/src/Cache/Feature/Retryable.php b/src/Cache/Feature/Retryable.php new file mode 100644 index 0000000000..b7fd90de83 --- /dev/null +++ b/src/Cache/Feature/Retryable.php @@ -0,0 +1,32 @@ + Date: Thu, 14 May 2026 15:03:48 +0100 Subject: [PATCH 2/2] style: drop trailing blank lines flagged by pint --- src/Cache/Adapter/CircuitBreaker.php | 1 - src/Cache/Adapter/Pool.php | 1 - 2 files changed, 2 deletions(-) diff --git a/src/Cache/Adapter/CircuitBreaker.php b/src/Cache/Adapter/CircuitBreaker.php index 4a6a711aa9..4e79c91059 100644 --- a/src/Cache/Adapter/CircuitBreaker.php +++ b/src/Cache/Adapter/CircuitBreaker.php @@ -110,5 +110,4 @@ class CircuitBreaker implements Adapter, Feature\Telemetry $this->adapter->setTelemetry($telemetry); } } - } diff --git a/src/Cache/Adapter/Pool.php b/src/Cache/Adapter/Pool.php index eb570abd33..5dc4714129 100644 --- a/src/Cache/Adapter/Pool.php +++ b/src/Cache/Adapter/Pool.php @@ -128,5 +128,4 @@ class Pool implements Adapter return $result; } - }