diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 660061233e..9f0b8e3f58 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', '8.4'] + php-versions: ['8.3', '8.4', '8.5'] 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 \ No newline at end of file diff --git a/Dockerfile.php-8.3 b/Dockerfile.php-8.3 index ec4ff20edb..aa4f308fd1 100644 --- a/Dockerfile.php-8.3 +++ b/Dockerfile.php-8.3 @@ -1,4 +1,4 @@ -FROM composer:2.0 as step0 +FROM composer:2.7 as step0 ARG TESTING=false ENV TESTING=$TESTING @@ -10,10 +10,10 @@ 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.3-0.1.2 as final -ENV PHP_MEMCACHED_VERSION=v3.2.0 +FROM appwrite/utopia-base:php-8.3-2.0.0 as final + +ENV PHP_MEMCACHED_VERSION=v3.4.0 LABEL maintainer="team@appwrite.io" @@ -23,10 +23,6 @@ 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 \ # Memcached Extension @@ -41,7 +37,6 @@ RUN echo extension=memcached.so >> /usr/local/etc/php/conf.d/memcached.ini WORKDIR /usr/src/code -# Add Source Code COPY ./ /usr/src/code COPY --from=step0 /usr/local/src/vendor /usr/src/code/vendor diff --git a/Dockerfile.php-8.4 b/Dockerfile.php-8.4 index 3246c041ac..386f1efdac 100644 --- a/Dockerfile.php-8.4 +++ b/Dockerfile.php-8.4 @@ -1,4 +1,4 @@ -FROM composer:2.0 as step0 +FROM composer:2.7 as step0 ARG TESTING=false ENV TESTING=$TESTING @@ -10,10 +10,10 @@ 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.4-1.0.0 as final -ENV PHP_MEMCACHED_VERSION=v3.2.0 +FROM appwrite/utopia-base:php-8.4-2.0.0 as final + +ENV PHP_MEMCACHED_VERSION=v3.4.0 LABEL maintainer="team@appwrite.io" @@ -23,10 +23,6 @@ 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 \ # Memcached Extension @@ -41,7 +37,6 @@ RUN echo extension=memcached.so >> /usr/local/etc/php/conf.d/memcached.ini WORKDIR /usr/src/code -# Add Source Code COPY ./ /usr/src/code COPY --from=step0 /usr/local/src/vendor /usr/src/code/vendor diff --git a/Dockerfile.php-8.2 b/Dockerfile.php-8.5 similarity index 87% rename from Dockerfile.php-8.2 rename to Dockerfile.php-8.5 index ed25111b50..afcf3e6fa9 100644 --- a/Dockerfile.php-8.2 +++ b/Dockerfile.php-8.5 @@ -1,4 +1,4 @@ -FROM composer:2.0 as step0 +FROM composer:2.7 as step0 ARG TESTING=false ENV TESTING=$TESTING @@ -10,10 +10,10 @@ 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.2-0.1.2 as final -ENV PHP_MEMCACHED_VERSION=v3.2.0 +FROM appwrite/utopia-base:php-8.5-2.0.0 as final + +ENV PHP_MEMCACHED_VERSION=v3.4.0 LABEL maintainer="team@appwrite.io" @@ -23,7 +23,6 @@ RUN \ apk update \ && apk add --no-cache make automake autoconf g++ gcc zlib-dev libmemcached-dev docker-cli \ && rm -rf /var/cache/apk/* - RUN \ # Memcached Extension @@ -38,7 +37,6 @@ RUN echo extension=memcached.so >> /usr/local/etc/php/conf.d/memcached.ini WORKDIR /usr/src/code -# Add Source Code COPY ./ /usr/src/code COPY --from=step0 /usr/local/src/vendor /usr/src/code/vendor diff --git a/composer.json b/composer.json index 61905b9301..06b863c009 100644 --- a/composer.json +++ b/composer.json @@ -17,7 +17,7 @@ "psr-4": {"Utopia\\Tests\\": "tests/Cache"} }, "require": { - "php": ">=8.2", + "php": ">=8.3", "ext-json": "*", "ext-memcached": "*", "ext-redis": "*", @@ -29,6 +29,7 @@ "laravel/pint": "1.2.*", "phpstan/phpstan": "^1.12", "phpunit/phpunit": "^9.3", + "swoole/ide-helper": "^6.0", "vimeo/psalm": "4.13.1" }, "config": { diff --git a/composer.lock b/composer.lock index b4e2e4e452..1c319591d9 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": "1d0ace4df177cb2519358831ae65ec36", + "content-hash": "c0bbfaba8e8700ddb517078d445cb0ec", "packages": [ { "name": "brick/math", @@ -4774,6 +4774,38 @@ ], "time": "2020-09-28T06:39:44+00:00" }, + { + "name": "swoole/ide-helper", + "version": "6.0.2", + "source": { + "type": "git", + "url": "https://github.com/swoole/ide-helper.git", + "reference": "6f12243dce071714c5febe059578d909698f9a52" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/swoole/ide-helper/zipball/6f12243dce071714c5febe059578d909698f9a52", + "reference": "6f12243dce071714c5febe059578d909698f9a52", + "shasum": "" + }, + "type": "library", + "notification-url": "https://packagist.org/downloads/", + "license": [ + "Apache-2.0" + ], + "authors": [ + { + "name": "Team Swoole", + "email": "team@swoole.com" + } + ], + "description": "IDE help files for Swoole.", + "support": { + "issues": "https://github.com/swoole/ide-helper/issues", + "source": "https://github.com/swoole/ide-helper/tree/6.0.2" + }, + "time": "2025-03-23T07:31:41+00:00" + }, { "name": "symfony/console", "version": "v6.4.31", @@ -5485,10 +5517,10 @@ "prefer-stable": false, "prefer-lowest": false, "platform": { - "php": ">=8.2", + "php": ">=8.4", "ext-json": "*", - "ext-redis": "*", - "ext-memcached": "*" + "ext-memcached": "*", + "ext-redis": "*" }, "platform-dev": {}, "plugin-api-version": "2.9.0" diff --git a/docker-compose.yml b/docker-compose.yml index 7efba22f54..94524c72a7 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -3,7 +3,7 @@ services: container_name: tests build: context: . - dockerfile: Dockerfile.php-${PHP_VERSION:-8.3} + dockerfile: Dockerfile.php-${PHP_VERSION:-8.4} networks: - database volumes: diff --git a/docs/multiplexing.md b/docs/multiplexing.md new file mode 100644 index 0000000000..aba47b1d9b --- /dev/null +++ b/docs/multiplexing.md @@ -0,0 +1,82 @@ +# Redis Multiplexing Adapter + +A Redis cache adapter for Swoole that serves many concurrent coroutines from a +single Redis TCP connection. + +## When to use it vs. a connection pool + +Most Swoole apps reach for a pool (`Adapter\Pool` wrapping `Adapter\Redis`): +each request checks out one connection, runs its commands, returns it. Pool +size = max concurrent commands. + +`Redis\Multiplexing` is the alternative for *cache* traffic specifically: + +- One TCP socket serving thousands of concurrent commands. +- No pool sizing to tune, no checkout backpressure on bursts. +- Lower memory: ~1 connection per worker, not N. + +You'd still want a pool for transactions, pub/sub, blocking commands, or any +workload where commands are not independent. Many Swoole apps end up using +both — multiplex the cache, pool the rest. + +## Quick start + +```php +use Swoole\Coroutine; +use Utopia\Cache\Cache; +use Utopia\Cache\Adapter\Redis\Multiplexing; + +Coroutine\run(function () { + $adapter = new Multiplexing(host: 'redis'); + $cache = new Cache($adapter); + + $cache->save('user:42', ['name' => 'Ada'], 'profile'); + $cache->load('user:42', ttl: 60, hash: 'profile'); + + $adapter->disconnect(); +}); +``` + +Construct once at worker start, share across requests, `disconnect()` on +`WorkerStop`. The adapter must be constructed inside a Swoole coroutine. + +## Constructor + +```php +new Multiplexing( + host: 'redis', + port: 6379, + timeout: 1.0, // connect timeout (s) + readTimeout: 0.25, // per-command response timeout (s) + auth: null, // string password, [user, password], or null + dbIndex: 0, +); +``` + +`readTimeout` defaults to **250 ms**. A timeout fails the command *and tears +down the connection* — every other in-flight command on it also fails with +`ConnectionException`, and the next command reconnects. This is intentional: +caches should fail fast and let callers fall through to the source of truth. +Per-request resync would add significant complexity for little gain. + +## Errors + +- `\RedisException` — Redis-side error (`WRONGTYPE`, `NOAUTH`, …). Connection + is fine; the command was wrong. Not retried. +- `Utopia\Cache\Adapter\Redis\ConnectionException` — transport failure + (timeout, socket closed, send failed). Connection has been discarded. + Retried if `setMaxRetries(n)` was called. + +## Telemetry + +Implements `Cache\Feature\Telemetry`. Emits a +`cache.redis_multiplexing.pending.depth` gauge after each enqueue — non-zero +steady-state means callers are queueing faster than Redis is replying. Wire +up via `Cache::setTelemetry()`. + +## Limitations + +- Swoole coroutine context required. +- No pub/sub, transactions, blocking commands, or pipelining APIs. +- No Redis Cluster (use `Adapter\RedisCluster`). +- One Redis host per adapter instance; one connection per worker process. diff --git a/phpstan.neon b/phpstan.neon new file mode 100644 index 0000000000..1213936da6 --- /dev/null +++ b/phpstan.neon @@ -0,0 +1,7 @@ +parameters: + level: max + paths: + - src + - tests + scanDirectories: + - vendor/swoole/ide-helper diff --git a/phpunit.xml b/phpunit.xml index 16d75415b7..1003a37b1f 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -9,14 +9,11 @@ stopOnFailure="false" > - - ./tests/Cache/FilesystemTest.php - ./tests/Cache/MemoryTest.php - ./tests/Cache/NoneTest.php - ./tests/Cache/RedisTest.php - ./tests/Cache/ShardingTest.php - ./tests/Cache/HazelcastTest.php - ./tests/Cache/MemcachedTest.php + + ./tests/Cache/Unit + + + ./tests/Cache/E2E - \ No newline at end of file + diff --git a/src/Cache/Adapter/Redis.php b/src/Cache/Adapter/Redis.php index 654da4cffa..e55674db17 100644 --- a/src/Cache/Adapter/Redis.php +++ b/src/Cache/Adapter/Redis.php @@ -6,6 +6,7 @@ use Exception; use Redis as Client; use Throwable; use Utopia\Cache\Adapter; +use Utopia\Cache\Adapter\Redis\Envelope; class Redis implements Adapter { @@ -57,8 +58,9 @@ class Redis implements Adapter $this->persistent = $this->persistentId !== null; $this->dbIndex = $redis->getDbNum(); - if (! empty($redis->getAuth())) { - $this->auth = $redis->getAuth(); + $auth = $redis->getAuth(); + if ($auth !== null && $auth !== false) { + $this->auth = $auth; } $this->redis = $redis; @@ -100,22 +102,11 @@ class Redis implements Adapter $redis_string = $this->execute(fn () => $this->redis->hGet($key, $hash)); - if ($redis_string === false || $redis_string === null) { + if (! is_string($redis_string)) { return false; } - if (gettype($redis_string) !== 'string') { - return false; - } - - /** @var array{time: int, data: string} */ - $cache = json_decode($redis_string, true); - - if ($cache['time'] + $ttl > time()) { // Cache is valid - return $cache['data']; - } - - return false; + return Envelope::decode($redis_string, $ttl, time()); } /** @@ -135,15 +126,7 @@ class Redis implements Adapter } try { - $value = json_encode([ - 'time' => \time(), - 'data' => $data, - ], flags: JSON_THROW_ON_ERROR); - } catch (Throwable $th) { - return false; - } - - try { + $value = Envelope::encode($data, time()); $this->execute(fn () => $this->redis->hSet($key, $hash, $value)); return $data; @@ -165,16 +148,12 @@ class Redis implements Adapter $redis_string = $this->execute(fn () => $this->redis->hGet($key, $hash)); - if ($redis_string === false || $redis_string === null || ! is_string($redis_string)) { + if (! is_string($redis_string)) { return false; } - try { - /** @var array{time: int, data: mixed} $cache */ - $cache = json_decode($redis_string, true, flags: JSON_THROW_ON_ERROR); - $cache['time'] = time(); - $value = json_encode($cache, flags: JSON_THROW_ON_ERROR); - } catch (Throwable $th) { + $value = Envelope::touch($redis_string, time()); + if ($value === false) { return false; } @@ -360,7 +339,7 @@ class Redis implements Adapter ); } - if (! empty($this->auth)) { + if ($this->auth !== null) { $newRedis->auth($this->auth); } diff --git a/src/Cache/Adapter/Redis/Client.php b/src/Cache/Adapter/Redis/Client.php new file mode 100644 index 0000000000..1f718ff3d2 --- /dev/null +++ b/src/Cache/Adapter/Redis/Client.php @@ -0,0 +1,217 @@ +client = new SwooleClient(SWOOLE_SOCK_TCP); + $this->client->set([ + 'open_eof_check' => false, + 'package_max_length' => 64 * 1024 * 1024, + 'open_tcp_nodelay' => true, + ]); + + if (! $this->client->connect($host, $port, $timeout)) { + $errMsg = $this->client->errMsg; + $this->close(); + + throw new ConnectionException('Failed to connect to Redis: '.$errMsg); + } + } + + /** + * Synchronous command: encode, send, block until a frame arrives. Used + * during connection handshake before the reader coroutine takes over. + * Any extra bytes the kernel hands us after the frame stay in the + * internal buffer and can be drained later via takeBuffer(). + * + * @param array $args + */ + public function command(array $args, float $readTimeout): mixed + { + $this->send(self::encode($args)); + + while (true) { + $offset = 0; + $value = self::parse($this->buffer, $offset); + if ($value !== self::INCOMPLETE) { + $this->buffer = substr($this->buffer, $offset); + + if ($value instanceof RedisError) { + throw $value->exception; + } + + return $value; + } + + $chunk = $this->client->recv($readTimeout); + if ($chunk === false || $chunk === '') { + throw new ConnectionException('Timed out waiting for Redis response'); + } + $this->buffer .= $chunk; + } + } + + public function send(string $payload): void + { + $written = $this->client->send($payload); + if ($written === strlen($payload)) { + return; + } + + $message = $written === false + ? ($this->client->errMsg ?: 'send failed') + : 'partial send'; + + throw new ConnectionException('Redis send failed: '.$message); + } + + public function recv(float $timeout): string|false + { + return $this->client->recv($timeout); + } + + /** + * Drain and return any bytes the kernel delivered past the last parsed + * frame. The reader coroutine seeds itself with these so handshake + * leftovers are not lost. + */ + public function takeBuffer(): string + { + $buffer = $this->buffer; + $this->buffer = ''; + + return $buffer; + } + + public function close(): void + { + try { + $this->client->close(); + } catch (Throwable $th) { + // ignore + } + } + + /** + * Recursively rethrow any RedisError / ConnectionError values produced by + * parse() so callers see plain PHP types and exceptions. Arrays are walked + * so that an error nested inside a multi-bulk reply still surfaces. + */ + public static function unwrap(mixed $value): mixed + { + if ($value instanceof RedisError) { + throw $value->exception; + } + + if ($value instanceof ConnectionError) { + throw $value->exception; + } + + if (! is_array($value)) { + return $value; + } + + foreach ($value as $key => $child) { + $value[$key] = self::unwrap($child); + } + + return $value; + } + + /** + * Encode an array of arguments as a RESP array of bulk strings. + * + * @param array $args + */ + public static function encode(array $args): string + { + $out = '*'.count($args)."\r\n"; + foreach ($args as $arg) { + $arg = (string) $arg; + $out .= '$'.strlen($arg)."\r\n".$arg."\r\n"; + } + + return $out; + } + + /** + * Parse a single RESP value from $buffer starting at $offset. Advances + * $offset past the consumed bytes. Returns INCOMPLETE if not enough data + * is present. Redis error frames are returned wrapped in RedisError. + */ + public static function parse(string $buffer, int &$offset): mixed + { + if (! isset($buffer[$offset])) { + return self::INCOMPLETE; + } + + $type = $buffer[$offset]; + $lineEnd = strpos($buffer, "\r\n", $offset + 1); + if ($lineEnd === false) { + return self::INCOMPLETE; + } + + $line = substr($buffer, $offset + 1, $lineEnd - $offset - 1); + $offset = $lineEnd + 2; + + switch ($type) { + case '+': // simple string + return $line; + case '-': // error + return new RedisError(new \RedisException($line)); + case ':': // integer + return (int) $line; + case '$': // bulk string + $len = (int) $line; + if ($len === -1) { + return null; + } + if (strlen($buffer) < $offset + $len + 2) { + return self::INCOMPLETE; + } + $value = substr($buffer, $offset, $len); + $offset += $len + 2; + + return $value; + case '*': // array + $count = (int) $line; + if ($count === -1) { + return null; + } + $items = []; + for ($i = 0; $i < $count; $i++) { + $item = self::parse($buffer, $offset); + if ($item === self::INCOMPLETE) { + return self::INCOMPLETE; + } + $items[] = $item; + } + + return $items; + default: + throw new \RedisException('Unknown RESP type: '.$type); + } + } +} diff --git a/src/Cache/Adapter/Redis/ConnectionContext.php b/src/Cache/Adapter/Redis/ConnectionContext.php new file mode 100644 index 0000000000..8118681eb4 --- /dev/null +++ b/src/Cache/Adapter/Redis/ConnectionContext.php @@ -0,0 +1,17 @@ +> $pending + */ + public function __construct( + public Client $client, + public SplQueue $pending, + ) { + } +} diff --git a/src/Cache/Adapter/Redis/ConnectionError.php b/src/Cache/Adapter/Redis/ConnectionError.php new file mode 100644 index 0000000000..4ae7fd806e --- /dev/null +++ b/src/Cache/Adapter/Redis/ConnectionError.php @@ -0,0 +1,11 @@ +, "data": }`. Encoding adds the + * timestamp; decoding enforces TTL relative to a caller-supplied `now`. + */ +final class Envelope +{ + /** + * @param array|string $data + * + * @throws JsonException + */ + public static function encode(array|string $data, int $time): string + { + return json_encode([ + 'time' => $time, + 'data' => $data, + ], flags: JSON_THROW_ON_ERROR); + } + + /** + * Decode a stored envelope. Returns the wrapped data if the envelope is + * well-formed and not yet expired (`time + ttl > now`); returns false + * otherwise. Never throws — malformed JSON / shape is treated as a miss. + */ + public static function decode(string $value, int $ttl, int $now): mixed + { + $cache = json_decode($value, true); + if (! is_array($cache) || ! isset($cache['time'], $cache['data']) || ! is_int($cache['time'])) { + return false; + } + + if ($cache['time'] + $ttl > $now) { + return $cache['data']; + } + + return false; + } + + /** + * Re-stamp an existing envelope with a new timestamp, preserving its data. + * Returns the rewritten JSON, or false if the input is not a valid envelope. + */ + public static function touch(string $value, int $newTime): string|false + { + try { + $cache = json_decode($value, true, flags: JSON_THROW_ON_ERROR); + } catch (JsonException) { + return false; + } + + if (! is_array($cache) || ! array_key_exists('data', $cache)) { + return false; + } + + $cache['time'] = $newTime; + + try { + return json_encode($cache, flags: JSON_THROW_ON_ERROR); + } catch (JsonException) { + return false; + } + } +} diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php new file mode 100644 index 0000000000..fcb9d9956c --- /dev/null +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -0,0 +1,493 @@ +|null $auth password or [username, password] + * @param int $dbIndex + */ + public function __construct( + private string $host, + private int $port = 6379, + private float $timeout = 1.0, + private float $readTimeout = 0.25, + private string|array|null $auth = null, + private int $dbIndex = 0, + ) { + if ($this->timeout <= 0) { + throw new \InvalidArgumentException('timeout must be greater than 0'); + } + if ($this->readTimeout <= 0) { + throw new \InvalidArgumentException('readTimeout must be greater than 0'); + } + $this->sendLock = new Lock(); + $this->setTelemetry(new NoTelemetry()); + + $locked = $this->lockSend(); + try { + $this->connect(); + } finally { + $this->unlockSend($locked); + } + } + + /** + * Wire a telemetry adapter for connection-level metrics. The current + * pending-queue depth is recorded after each enqueue — a steady-state + * non-zero value means callers are queueing faster than Redis is + * replying. + */ + public function setTelemetry(Telemetry $telemetry): void + { + $this->pendingDepth = $telemetry->createGauge( + 'cache.redis_multiplexing.pending.depth', + description: 'Pending response channels awaiting RESP frames on the multiplexed connection.', + ); + } + + /** + * Explicitly close the multiplexed connection. Required for clean shutdown + * because the reader coroutine holds a reference to this adapter. + */ + public function disconnect(): void + { + $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)) { + $hash = $key; + } + + $value = $this->command(['HGET', $key, $hash]); + + if (! is_string($value)) { + return false; + } + + return Envelope::decode($value, $ttl, time()); + } + + public function save(string $key, array|string $data, string $hash = ''): bool|string|array + { + if (empty($key) || empty($data)) { + return false; + } + + if (empty($hash)) { + $hash = $key; + } + + try { + $value = Envelope::encode($data, time()); + $this->command(['HSET', $key, $hash, $value]); + + return $data; + } catch (Throwable $th) { + return false; + } + } + + public function touch(string $key, string $hash = ''): bool + { + if (empty($hash)) { + $hash = $key; + } + + $value = $this->command(['HGET', $key, $hash]); + if (! is_string($value)) { + return false; + } + + $payload = Envelope::touch($value, time()); + if ($payload === false) { + return false; + } + + return $this->command(['HSET', $key, $hash, $payload]) !== false; + } + + /** + * @return string[] + */ + public function list(string $key): array + { + $keys = $this->command(['HKEYS', $key]); + if (! is_array($keys)) { + return []; + } + + /** @var string[] $keys */ + return $keys; + } + + public function purge(string $key, string $hash = ''): bool + { + if (! empty($hash)) { + return (bool) $this->command(['HDEL', $key, $hash]); + } + + return (bool) $this->command(['DEL', $key]); + } + + public function flush(): bool + { + return $this->command(['FLUSHDB']) === 'OK'; + } + + public function ping(): bool + { + try { + return $this->command(['PING']) === 'PONG'; + } catch (Throwable $th) { + return false; + } + } + + public function getSize(): int + { + $size = $this->command(['DBSIZE']); + + return is_int($size) ? $size : 0; + } + + public function getName(?string $key = null): string + { + return 'redis-multiplexing'; + } + + /** + * Send a Redis command and block the calling coroutine until the response arrives. + * + * @param array $args + */ + private function command(array $args): mixed + { + $attempts = 0; + $maxAttempts = 1 + $this->maxRetries; + + while (true) { + try { + return $this->dispatch($args); + } catch (ConnectionException $th) { + if (++$attempts >= $maxAttempts) { + throw $th; + } + + Coroutine::sleep($this->retryDelaySeconds()); + $this->ensureConnected(); + } + } + } + + 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. + * + * @param array $args + */ + private function dispatch(array $args): mixed + { + $locked = $this->lockSend(); + try { + $context = $this->connection; + if ($context === null) { + throw new ConnectionException('Redis connection is not open'); + } + $response = new Channel(1); + $error = null; + + $context->pending->enqueue($response); + $this->pendingDepth?->record($context->pending->count()); + try { + $context->client->send(Client::encode($args)); + } catch (ConnectionException $sendError) { + $error = $sendError; + } + } finally { + $this->unlockSend($locked); + } + + if ($error !== null) { + $this->teardownIfCurrent($context, $error); + + throw $error; + } + + return $this->awaitResponse($context, $response); + } + + /** + * @param Channel $response + */ + private function awaitResponse(ConnectionContext $context, Channel $response): mixed + { + $result = $response->pop($this->readTimeout); + if ($result === false && $response->errCode !== 0) { + $error = new ConnectionException('Timed out waiting for Redis response'); + $this->teardownIfCurrent($context, $error); + + throw $error; + } + + 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. + */ + private function connect(): void + { + $client = new Client($this->host, $this->port, $this->timeout); + + try { + if ($this->auth !== null) { + $authArgs = is_array($this->auth) + ? array_merge(['AUTH'], array_values($this->auth)) + : ['AUTH', $this->auth]; + + if ($client->command($authArgs, $this->readTimeout) !== 'OK') { + throw new \RedisException('Redis AUTH failed'); + } + } + + if ($this->dbIndex !== 0) { + if ($client->command(['SELECT', (string) $this->dbIndex], $this->readTimeout) !== 'OK') { + throw new \RedisException('Redis SELECT failed'); + } + } + } catch (Throwable $th) { + $client->close(); + + throw $th; + } + + /** @var SplQueue> $pending */ + $pending = new SplQueue(); + $context = new ConnectionContext($client, $pending); + $this->connection = $context; + + Coroutine::create(function () use ($context) { + $this->readerLoop($context); + }); + } + + private function shutdown(): void + { + $context = null; + $locked = $this->lockSend(); + try { + if ($this->connection !== null) { + $context = $this->connection; + $this->connection = null; + } + } finally { + $this->unlockSend($locked); + } + + if ($context !== null) { + $this->finishTeardown($context, new ConnectionException('Connection closed')); + } + } + + /** + * Stop the connection and fail every coroutine still waiting on a response. + */ + private function finishTeardown(ConnectionContext $context, ConnectionException $error): void + { + while (! $context->pending->isEmpty()) { + $ch = $context->pending->dequeue(); + if ($ch instanceof Channel) { + $ch->push(new ConnectionError($error)); + } + } + + $context->client->close(); + } + + private function teardownIfCurrent(ConnectionContext $context, ConnectionException $error): void + { + $shouldTeardown = false; + $locked = $this->lockSend(); + try { + if ($this->connection === $context) { + $this->connection = null; + $shouldTeardown = true; + } + } finally { + $this->unlockSend($locked); + } + + if ($shouldTeardown) { + $this->finishTeardown($context, $error); + } + } + + private function lockSend(): bool + { + if (Coroutine::getCid() < 0) { + return false; + } + + $this->sendLock->lock(); + + return true; + } + + private function unlockSend(bool $locked): void + { + if ($locked) { + $this->sendLock->unlock(); + } + } + + private function readerLoop(ConnectionContext $context): void + { + $readBuffer = $context->client->takeBuffer(); + + while (true) { + while ($readBuffer !== '') { + $offset = 0; + try { + $value = Client::parse($readBuffer, $offset); + } catch (Throwable $th) { + $this->teardownIfCurrent($context, new ConnectionException('Redis protocol parse failed: '.$th->getMessage())); + + return; + } + + if ($value === Client::INCOMPLETE) { + break; + } + + $readBuffer = substr($readBuffer, $offset); + + if (! $this->isCurrentContext($context)) { + return; + } + + // A complete frame implies a prior pending enqueue. + $waiting = $context->pending->isEmpty() ? null : $context->pending->dequeue(); + if ($waiting instanceof Channel) { + $waiting->push($value); + } else { + // Should never happen given the send-lock invariant. Log + // and tear down so the next caller reconnects on a clean + // socket rather than continuing to misroute frames. + error_log('Redis\\Multiplexing: unexpected RESP frame with no pending request; tearing down connection'); + $this->teardownIfCurrent($context, new ConnectionException('Unexpected RESP frame with no pending request')); + + return; + } + } + + $chunk = $context->client->recv(-1); + if ($chunk === false || $chunk === '') { + $this->teardownIfCurrent($context, new ConnectionException('Redis connection closed')); + + return; + } + + $readBuffer .= $chunk; + } + } + + private function isCurrentContext(ConnectionContext $context): bool + { + $locked = $this->lockSend(); + try { + return $this->connection === $context; + } finally { + $this->unlockSend($locked); + } + } +} diff --git a/src/Cache/Adapter/Redis/RedisError.php b/src/Cache/Adapter/Redis/RedisError.php new file mode 100644 index 0000000000..93680dbeb3 --- /dev/null +++ b/src/Cache/Adapter/Redis/RedisError.php @@ -0,0 +1,11 @@ + */ + protected array $dataArray = ['test', 'data', 'string']; + + /** + * Run the entire test body inside a Swoole coroutine context. + */ + private function runCo(callable $fn): void + { + $error = null; + run(function () use ($fn, &$error) { + try { + $fn(); + } catch (\Throwable $th) { + $error = $th; + } finally { + $this->close(); + } + }); + if ($error !== null) { + throw $error; + } + } + + private RedisMultiplexing $adapter; + + private function makeCache(): Cache + { + $this->adapter = new RedisMultiplexing('redis', 6379); + + return new Cache($this->adapter); + } + + private function close(): void + { + if (isset($this->adapter)) { + $this->adapter->disconnect(); + } + } + + public function testCacheSave(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->flush(); + + $result = $cache->save($this->key, $this->dataArray, $this->key); + $this->assertEquals($this->dataArray, $result); + + $result = $cache->save($this->key, $this->data, $this->key); + $this->assertEquals($this->data, $result); + + $loaded = $cache->load($this->key, 60, $this->key); + $this->assertEquals($this->data, $loaded); + }); + } + + public function testCachePurge(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->save($this->key, $this->data, $this->key); + + $loaded = $cache->load($this->key, 60, $this->key); + $this->assertEquals($this->data, $loaded); + + $this->assertTrue($cache->purge($this->key)); + $this->assertFalse($cache->load($this->key, 60, $this->key)); + }); + } + + public function testCacheTouch(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->save('touch-key', 'touch data', 'touch-key'); + + sleep(3); + + $this->assertFalse($cache->load('touch-key', 2, 'touch-key')); + $this->assertTrue($cache->touch('touch-key', 'touch-key')); + $this->assertEquals('touch data', $cache->load('touch-key', 2, 'touch-key')); + $this->assertFalse($cache->touch('missing-touch-key', 'missing-touch-key')); + + $cache->purge('touch-key'); + }); + } + + public function testPing(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $this->assertTrue($cache->ping()); + }); + } + + public function testFlush(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->save('x', 'x', 'x'); + $cache->save('y', 'y', 'y'); + + $this->assertEquals('x', $cache->load('x', 100, 'x')); + $this->assertEquals('y', $cache->load('y', 100, 'y')); + + $this->assertTrue($cache->flush()); + $this->assertFalse($cache->load('x', 100, 'x')); + $this->assertFalse($cache->load('y', 100, 'y')); + }); + } + + public function testGetSize(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->flush(); + + $cache->save('test:file33', 'file33', 'test:file33'); + $cache->save('test:file34', 'file34', 'test:file34'); + $cache->save('test:file35', 'file35', 'test:file35'); + + $this->assertEquals(3, $cache->getSize()); + }); + } + + public function testJsonData(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->flush(); + + $payload = [ + 'id' => 'doc-42', + 'title' => 'Hello, "world"', + 'tags' => ['php', 'redis', 'swoole'], + 'meta' => [ + 'count' => 7, + 'ratio' => 0.125, + 'flag' => true, + 'missing' => null, + ], + 'unicode' => 'café — 日本語 — 🚀', + 'nested' => [ + 'a' => ['b' => ['c' => ['d' => 'deep']]], + ], + 'binary-ish' => "line1\nline2\twith\ttabs\r\nand crlf", + ]; + + $saved = $cache->save('json:doc', $payload, 'json:doc'); + $this->assertEquals($payload, $saved); + + $loaded = $cache->load('json:doc', 60, 'json:doc'); + $this->assertEquals($payload, $loaded); + + $jsonString = json_encode($payload, JSON_THROW_ON_ERROR); + $this->assertNotFalse($jsonString); + $this->assertEquals($jsonString, $cache->save('json:string', $jsonString, 'json:string')); + $this->assertEquals($jsonString, $cache->load('json:string', 60, 'json:string')); + }); + } + + public function testLargeJsonPayload(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->flush(); + + $rows = []; + for ($i = 0; $i < 1000; $i++) { + $rows[] = [ + 'i' => $i, + 'name' => 'row-'.$i, + 'value' => str_repeat('x', 64), + ]; + } + $payload = ['rows' => $rows]; + + $saved = $cache->save('json:large', $payload, 'json:large'); + $this->assertEquals($payload, $saved); + + $loaded = $cache->load('json:large', 60, 'json:large'); + $this->assertEquals($payload, $loaded); + }); + } + + public function testConcurrentJsonMultiplexing(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->flush(); + + $count = 50; + $wg = new WaitGroup(); + $errors = []; + + for ($i = 0; $i < $count; $i++) { + $wg->add(); + Coroutine::create(function () use ($cache, $i, $wg, &$errors) { + try { + $key = 'json-mux:'.$i; + $value = [ + 'i' => $i, + 'tags' => ['a', 'b', 'c-'.$i], + 'meta' => ['nested' => ['count' => $i * 2]], + 'text' => 'café 🚀 row '.$i, + ]; + $saved = $cache->save($key, $value, $key); + if ($saved !== $value) { + $errors[] = "save mismatch for $i"; + } + $loaded = $cache->load($key, 60, $key); + if ($loaded != $value) { + $errors[] = "load mismatch for $i: ".var_export($loaded, true); + } + } catch (\Throwable $th) { + $errors[] = $th->getMessage(); + } finally { + $wg->done(); + } + }); + } + + $wg->wait(); + + $this->assertEmpty($errors, 'Concurrent errors: '.implode('; ', $errors)); + $this->assertEquals($count, $cache->getSize()); + }); + } + + /** + * Concurrent multiplexing: many coroutines hitting the same connection. + */ + public function testConcurrentMultiplexing(): void + { + $this->runCo(function () { + $cache = $this->makeCache(); + $cache->flush(); + + $count = 50; + $wg = new WaitGroup(); + $errors = []; + + for ($i = 0; $i < $count; $i++) { + $wg->add(); + Coroutine::create(function () use ($cache, $i, $wg, &$errors) { + try { + $key = 'mux:'.$i; + $value = 'value-'.$i; + $saved = $cache->save($key, $value, $key); + if ($saved !== $value) { + $errors[] = "save mismatch for $i: ".var_export($saved, true); + } + $loaded = $cache->load($key, 60, $key); + if ($loaded !== $value) { + $errors[] = "load mismatch for $i: ".var_export($loaded, true); + } + } catch (\Throwable $th) { + $errors[] = $th->getMessage(); + } finally { + $wg->done(); + } + }); + } + + $wg->wait(); + + $this->assertEmpty($errors, 'Concurrent errors: '.implode('; ', $errors)); + $this->assertEquals($count, $cache->getSize()); + }); + } +} diff --git a/tests/Cache/RedisClusterTest.php b/tests/Cache/E2E/Redis/RedisClusterTest.php similarity index 97% rename from tests/Cache/RedisClusterTest.php rename to tests/Cache/E2E/Redis/RedisClusterTest.php index 933742141b..fc0f5dd565 100644 --- a/tests/Cache/RedisClusterTest.php +++ b/tests/Cache/E2E/Redis/RedisClusterTest.php @@ -1,10 +1,11 @@ flush(); self::$cache->save('test:file33', 'file33', 'test:file33'); self::$cache->save('test:file34', 'file34', 'test:file34'); self::$cache->save('test:file35', 'file35', 'test:file35'); diff --git a/tests/Cache/ShardingTest.php b/tests/Cache/E2E/ShardingTest.php similarity index 97% rename from tests/Cache/ShardingTest.php rename to tests/Cache/E2E/ShardingTest.php index 950eb9f657..766d18dc11 100644 --- a/tests/Cache/ShardingTest.php +++ b/tests/Cache/E2E/ShardingTest.php @@ -1,6 +1,6 @@ assertSame( + "*1\r\n\$4\r\nPING\r\n", + Client::encode(['PING']) + ); + + $this->assertSame( + "*3\r\n\$3\r\nSET\r\n\$3\r\nfoo\r\n\$3\r\nbar\r\n", + Client::encode(['SET', 'foo', 'bar']) + ); + } + + public function testEncodeCoercesIntegersToStrings(): void + { + $this->assertSame( + "*2\r\n\$6\r\nSELECT\r\n\$1\r\n3\r\n", + Client::encode(['SELECT', 3]) + ); + } + + public function testEncodePreservesBinaryPayloadByByteLength(): void + { + $payload = "café\n\0bytes"; + $encoded = Client::encode(['SET', 'k', $payload]); + + $this->assertSame( + "*3\r\n\$3\r\nSET\r\n\$1\r\nk\r\n\$".strlen($payload)."\r\n".$payload."\r\n", + $encoded + ); + } + + public function testParseSimpleString(): void + { + $offset = 0; + $this->assertSame('OK', Client::parse("+OK\r\n", $offset)); + $this->assertSame(5, $offset); + } + + public function testParseInteger(): void + { + $offset = 0; + $this->assertSame(42, Client::parse(":42\r\n", $offset)); + $this->assertSame(5, $offset); + } + + public function testParseNegativeInteger(): void + { + $offset = 0; + $this->assertSame(-7, Client::parse(":-7\r\n", $offset)); + } + + public function testParseBulkString(): void + { + $offset = 0; + $this->assertSame('hello', Client::parse("\$5\r\nhello\r\n", $offset)); + $this->assertSame(11, $offset); + } + + public function testParseBulkStringWithEmbeddedCrlf(): void + { + $offset = 0; + $payload = "line1\r\nline2"; + $this->assertSame( + $payload, + Client::parse('$'.strlen($payload)."\r\n".$payload."\r\n", $offset) + ); + } + + public function testParseEmptyBulkString(): void + { + $offset = 0; + $this->assertSame('', Client::parse("\$0\r\n\r\n", $offset)); + $this->assertSame(6, $offset); + } + + public function testParseNullBulkString(): void + { + $offset = 0; + $this->assertNull(Client::parse("\$-1\r\n", $offset)); + $this->assertSame(5, $offset); + } + + public function testParseArrayOfMixedTypes(): void + { + $offset = 0; + $buffer = "*3\r\n\$3\r\nfoo\r\n:42\r\n+OK\r\n"; + $this->assertSame(['foo', 42, 'OK'], Client::parse($buffer, $offset)); + $this->assertSame(strlen($buffer), $offset); + } + + public function testParseEmptyArray(): void + { + $offset = 0; + $this->assertSame([], Client::parse("*0\r\n", $offset)); + } + + public function testParseNullArray(): void + { + $offset = 0; + $this->assertNull(Client::parse("*-1\r\n", $offset)); + } + + public function testParseNestedArrays(): void + { + $offset = 0; + $buffer = "*2\r\n*2\r\n:1\r\n:2\r\n*1\r\n\$1\r\nx\r\n"; + $this->assertSame([[1, 2], ['x']], Client::parse($buffer, $offset)); + $this->assertSame(strlen($buffer), $offset); + } + + public function testParseRedisErrorIsWrappedNotThrown(): void + { + $offset = 0; + $value = Client::parse("-WRONGTYPE wrong kind\r\n", $offset); + + $this->assertInstanceOf(RedisError::class, $value); + $this->assertSame('WRONGTYPE wrong kind', $value->exception->getMessage()); + } + + public function testParseReturnsIncompleteWhenBufferEmpty(): void + { + $offset = 0; + $this->assertSame(Client::INCOMPLETE, Client::parse('', $offset)); + } + + public function testParseReturnsIncompleteWhenLineUnterminated(): void + { + $offset = 0; + $this->assertSame(Client::INCOMPLETE, Client::parse('+OK', $offset)); + } + + public function testParseReturnsIncompleteForTruncatedBulkString(): void + { + $offset = 0; + // header says 5 bytes, payload is short + $this->assertSame(Client::INCOMPLETE, Client::parse("\$5\r\nhel", $offset)); + } + + public function testParseReturnsIncompleteForBulkStringMissingTrailingCrlf(): void + { + $offset = 0; + $this->assertSame(Client::INCOMPLETE, Client::parse("\$5\r\nhello", $offset)); + } + + public function testParseReturnsIncompleteForPartiallyDeliveredArrayElement(): void + { + $offset = 0; + $this->assertSame(Client::INCOMPLETE, Client::parse("*2\r\n:1\r\n:", $offset)); + } + + public function testParseAdvancesOffsetExactlyOneFrame(): void + { + $offset = 0; + $buffer = "+OK\r\n+SECOND\r\n"; + $this->assertSame('OK', Client::parse($buffer, $offset)); + $this->assertSame(5, $offset); + $this->assertSame('SECOND', Client::parse($buffer, $offset)); + $this->assertSame(strlen($buffer), $offset); + } + + public function testParseUnknownTypeThrows(): void + { + $this->expectException(\RedisException::class); + $offset = 0; + Client::parse("?nope\r\n", $offset); + } + + public function testEncodeAndParseRoundTripFlattenedToServerEcho(): void + { + // The server's HSET reply for a new field is :1 — confirm we can + // round-trip from encode -> ... -> parse for what we'd read back. + $offset = 0; + $this->assertSame(1, Client::parse(":1\r\n", $offset)); + + // And that encode produces what a real Redis would expect. + $this->assertSame( + "*4\r\n\$4\r\nHSET\r\n\$1\r\nk\r\n\$1\r\nf\r\n\$1\r\nv\r\n", + Client::encode(['HSET', 'k', 'f', 'v']) + ); + } + + public function testUnwrapPassesThroughScalars(): void + { + $this->assertSame('OK', Client::unwrap('OK')); + $this->assertSame(42, Client::unwrap(42)); + $this->assertNull(Client::unwrap(null)); + $this->assertSame('', Client::unwrap('')); + } + + public function testUnwrapPassesThroughArraysOfScalars(): void + { + $this->assertSame(['a', 1, null], Client::unwrap(['a', 1, null])); + } + + public function testUnwrapThrowsRedisErrorAtTopLevel(): void + { + $this->expectException(\RedisException::class); + $this->expectExceptionMessage('WRONGTYPE'); + Client::unwrap(new RedisError(new \RedisException('WRONGTYPE'))); + } + + public function testUnwrapThrowsConnectionErrorAtTopLevel(): void + { + $this->expectException(ConnectionException::class); + $this->expectExceptionMessage('connection lost'); + Client::unwrap(new ConnectionError(new ConnectionException('connection lost'))); + } + + public function testUnwrapThrowsRedisErrorNestedInArray(): void + { + $this->expectException(\RedisException::class); + $this->expectExceptionMessage('NOAUTH'); + // Element 1 is an error frame; the unwrap must walk into it. + Client::unwrap(['ok', new RedisError(new \RedisException('NOAUTH'))]); + } + + public function testUnwrapThrowsErrorNestedInsideNestedArray(): void + { + $this->expectException(\RedisException::class); + $this->expectExceptionMessage('deep'); + Client::unwrap([ + ['nested', ['deeper', new RedisError(new \RedisException('deep'))]], + ]); + } + + public function testUnwrapReturnsArrayUnchangedWhenNoErrors(): void + { + $input = [['a', 1], ['b', null], 'c']; + $this->assertSame($input, Client::unwrap($input)); + } + + public function testUnwrapHandlesEmptyArray(): void + { + $this->assertSame([], Client::unwrap([])); + } +} diff --git a/tests/Cache/Unit/Redis/EnvelopeTest.php b/tests/Cache/Unit/Redis/EnvelopeTest.php new file mode 100644 index 0000000000..9a6c3ffb1b --- /dev/null +++ b/tests/Cache/Unit/Redis/EnvelopeTest.php @@ -0,0 +1,116 @@ +assertSame('{"time":1700000000,"data":"hello"}', $encoded); + } + + public function testEncodeArrayPayload(): void + { + $encoded = Envelope::encode(['a' => 1], 42); + $this->assertSame('{"time":42,"data":{"a":1}}', $encoded); + } + + public function testDecodeReturnsDataWhenFresh(): void + { + $encoded = Envelope::encode(['x' => 1], 100); + $this->assertSame(['x' => 1], Envelope::decode($encoded, ttl: 60, now: 130)); + } + + public function testDecodeReturnsFalseWhenStale(): void + { + $encoded = Envelope::encode('value', 100); + // 100 + 60 = 160; now = 161 → stale + $this->assertFalse(Envelope::decode($encoded, ttl: 60, now: 161)); + } + + public function testDecodeBoundaryIsExclusive(): void + { + $encoded = Envelope::encode('value', 100); + // time + ttl > now means strictly greater; equal counts as stale + $this->assertFalse(Envelope::decode($encoded, ttl: 60, now: 160)); + $this->assertSame('value', Envelope::decode($encoded, ttl: 60, now: 159)); + } + + public function testDecodeTreatsMalformedJsonAsMiss(): void + { + $this->assertFalse(Envelope::decode('not json', 60, 0)); + $this->assertFalse(Envelope::decode('', 60, 0)); + $this->assertFalse(Envelope::decode('null', 60, 0)); + } + + public function testDecodeRejectsMissingFields(): void + { + $this->assertFalse(Envelope::decode('{"time":100}', 60, 0)); + $this->assertFalse(Envelope::decode('{"data":"x"}', 60, 0)); + $this->assertFalse(Envelope::decode('{}', 60, 0)); + } + + public function testDecodeRejectsNonIntegerTime(): void + { + $this->assertFalse(Envelope::decode('{"time":"100","data":"x"}', 60, 0)); + $this->assertFalse(Envelope::decode('{"time":1.5,"data":"x"}', 60, 0)); + } + + public function testDecodePreservesNullData(): void + { + // isset() rejects null, so null-data envelopes are treated as a miss. + // This matches existing adapter behavior; documenting via test. + $this->assertFalse(Envelope::decode('{"time":100,"data":null}', 60, 130)); + } + + public function testDecodePreservesNestedArrayData(): void + { + $data = ['a' => ['b' => ['c' => 'deep']], 'list' => [1, 2, 3]]; + $encoded = Envelope::encode($data, 100); + $this->assertSame($data, Envelope::decode($encoded, 60, 130)); + } + + public function testTouchRewritesTime(): void + { + $encoded = Envelope::encode('value', 100); + $touched = Envelope::touch($encoded, 200); + + $this->assertIsString($touched); + $this->assertSame('value', Envelope::decode($touched, 60, 250)); + // Original timestamp would have made this stale + $this->assertFalse(Envelope::decode($encoded, 60, 250)); + } + + public function testTouchPreservesArrayData(): void + { + $data = ['x' => 1, 'y' => [2, 3]]; + $encoded = Envelope::encode($data, 100); + $touched = Envelope::touch($encoded, 200); + + $this->assertIsString($touched); + $this->assertSame($data, Envelope::decode($touched, 60, 230)); + } + + public function testTouchReturnsFalseOnMalformedJson(): void + { + $this->assertFalse(Envelope::touch('not json', 200)); + } + + public function testTouchReturnsFalseWhenDataKeyMissing(): void + { + $this->assertFalse(Envelope::touch('{"time":100}', 200)); + $this->assertFalse(Envelope::touch('{}', 200)); + } + + public function testTouchAcceptsEnvelopeWithoutPriorTimeField(): void + { + // touch() only requires a 'data' key — re-stamping is the whole point. + $touched = Envelope::touch('{"data":"x"}', 200); + $this->assertIsString($touched); + $this->assertSame('x', Envelope::decode($touched, 60, 230)); + } +}