From b0cc20957a9fa1aac32ca3a2c1fb35c7d4fe2f51 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 11 May 2026 19:06:41 +0530 Subject: [PATCH 01/10] Add telemetry aware cache adapters --- .github/workflows/test.yml | 4 +- composer.json | 5 +- composer.lock | 70 +++++++++- src/Cache/Adapter/CircuitBreaker.php | 144 ++++++++++++++++++++ src/Cache/Adapter/Sharding.php | 13 +- src/Cache/Cache.php | 4 + src/Cache/TelemetryAware.php | 10 ++ tests/Cache/CircuitBreakerTest.php | 189 +++++++++++++++++++++++++++ tests/Cache/TelemetryTest.php | 62 +++++++++ 9 files changed, 492 insertions(+), 9 deletions(-) create mode 100644 src/Cache/Adapter/CircuitBreaker.php create mode 100644 src/Cache/TelemetryAware.php create mode 100644 tests/Cache/CircuitBreakerTest.php create mode 100644 tests/Cache/TelemetryTest.php diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 8fa5b551af..b6ffadd10b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -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'] 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 \ No newline at end of file + run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests diff --git a/composer.json b/composer.json index 0430191387..fa49881c28 100644 --- a/composer.json +++ b/composer.json @@ -17,12 +17,13 @@ "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.*" + "utopia-php/pools": "1.*", + "utopia-php/circuit-breaker": "0.1.*" }, "require-dev": { "phpunit/phpunit": "^9.3", diff --git a/composer.lock b/composer.lock index 0bb810d6b7..b3778540f8 100644 --- a/composer.lock +++ b/composer.lock @@ -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": "98407f18aba0717c2718b0ca54cf8fe8", "packages": [ { "name": "brick/math", @@ -1867,6 +1867,68 @@ }, "time": "2025-06-29T15:42:06+00:00" }, + { + "name": "utopia-php/circuit-breaker", + "version": "0.1.0", + "source": { + "type": "git", + "url": "https://github.com/utopia-php/circuit-breaker.git", + "reference": "a1647f71b95aa55b137d9667b316e3dffba60d2d" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/circuit-breaker/zipball/a1647f71b95aa55b137d9667b316e3dffba60d2d", + "reference": "a1647f71b95aa55b137d9667b316e3dffba60d2d", + "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.1.0" + }, + "time": "2026-04-22T06:36:27+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" } diff --git a/src/Cache/Adapter/CircuitBreaker.php b/src/Cache/Adapter/CircuitBreaker.php new file mode 100644 index 0000000000..77f6cc7298 --- /dev/null +++ b/src/Cache/Adapter/CircuitBreaker.php @@ -0,0 +1,144 @@ +breaker->call( + open: fn (): bool => false, + close: fn (): mixed => $this->adapter->load($key, $ttl, $hash), + ); + } + + public function save(string $key, array|string $data, string $hash = ''): bool|string|array + { + /** @var bool|string|array $result */ + $result = $this->breaker->call( + open: fn (): bool => false, + close: fn (): bool|string|array => $this->adapter->save($key, $data, $hash), + ); + + return $result; + } + + public function touch(string $key, string $hash = ''): bool + { + /** @var bool $result */ + $result = $this->breaker->call( + open: fn (): bool => false, + close: fn (): bool => $this->adapter->touch($key, $hash), + ); + + return $result; + } + + public function list(string $key): array + { + /** @var string[] $result */ + $result = $this->breaker->call( + open: fn (): array => [], + close: fn (): array => $this->adapter->list($key), + ); + + return $result; + } + + public function purge(string $key, string $hash = ''): bool + { + /** @var bool $result */ + $result = $this->breaker->call( + open: fn (): bool => false, + close: fn (): bool => $this->adapter->purge($key, $hash), + ); + + return $result; + } + + public function flush(): bool + { + /** @var bool $result */ + $result = $this->breaker->call( + open: fn (): bool => false, + close: fn (): bool => $this->adapter->flush(), + ); + + return $result; + } + + public function ping(): bool + { + /** @var bool $result */ + $result = $this->breaker->call( + open: fn (): bool => false, + close: fn (): bool => $this->adapter->ping(), + ); + + return $result; + } + + public function getSize(): int + { + /** @var int $result */ + $result = $this->breaker->call( + open: fn (): int => 0, + close: fn (): int => $this->adapter->getSize(), + ); + + 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 TelemetryAware) { + $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(); + } +} diff --git a/src/Cache/Adapter/Sharding.php b/src/Cache/Adapter/Sharding.php index 0521edff6a..bb507c2e2a 100644 --- a/src/Cache/Adapter/Sharding.php +++ b/src/Cache/Adapter/Sharding.php @@ -3,8 +3,10 @@ namespace Utopia\Cache\Adapter; use Utopia\Cache\Adapter; +use Utopia\Cache\TelemetryAware; +use Utopia\Telemetry\Adapter as Telemetry; -class Sharding implements Adapter +class Sharding implements Adapter, TelemetryAware { /** * @var Adapter[] @@ -70,6 +72,15 @@ class Sharding implements Adapter return $this; } + public function setTelemetry(Telemetry $telemetry): void + { + foreach ($this->adapters as $adapter) { + if ($adapter instanceof TelemetryAware) { + $adapter->setTelemetry($telemetry); + } + } + } + /** * @param string $key * @param int $ttl time in seconds diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index 324fb71da1..907b8db08d 100644 --- a/src/Cache/Cache.php +++ b/src/Cache/Cache.php @@ -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 TelemetryAware) { + $this->adapter->setTelemetry($telemetry); + } } /** diff --git a/src/Cache/TelemetryAware.php b/src/Cache/TelemetryAware.php new file mode 100644 index 0000000000..5b60794f57 --- /dev/null +++ b/src/Cache/TelemetryAware.php @@ -0,0 +1,10 @@ +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 test_returns_fallbacks_when_cache_operations_fail(): 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 test_breaker_short_circuits_after_failure(): 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 test_telemetry_can_be_attached_after_construction(): void + { + $telemetry = new TestTelemetry(); + $cache = new CircuitBreaker(new Memory(), new UtopiaCircuitBreaker()); + + $cache->setTelemetry($telemetry); + + $this->assertFalse($cache->load('missing', 60)); + /** @var object{values: list} $calls */ + $calls = $telemetry->counters['breaker.calls']; + $this->assertSame([1], $calls->values); + } + + public function test_telemetry_propagates_to_inner_adapter(): void + { + $telemetry = new TestTelemetry(); + $adapter = new class extends Memory implements TelemetryAware + { + 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 test_cache_telemetry_propagates_to_circuit_breaker_adapters(): 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} $calls */ + $calls = $telemetry->counters['breaker.calls']; + /** @var object{values: list} $operationDuration */ + $operationDuration = $telemetry->histograms['cache.operation.duration']; + $this->assertSame([1], $calls->values); + $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); + } +} diff --git a/tests/Cache/TelemetryTest.php b/tests/Cache/TelemetryTest.php new file mode 100644 index 0000000000..0cb7313880 --- /dev/null +++ b/tests/Cache/TelemetryTest.php @@ -0,0 +1,62 @@ +telemetry = $telemetry; + $this->calls++; + } + }; + + $cache = new Cache($adapter); + $telemetry = new None; + + $cache->setTelemetry($telemetry); + + $this->assertSame($telemetry, $adapter->telemetry); + $this->assertEquals(2, $adapter->calls); + } + + public function test_sharding_propagates_telemetry_to_adapters(): void + { + $adapter = new class extends Memory implements TelemetryAware + { + public ?Telemetry $telemetry = null; + + public int $calls = 0; + + public function setTelemetry(Telemetry $telemetry): void + { + $this->telemetry = $telemetry; + $this->calls++; + } + }; + $plainAdapter = new Memory; + $telemetry = new None; + + $sharding = new Sharding([$adapter, $plainAdapter]); + $sharding->setTelemetry($telemetry); + + $this->assertSame($telemetry, $adapter->telemetry); + $this->assertEquals(1, $adapter->calls); + } +} From f908ae81488381b4d1e97445ec5eae54ca0c955e Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 12 May 2026 10:11:25 +0530 Subject: [PATCH 02/10] chore: bump circuit breaker dependency --- composer.json | 2 +- composer.lock | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/composer.json b/composer.json index fa49881c28..3a186b1439 100644 --- a/composer.json +++ b/composer.json @@ -23,7 +23,7 @@ "ext-memcached": "*", "utopia-php/telemetry": "*", "utopia-php/pools": "1.*", - "utopia-php/circuit-breaker": "0.1.*" + "utopia-php/circuit-breaker": "0.3.0" }, "require-dev": { "phpunit/phpunit": "^9.3", diff --git a/composer.lock b/composer.lock index b3778540f8..ba2785b22f 100644 --- a/composer.lock +++ b/composer.lock @@ -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": "98407f18aba0717c2718b0ca54cf8fe8", + "content-hash": "acd3850b4ddd76841507a3a77c7192c7", "packages": [ { "name": "brick/math", @@ -1869,16 +1869,16 @@ }, { "name": "utopia-php/circuit-breaker", - "version": "0.1.0", + "version": "0.3.0", "source": { "type": "git", "url": "https://github.com/utopia-php/circuit-breaker.git", - "reference": "a1647f71b95aa55b137d9667b316e3dffba60d2d" + "reference": "064243c1667778c00abf027ff53a735a228776de" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/circuit-breaker/zipball/a1647f71b95aa55b137d9667b316e3dffba60d2d", - "reference": "a1647f71b95aa55b137d9667b316e3dffba60d2d", + "url": "https://api.github.com/repos/utopia-php/circuit-breaker/zipball/064243c1667778c00abf027ff53a735a228776de", + "reference": "064243c1667778c00abf027ff53a735a228776de", "shasum": "" }, "require": { @@ -1925,9 +1925,9 @@ ], "support": { "issues": "https://github.com/utopia-php/circuit-breaker/issues", - "source": "https://github.com/utopia-php/circuit-breaker/tree/0.1.0" + "source": "https://github.com/utopia-php/circuit-breaker/tree/0.3.0" }, - "time": "2026-04-22T06:36:27+00:00" + "time": "2026-05-12T04:27:08+00:00" }, { "name": "utopia-php/pools", From 8bbb543ae401515a243d1bd3986cd224f966188d Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 12 May 2026 10:14:12 +0530 Subject: [PATCH 03/10] chore: allow circuit breaker patch updates --- composer.json | 2 +- composer.lock | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/composer.json b/composer.json index 3a186b1439..f9dc912e97 100644 --- a/composer.json +++ b/composer.json @@ -23,7 +23,7 @@ "ext-memcached": "*", "utopia-php/telemetry": "*", "utopia-php/pools": "1.*", - "utopia-php/circuit-breaker": "0.3.0" + "utopia-php/circuit-breaker": "0.3.*" }, "require-dev": { "phpunit/phpunit": "^9.3", diff --git a/composer.lock b/composer.lock index ba2785b22f..b4e2e4e452 100644 --- a/composer.lock +++ b/composer.lock @@ -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": "acd3850b4ddd76841507a3a77c7192c7", + "content-hash": "1d0ace4df177cb2519358831ae65ec36", "packages": [ { "name": "brick/math", From c66698802a086b1533dd97b42b577ec33c766535 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 12 May 2026 10:17:13 +0530 Subject: [PATCH 04/10] chore: sort composer dependencies alphabetically --- composer.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/composer.json b/composer.json index f9dc912e97..61905b9301 100644 --- a/composer.json +++ b/composer.json @@ -19,17 +19,17 @@ "require": { "php": ">=8.2", "ext-json": "*", - "ext-redis": "*", "ext-memcached": "*", - "utopia-php/telemetry": "*", + "ext-redis": "*", + "utopia-php/circuit-breaker": "0.3.*", "utopia-php/pools": "1.*", - "utopia-php/circuit-breaker": "0.3.*" + "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": { From 1a8b8b0ecf0de3a482c4e8acc1a203f095b04921 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 12 May 2026 15:12:29 +0530 Subject: [PATCH 05/10] Add PHP 8.4 CI coverage --- .github/workflows/test.yml | 2 +- Dockerfile.php-8.1 => Dockerfile.php-8.4 | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) rename Dockerfile.php-8.1 => Dockerfile.php-8.4 (89%) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b6ffadd10b..660061233e 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -7,7 +7,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - php-versions: ['8.2', '8.3'] + php-versions: ['8.2', '8.3', '8.4'] steps: - name: Checkout repository diff --git a/Dockerfile.php-8.1 b/Dockerfile.php-8.4 similarity index 89% rename from Dockerfile.php-8.1 rename to Dockerfile.php-8.4 index 1d3fc49075..3246c041ac 100644 --- a/Dockerfile.php-8.1 +++ b/Dockerfile.php-8.4 @@ -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 \ From f8fa206a130371d392d9d13c436d966f7f006c56 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 12 May 2026 15:45:41 +0530 Subject: [PATCH 06/10] Refactor circuit breaker adapter delegation --- src/Cache/Adapter/CircuitBreaker.php | 55 ++++++++++++---------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/src/Cache/Adapter/CircuitBreaker.php b/src/Cache/Adapter/CircuitBreaker.php index 77f6cc7298..2fb9e9eb93 100644 --- a/src/Cache/Adapter/CircuitBreaker.php +++ b/src/Cache/Adapter/CircuitBreaker.php @@ -15,21 +15,32 @@ class CircuitBreaker implements Adapter, TelemetryAware ) { } - public function load(string $key, int $ttl, string $hash = ''): mixed + /** + * 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 $args + * @return mixed + */ + public function delegate(string $method, array $args, mixed $fallback): mixed { return $this->breaker->call( - open: fn (): bool => false, - close: fn (): mixed => $this->adapter->load($key, $ttl, $hash), + 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 $result */ - $result = $this->breaker->call( - open: fn (): bool => false, - close: fn (): bool|string|array => $this->adapter->save($key, $data, $hash), - ); + $result = $this->delegate(__FUNCTION__, \func_get_args(), false); return $result; } @@ -37,10 +48,7 @@ class CircuitBreaker implements Adapter, TelemetryAware public function touch(string $key, string $hash = ''): bool { /** @var bool $result */ - $result = $this->breaker->call( - open: fn (): bool => false, - close: fn (): bool => $this->adapter->touch($key, $hash), - ); + $result = $this->delegate(__FUNCTION__, \func_get_args(), false); return $result; } @@ -48,10 +56,7 @@ class CircuitBreaker implements Adapter, TelemetryAware public function list(string $key): array { /** @var string[] $result */ - $result = $this->breaker->call( - open: fn (): array => [], - close: fn (): array => $this->adapter->list($key), - ); + $result = $this->delegate(__FUNCTION__, \func_get_args(), []); return $result; } @@ -59,10 +64,7 @@ class CircuitBreaker implements Adapter, TelemetryAware public function purge(string $key, string $hash = ''): bool { /** @var bool $result */ - $result = $this->breaker->call( - open: fn (): bool => false, - close: fn (): bool => $this->adapter->purge($key, $hash), - ); + $result = $this->delegate(__FUNCTION__, \func_get_args(), false); return $result; } @@ -70,10 +72,7 @@ class CircuitBreaker implements Adapter, TelemetryAware public function flush(): bool { /** @var bool $result */ - $result = $this->breaker->call( - open: fn (): bool => false, - close: fn (): bool => $this->adapter->flush(), - ); + $result = $this->delegate(__FUNCTION__, \func_get_args(), false); return $result; } @@ -81,10 +80,7 @@ class CircuitBreaker implements Adapter, TelemetryAware public function ping(): bool { /** @var bool $result */ - $result = $this->breaker->call( - open: fn (): bool => false, - close: fn (): bool => $this->adapter->ping(), - ); + $result = $this->delegate(__FUNCTION__, \func_get_args(), false); return $result; } @@ -92,10 +88,7 @@ class CircuitBreaker implements Adapter, TelemetryAware public function getSize(): int { /** @var int $result */ - $result = $this->breaker->call( - open: fn (): int => 0, - close: fn (): int => $this->adapter->getSize(), - ); + $result = $this->delegate(__FUNCTION__, \func_get_args(), 0); return $result; } From 59332499cf4c897897e5db0f6f9c799ee54bd33f Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 12 May 2026 15:51:38 +0530 Subject: [PATCH 07/10] Stop propagating telemetry through sharding --- src/Cache/Adapter/Sharding.php | 13 +------------ tests/Cache/CircuitBreakerTest.php | 6 ++---- tests/Cache/TelemetryTest.php | 25 ------------------------- 3 files changed, 3 insertions(+), 41 deletions(-) diff --git a/src/Cache/Adapter/Sharding.php b/src/Cache/Adapter/Sharding.php index bb507c2e2a..0521edff6a 100644 --- a/src/Cache/Adapter/Sharding.php +++ b/src/Cache/Adapter/Sharding.php @@ -3,10 +3,8 @@ namespace Utopia\Cache\Adapter; use Utopia\Cache\Adapter; -use Utopia\Cache\TelemetryAware; -use Utopia\Telemetry\Adapter as Telemetry; -class Sharding implements Adapter, TelemetryAware +class Sharding implements Adapter { /** * @var Adapter[] @@ -72,15 +70,6 @@ class Sharding implements Adapter, TelemetryAware return $this; } - public function setTelemetry(Telemetry $telemetry): void - { - foreach ($this->adapters as $adapter) { - if ($adapter instanceof TelemetryAware) { - $adapter->setTelemetry($telemetry); - } - } - } - /** * @param string $key * @param int $ttl time in seconds diff --git a/tests/Cache/CircuitBreakerTest.php b/tests/Cache/CircuitBreakerTest.php index c069e77869..6805750fa3 100644 --- a/tests/Cache/CircuitBreakerTest.php +++ b/tests/Cache/CircuitBreakerTest.php @@ -84,7 +84,7 @@ class CircuitBreakerTest extends TestCase $this->assertSame($telemetry, $adapter->telemetry); } - public function test_cache_telemetry_propagates_to_circuit_breaker_adapters(): void + public function test_cache_telemetry_does_not_propagate_through_sharding(): void { $telemetry = new TestTelemetry(); $cache = new Cache(new Sharding([ @@ -94,11 +94,9 @@ class CircuitBreakerTest extends TestCase $cache->setTelemetry($telemetry); $this->assertSame('value', $cache->save('key', 'value')); - /** @var object{values: list} $calls */ - $calls = $telemetry->counters['breaker.calls']; /** @var object{values: list} $operationDuration */ $operationDuration = $telemetry->histograms['cache.operation.duration']; - $this->assertSame([1], $calls->values); + $this->assertArrayNotHasKey('breaker.calls', $telemetry->counters); $this->assertCount(1, $operationDuration->values); } diff --git a/tests/Cache/TelemetryTest.php b/tests/Cache/TelemetryTest.php index 0cb7313880..6c0f96cc0b 100644 --- a/tests/Cache/TelemetryTest.php +++ b/tests/Cache/TelemetryTest.php @@ -4,7 +4,6 @@ namespace Utopia\Tests; use PHPUnit\Framework\TestCase; use Utopia\Cache\Adapter\Memory; -use Utopia\Cache\Adapter\Sharding; use Utopia\Cache\Cache; use Utopia\Cache\TelemetryAware; use Utopia\Telemetry\Adapter as Telemetry; @@ -35,28 +34,4 @@ class TelemetryTest extends TestCase $this->assertSame($telemetry, $adapter->telemetry); $this->assertEquals(2, $adapter->calls); } - - public function test_sharding_propagates_telemetry_to_adapters(): void - { - $adapter = new class extends Memory implements TelemetryAware - { - public ?Telemetry $telemetry = null; - - public int $calls = 0; - - public function setTelemetry(Telemetry $telemetry): void - { - $this->telemetry = $telemetry; - $this->calls++; - } - }; - $plainAdapter = new Memory; - $telemetry = new None; - - $sharding = new Sharding([$adapter, $plainAdapter]); - $sharding->setTelemetry($telemetry); - - $this->assertSame($telemetry, $adapter->telemetry); - $this->assertEquals(1, $adapter->calls); - } } From 1575840c0b4cc035b2ea2a8e2ac0d61ef36dc4bf Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 12 May 2026 15:55:43 +0530 Subject: [PATCH 08/10] Move telemetry feature interface --- src/Cache/Adapter/CircuitBreaker.php | 6 +++--- src/Cache/Cache.php | 2 +- src/Cache/Feature/Telemetry.php | 10 ++++++++++ src/Cache/TelemetryAware.php | 10 ---------- tests/Cache/CircuitBreakerTest.php | 4 ++-- tests/Cache/TelemetryTest.php | 4 ++-- 6 files changed, 18 insertions(+), 18 deletions(-) create mode 100644 src/Cache/Feature/Telemetry.php delete mode 100644 src/Cache/TelemetryAware.php diff --git a/src/Cache/Adapter/CircuitBreaker.php b/src/Cache/Adapter/CircuitBreaker.php index 2fb9e9eb93..3ef064689d 100644 --- a/src/Cache/Adapter/CircuitBreaker.php +++ b/src/Cache/Adapter/CircuitBreaker.php @@ -3,11 +3,11 @@ namespace Utopia\Cache\Adapter; use Utopia\Cache\Adapter; -use Utopia\Cache\TelemetryAware; +use Utopia\Cache\Feature; use Utopia\CircuitBreaker\CircuitBreaker as UtopiaCircuitBreaker; use Utopia\Telemetry\Adapter as Telemetry; -class CircuitBreaker implements Adapter, TelemetryAware +class CircuitBreaker implements Adapter, Feature\Telemetry { public function __construct( private readonly Adapter $adapter, @@ -106,7 +106,7 @@ class CircuitBreaker implements Adapter, TelemetryAware { $this->breaker->setTelemetry($telemetry); - if ($this->adapter instanceof TelemetryAware) { + if ($this->adapter instanceof Feature\Telemetry) { $this->adapter->setTelemetry($telemetry); } } diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index 907b8db08d..5a9d4c5695 100644 --- a/src/Cache/Cache.php +++ b/src/Cache/Cache.php @@ -34,7 +34,7 @@ class Cache ['ExplicitBucketBoundaries' => [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1]] ); - if ($this->adapter instanceof TelemetryAware) { + if ($this->adapter instanceof Feature\Telemetry) { $this->adapter->setTelemetry($telemetry); } } diff --git a/src/Cache/Feature/Telemetry.php b/src/Cache/Feature/Telemetry.php new file mode 100644 index 0000000000..f7026eb262 --- /dev/null +++ b/src/Cache/Feature/Telemetry.php @@ -0,0 +1,10 @@ + Date: Tue, 12 May 2026 15:58:43 +0530 Subject: [PATCH 09/10] Use camel case circuit breaker test names --- tests/Cache/CircuitBreakerTest.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tests/Cache/CircuitBreakerTest.php b/tests/Cache/CircuitBreakerTest.php index fb0595ac62..849c677c22 100644 --- a/tests/Cache/CircuitBreakerTest.php +++ b/tests/Cache/CircuitBreakerTest.php @@ -16,7 +16,7 @@ use Utopia\Telemetry\Adapter\Test as TestTelemetry; class CircuitBreakerTest extends TestCase { - public function test_passes_through_healthy_cache_operations(): void + public function testPassesThroughHealthyCacheOperations(): void { $adapter = new Memory(); $cache = new CircuitBreaker($adapter, new UtopiaCircuitBreaker()); @@ -30,7 +30,7 @@ class CircuitBreakerTest extends TestCase $this->assertFalse($cache->load('key', 60)); } - public function test_returns_fallbacks_when_cache_operations_fail(): void + public function testReturnsFallbacksWhenCacheOperationsFail(): void { $this->assertFalse($this->failingCache()->load('key', 60)); $this->assertFalse($this->failingCache()->save('key', 'value')); @@ -42,7 +42,7 @@ class CircuitBreakerTest extends TestCase $this->assertSame(0, $this->failingCache()->getSize()); } - public function test_breaker_short_circuits_after_failure(): void + public function testBreakerShortCircuitsAfterFailure(): void { $adapter = new CountingFailingAdapter(); $cache = new CircuitBreaker($adapter, new UtopiaCircuitBreaker(threshold: 1)); @@ -52,7 +52,7 @@ class CircuitBreakerTest extends TestCase $this->assertSame(1, $adapter->loads); } - public function test_telemetry_can_be_attached_after_construction(): void + public function testTelemetryCanBeAttachedAfterConstruction(): void { $telemetry = new TestTelemetry(); $cache = new CircuitBreaker(new Memory(), new UtopiaCircuitBreaker()); @@ -65,7 +65,7 @@ class CircuitBreakerTest extends TestCase $this->assertSame([1], $calls->values); } - public function test_telemetry_propagates_to_inner_adapter(): void + public function testTelemetryPropagatesToInnerAdapter(): void { $telemetry = new TestTelemetry(); $adapter = new class extends Memory implements Feature\Telemetry @@ -84,7 +84,7 @@ class CircuitBreakerTest extends TestCase $this->assertSame($telemetry, $adapter->telemetry); } - public function test_cache_telemetry_does_not_propagate_through_sharding(): void + public function testCacheTelemetryDoesNotPropagateThroughSharding(): void { $telemetry = new TestTelemetry(); $cache = new Cache(new Sharding([ From 2575accaccfabe10fd80f7096d0af30f92cd5827 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 12 May 2026 16:08:10 +0530 Subject: [PATCH 10/10] Use camel case telemetry test name --- tests/Cache/TelemetryTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/Cache/TelemetryTest.php b/tests/Cache/TelemetryTest.php index d1e760e3b9..7993ae0c7c 100644 --- a/tests/Cache/TelemetryTest.php +++ b/tests/Cache/TelemetryTest.php @@ -11,7 +11,7 @@ use Utopia\Telemetry\Adapter\None; class TelemetryTest extends TestCase { - public function test_cache_propagates_telemetry_to_adapter(): void + public function testCachePropagatesTelemetryToAdapter(): void { $adapter = new class extends Memory implements Feature\Telemetry {