Merge pull request #69 from utopia-php/feat/telemetry-aware-adapters

Add circuit breaker cache adapter
This commit is contained in:
Chirag Aggarwal authored and GitHub committed 2026-05-12 16:25:15 +05:30
commit ef1d122a46
9 files changed
+455 -14

No files matched your search

+2 -2
View File
@@ -7,7 +7,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
php-versions: ['8.1', '8.2', '8.3']
php-versions: ['8.2', '8.3', '8.4']
steps:
- name: Checkout repository
@@ -25,4 +25,4 @@ jobs:
sleep 10
- name: Run Tests
run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests
run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests
+4 -1
View File
@@ -11,7 +11,7 @@ COPY composer.json /usr/local/src/
RUN composer update --ignore-platform-reqs --optimize-autoloader \
--no-plugins --no-scripts --prefer-dist
FROM appwrite/utopia-base:php-8.1-0.1.2 as final
FROM appwrite/utopia-base:php-8.4-1.0.0 as final
ENV PHP_MEMCACHED_VERSION=v3.2.0
@@ -23,6 +23,9 @@ RUN \
apk update \
&& apk add --no-cache make automake autoconf g++ gcc zlib-dev libmemcached-dev docker-cli \
&& rm -rf /var/cache/apk/*
RUN echo extension=redis.so >> /usr/local/etc/php/conf.d/redis.ini
RUN \
+8 -7
View File
@@ -17,18 +17,19 @@
"psr-4": {"Utopia\\Tests\\": "tests/Cache"}
},
"require": {
"php": ">=8.0",
"php": ">=8.2",
"ext-json": "*",
"ext-redis": "*",
"ext-memcached": "*",
"utopia-php/telemetry": "*",
"utopia-php/pools": "1.*"
"ext-redis": "*",
"utopia-php/circuit-breaker": "0.3.*",
"utopia-php/pools": "1.*",
"utopia-php/telemetry": "*"
},
"require-dev": {
"phpunit/phpunit": "^9.3",
"vimeo/psalm": "4.13.1",
"laravel/pint": "1.2.*",
"phpstan/phpstan": "^1.12",
"laravel/pint": "1.2.*"
"phpunit/phpunit": "^9.3",
"vimeo/psalm": "4.13.1"
},
"config": {
"allow-plugins": {
Generated
+66 -4
View File
@@ -4,7 +4,7 @@
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "d33703ed3a1dc42fb598493d1eae8d90",
"content-hash": "1d0ace4df177cb2519358831ae65ec36",
"packages": [
{
"name": "brick/math",
@@ -1867,6 +1867,68 @@
},
"time": "2025-06-29T15:42:06+00:00"
},
{
"name": "utopia-php/circuit-breaker",
"version": "0.3.0",
"source": {
"type": "git",
"url": "https://github.com/utopia-php/circuit-breaker.git",
"reference": "064243c1667778c00abf027ff53a735a228776de"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/utopia-php/circuit-breaker/zipball/064243c1667778c00abf027ff53a735a228776de",
"reference": "064243c1667778c00abf027ff53a735a228776de",
"shasum": ""
},
"require": {
"php": ">=8.2"
},
"require-dev": {
"laravel/pint": "^1.29",
"phpstan/phpstan": "^2.1",
"phpunit/phpunit": "^10.0",
"utopia-php/telemetry": "0.2.*"
},
"suggest": {
"ext-opentelemetry": "Required by utopia-php/telemetry when using OpenTelemetry metrics.",
"ext-protobuf": "Required by utopia-php/telemetry when using OpenTelemetry metrics.",
"ext-redis": "Required when using Utopia\\CircuitBreaker\\Adapter\\Redis with the phpredis extension.",
"ext-swoole": "Required when using Utopia\\CircuitBreaker\\Adapter\\SwooleTable.",
"utopia-php/telemetry": "Required when passing telemetry adapters or running the local telemetry demo."
},
"type": "library",
"autoload": {
"psr-4": {
"Utopia\\CircuitBreaker\\": "src/CircuitBreaker"
}
},
"notification-url": "https://packagist.org/downloads/",
"license": [
"MIT"
],
"authors": [
{
"name": "Team Appwrite",
"email": "team@appwrite.io"
}
],
"description": "Light & simple Circuit Breaker for PHP to prevent cascading failures in distributed systems.",
"keywords": [
"circuit-breaker",
"fault-tolerance",
"framework",
"php",
"resilience",
"upf",
"utopia"
],
"support": {
"issues": "https://github.com/utopia-php/circuit-breaker/issues",
"source": "https://github.com/utopia-php/circuit-breaker/tree/0.3.0"
},
"time": "2026-05-12T04:27:08+00:00"
},
{
"name": "utopia-php/pools",
"version": "1.0.0",
@@ -5419,15 +5481,15 @@
],
"aliases": [],
"minimum-stability": "stable",
"stability-flags": [],
"stability-flags": {},
"prefer-stable": false,
"prefer-lowest": false,
"platform": {
"php": ">=8.0",
"php": ">=8.2",
"ext-json": "*",
"ext-redis": "*",
"ext-memcached": "*"
},
"platform-dev": {},
"plugin-api-version": "2.6.0"
"plugin-api-version": "2.9.0"
}
+137
View File
@@ -0,0 +1,137 @@
<?php
namespace Utopia\Cache\Adapter;
use Utopia\Cache\Adapter;
use Utopia\Cache\Feature;
use Utopia\CircuitBreaker\CircuitBreaker as UtopiaCircuitBreaker;
use Utopia\Telemetry\Adapter as Telemetry;
class CircuitBreaker implements Adapter, Feature\Telemetry
{
public function __construct(
private readonly Adapter $adapter,
private readonly UtopiaCircuitBreaker $breaker,
) {
}
/**
* Forward method calls to the internal adapter through the circuit breaker.
*
* Required because __call() can't be used to implement abstract methods.
*
* @param string $method
* @param array<mixed> $args
* @return mixed
*/
public function delegate(string $method, array $args, mixed $fallback): mixed
{
return $this->breaker->call(
open: fn (): mixed => $fallback,
close: fn (): mixed => $this->adapter->{$method}(...$args),
);
}
public function load(string $key, int $ttl, string $hash = ''): mixed
{
return $this->delegate(__FUNCTION__, \func_get_args(), false);
}
public function save(string $key, array|string $data, string $hash = ''): bool|string|array
{
/** @var bool|string|array<int|string, mixed> $result */
$result = $this->delegate(__FUNCTION__, \func_get_args(), false);
return $result;
}
public function touch(string $key, string $hash = ''): bool
{
/** @var bool $result */
$result = $this->delegate(__FUNCTION__, \func_get_args(), false);
return $result;
}
public function list(string $key): array
{
/** @var string[] $result */
$result = $this->delegate(__FUNCTION__, \func_get_args(), []);
return $result;
}
public function purge(string $key, string $hash = ''): bool
{
/** @var bool $result */
$result = $this->delegate(__FUNCTION__, \func_get_args(), false);
return $result;
}
public function flush(): bool
{
/** @var bool $result */
$result = $this->delegate(__FUNCTION__, \func_get_args(), false);
return $result;
}
public function ping(): bool
{
/** @var bool $result */
$result = $this->delegate(__FUNCTION__, \func_get_args(), false);
return $result;
}
public function getSize(): int
{
/** @var int $result */
$result = $this->delegate(__FUNCTION__, \func_get_args(), 0);
return $result;
}
public function getName(?string $key = null): string
{
try {
return $this->adapter->getName($key);
} catch (\Throwable) {
return 'circuit-breaker';
}
}
public function setTelemetry(Telemetry $telemetry): void
{
$this->breaker->setTelemetry($telemetry);
if ($this->adapter instanceof Feature\Telemetry) {
$this->adapter->setTelemetry($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();
}
}
+4
View File
@@ -33,6 +33,10 @@ class Cache
null,
['ExplicitBucketBoundaries' => [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1]]
);
if ($this->adapter instanceof Feature\Telemetry) {
$this->adapter->setTelemetry($telemetry);
}
}
/**
+10
View File
@@ -0,0 +1,10 @@
<?php
namespace Utopia\Cache\Feature;
use Utopia\Telemetry\Adapter as TelemetryAdapter;
interface Telemetry
{
public function setTelemetry(TelemetryAdapter $telemetry): void;
}
+187
View File
@@ -0,0 +1,187 @@
<?php
namespace Utopia\Tests;
use PHPUnit\Framework\TestCase;
use RuntimeException;
use Utopia\Cache\Adapter;
use Utopia\Cache\Adapter\CircuitBreaker;
use Utopia\Cache\Adapter\Memory;
use Utopia\Cache\Adapter\Sharding;
use Utopia\Cache\Cache;
use Utopia\Cache\Feature;
use Utopia\CircuitBreaker\CircuitBreaker as UtopiaCircuitBreaker;
use Utopia\Telemetry\Adapter as Telemetry;
use Utopia\Telemetry\Adapter\Test as TestTelemetry;
class CircuitBreakerTest extends TestCase
{
public function testPassesThroughHealthyCacheOperations(): void
{
$adapter = new Memory();
$cache = new CircuitBreaker($adapter, new UtopiaCircuitBreaker());
$this->assertSame('value', $cache->save('key', 'value'));
$this->assertSame('value', $cache->load('key', 60));
$this->assertTrue($cache->touch('key'));
$this->assertSame(1, $cache->getSize());
$this->assertTrue($cache->ping());
$this->assertTrue($cache->purge('key'));
$this->assertFalse($cache->load('key', 60));
}
public function testReturnsFallbacksWhenCacheOperationsFail(): void
{
$this->assertFalse($this->failingCache()->load('key', 60));
$this->assertFalse($this->failingCache()->save('key', 'value'));
$this->assertFalse($this->failingCache()->touch('key'));
$this->assertSame([], $this->failingCache()->list('key'));
$this->assertFalse($this->failingCache()->purge('key'));
$this->assertFalse($this->failingCache()->flush());
$this->assertFalse($this->failingCache()->ping());
$this->assertSame(0, $this->failingCache()->getSize());
}
public function testBreakerShortCircuitsAfterFailure(): void
{
$adapter = new CountingFailingAdapter();
$cache = new CircuitBreaker($adapter, new UtopiaCircuitBreaker(threshold: 1));
$this->assertFalse($cache->load('key', 60));
$this->assertFalse($cache->load('key', 60));
$this->assertSame(1, $adapter->loads);
}
public function testTelemetryCanBeAttachedAfterConstruction(): void
{
$telemetry = new TestTelemetry();
$cache = new CircuitBreaker(new Memory(), new UtopiaCircuitBreaker());
$cache->setTelemetry($telemetry);
$this->assertFalse($cache->load('missing', 60));
/** @var object{values: list<int|float>} $calls */
$calls = $telemetry->counters['breaker.calls'];
$this->assertSame([1], $calls->values);
}
public function testTelemetryPropagatesToInnerAdapter(): void
{
$telemetry = new TestTelemetry();
$adapter = new class extends Memory implements Feature\Telemetry
{
public ?Telemetry $telemetry = null;
public function setTelemetry(Telemetry $telemetry): void
{
$this->telemetry = $telemetry;
}
};
$cache = new CircuitBreaker($adapter, new UtopiaCircuitBreaker());
$cache->setTelemetry($telemetry);
$this->assertSame($telemetry, $adapter->telemetry);
}
public function testCacheTelemetryDoesNotPropagateThroughSharding(): void
{
$telemetry = new TestTelemetry();
$cache = new Cache(new Sharding([
new CircuitBreaker(new Memory(), new UtopiaCircuitBreaker()),
]));
$cache->setTelemetry($telemetry);
$this->assertSame('value', $cache->save('key', 'value'));
/** @var object{values: list<int|float>} $operationDuration */
$operationDuration = $telemetry->histograms['cache.operation.duration'];
$this->assertArrayNotHasKey('breaker.calls', $telemetry->counters);
$this->assertCount(1, $operationDuration->values);
}
private function failingCache(): CircuitBreaker
{
return new CircuitBreaker(new FailingAdapter(), new UtopiaCircuitBreaker(threshold: 1));
}
}
class FailingAdapter implements Adapter
{
public function load(string $key, int $ttl, string $hash = ''): mixed
{
throw new RuntimeException('Cache failed.');
}
public function save(string $key, array|string $data, string $hash = ''): bool|string|array
{
throw new RuntimeException('Cache failed.');
}
public function touch(string $key, string $hash = ''): bool
{
throw new RuntimeException('Cache failed.');
}
public function list(string $key): array
{
throw new RuntimeException('Cache failed.');
}
public function purge(string $key, string $hash = ''): bool
{
throw new RuntimeException('Cache failed.');
}
public function flush(): bool
{
throw new RuntimeException('Cache failed.');
}
public function ping(): bool
{
throw new RuntimeException('Cache failed.');
}
public function getSize(): int
{
throw new RuntimeException('Cache failed.');
}
public function getName(?string $key = null): string
{
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
{
public int $loads = 0;
public function load(string $key, int $ttl, string $hash = ''): mixed
{
$this->loads++;
return parent::load($key, $ttl, $hash);
}
}
+37
View File
@@ -0,0 +1,37 @@
<?php
namespace Utopia\Tests;
use PHPUnit\Framework\TestCase;
use Utopia\Cache\Adapter\Memory;
use Utopia\Cache\Cache;
use Utopia\Cache\Feature;
use Utopia\Telemetry\Adapter as Telemetry;
use Utopia\Telemetry\Adapter\None;
class TelemetryTest extends TestCase
{
public function testCachePropagatesTelemetryToAdapter(): void
{
$adapter = new class extends Memory implements Feature\Telemetry
{
public ?Telemetry $telemetry = null;
public int $calls = 0;
public function setTelemetry(Telemetry $telemetry): void
{
$this->telemetry = $telemetry;
$this->calls++;
}
};
$cache = new Cache($adapter);
$telemetry = new None;
$cache->setTelemetry($telemetry);
$this->assertSame($telemetry, $adapter->telemetry);
$this->assertEquals(2, $adapter->calls);
}
}