refactor: extract Retryable into a Feature interface

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.
This commit is contained in:
loks0n committed 2026-05-14 15:01:00 +01:00
1 parent fc3b9ae33c
commit d13eb23660
14 files changed
+67 -324

No files matched your search

-26
View File
@@ -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;
}
-23
View File
@@ -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();
}
}
-34
View File
@@ -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;
}
}
+3 -2
View File
@@ -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;
}
+3 -2
View File
@@ -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;
}
-34
View File
@@ -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;
}
}
-34
View File
@@ -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;
}
}
-33
View File
@@ -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;
}
}
+3 -2
View File
@@ -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;
}
+23 -70
View File
@@ -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<int|string> $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<mixed> $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.
*/
+3 -2
View File
@@ -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;
}
-42
View File
@@ -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;
}
}
+32
View File
@@ -0,0 +1,32 @@
<?php
namespace Utopia\Cache\Feature;
interface Retryable
{
const MIN_RETRIES = 0;
const MAX_RETRIES = 10;
/**
* @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;
}
-20
View File
@@ -152,26 +152,6 @@ class FailingAdapter implements Adapter
{
return 'failing';
}
public function setMaxRetries(int $maxRetries): self
{
return $this;
}
public function setRetryDelay(int $retryDelay): self
{
return $this;
}
public function getMaxRetries(): int
{
return 0;
}
public function getRetryDelay(): int
{
return 0;
}
}
class CountingFailingAdapter extends FailingAdapter