mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
Merge pull request #69 from utopia-php/feat/telemetry-aware-adapters
Add circuit breaker cache adapter
This commit is contained in:
9 files changed
+455
-14
No files matched your search
@@ -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
|
||||
@@ -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
@@ -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
@@ -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"
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
<?php
|
||||
|
||||
namespace Utopia\Cache\Feature;
|
||||
|
||||
use Utopia\Telemetry\Adapter as TelemetryAdapter;
|
||||
|
||||
interface Telemetry
|
||||
{
|
||||
public function setTelemetry(TelemetryAdapter $telemetry): void;
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user