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));
+ }
+}