diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 8fa5b551af..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.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 \ No newline at end of file + run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests 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 \ diff --git a/composer.json b/composer.json index 0430191387..61905b9301 100644 --- a/composer.json +++ b/composer.json @@ -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": { diff --git a/composer.lock b/composer.lock index 0bb810d6b7..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": "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" } diff --git a/src/Cache/Adapter/CircuitBreaker.php b/src/Cache/Adapter/CircuitBreaker.php new file mode 100644 index 0000000000..3ef064689d --- /dev/null +++ b/src/Cache/Adapter/CircuitBreaker.php @@ -0,0 +1,137 @@ + $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 $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(); + } +} diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index 324fb71da1..5a9d4c5695 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 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 @@ +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} $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} $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); + } +} diff --git a/tests/Cache/TelemetryTest.php b/tests/Cache/TelemetryTest.php new file mode 100644 index 0000000000..7993ae0c7c --- /dev/null +++ b/tests/Cache/TelemetryTest.php @@ -0,0 +1,37 @@ +telemetry = $telemetry; + $this->calls++; + } + }; + + $cache = new Cache($adapter); + $telemetry = new None; + + $cache->setTelemetry($telemetry); + + $this->assertSame($telemetry, $adapter->telemetry); + $this->assertEquals(2, $adapter->calls); + } +}