From 95f04dd65d3c272241d09b39d1d6b9b3a607964e Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 12 May 2026 13:13:19 +0100 Subject: [PATCH 1/9] refactor(tests): split into Unit and E2E suites; group Redis tests - Move every test under tests/Cache/E2E so e2e and unit suites can be selected independently. - Group RedisTest, RedisClusterTest under tests/Cache/E2E/Redis/. - Update phpunit.xml to expose 'unit' and 'e2e' testsuites; the default test command no longer needs to enumerate files. Co-Authored-By: Claude Opus 4.7 --- phpunit.xml | 15 ++++++--------- tests/Cache/{ => E2E}/Base.php | 2 +- tests/Cache/{ => E2E}/CircuitBreakerTest.php | 2 +- tests/Cache/{ => E2E}/FilesystemTest.php | 2 +- tests/Cache/{ => E2E}/HazelcastTest.php | 2 +- tests/Cache/{ => E2E}/MemcachedTest.php | 2 +- tests/Cache/{ => E2E}/MemoryTest.php | 2 +- tests/Cache/{ => E2E}/NoneTest.php | 2 +- tests/Cache/{ => E2E}/PoolTest.php | 2 +- tests/Cache/{ => E2E/Redis}/RedisClusterTest.php | 3 ++- tests/Cache/{ => E2E/Redis}/RedisTest.php | 3 ++- tests/Cache/{ => E2E}/ShardingTest.php | 2 +- tests/Cache/{ => E2E}/TelemetryTest.php | 2 +- 13 files changed, 20 insertions(+), 21 deletions(-) rename tests/Cache/{ => E2E}/Base.php (99%) rename tests/Cache/{ => E2E}/CircuitBreakerTest.php (99%) rename tests/Cache/{ => E2E}/FilesystemTest.php (98%) rename tests/Cache/{ => E2E}/HazelcastTest.php (98%) rename tests/Cache/{ => E2E}/MemcachedTest.php (98%) rename tests/Cache/{ => E2E}/MemoryTest.php (95%) rename tests/Cache/{ => E2E}/NoneTest.php (98%) rename tests/Cache/{ => E2E}/PoolTest.php (96%) rename tests/Cache/{ => E2E/Redis}/RedisClusterTest.php (97%) rename tests/Cache/{ => E2E/Redis}/RedisTest.php (98%) rename tests/Cache/{ => E2E}/ShardingTest.php (97%) rename tests/Cache/{ => E2E}/TelemetryTest.php (96%) 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/tests/Cache/Base.php b/tests/Cache/E2E/Base.php similarity index 99% rename from tests/Cache/Base.php rename to tests/Cache/E2E/Base.php index 4fd13cb62e..fe12478b5e 100644 --- a/tests/Cache/Base.php +++ b/tests/Cache/E2E/Base.php @@ -1,6 +1,6 @@ Date: Tue, 12 May 2026 13:13:51 +0100 Subject: [PATCH 2/9] feat: add Redis\Multiplexing adapter over Swoole TCP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A coroutine-aware Redis cache adapter that multiplexes many concurrent Swoole coroutines over a single Redis TCP connection. The architecture is documented in docs/multiplexing.md. Key components under src/Cache/Adapter/Redis/: - Client — Swoole TCP socket wrapper plus the RESP2 codec. Owns the socket and any unread byte buffer. - Multiplexing — the cache adapter. Holds at most one ConnectionContext at a time; a single send lock serialises pending->push + send so the FIFO invariant matches inbound RESP frames to outbound commands. - ConnectionContext — value object pairing a Client with its pending queue. Per-context state means a context can be torn down on timeout without poisoning a replacement context. - Envelope — shared {time, data} cache JSON envelope (encode/decode/ touch with TTL semantics). - ConnectionException, ConnectionError, RedisError — typed signals so the retry loop can distinguish reconnectable errors from server-side Redis errors. Implements Cache\Feature\Telemetry; emits a redis_multiplexing.pending.depth gauge after each enqueue, the single most useful health signal for this adapter. Tests: 23 RESP codec + unwrap unit tests, 14 envelope unit tests, and 10 e2e tests covering basic ops, large/nested JSON payloads, and 50-way concurrent multiplexing. Co-Authored-By: Claude Opus 4.7 --- src/Cache/Adapter/Redis/Client.php | 217 ++++++++ src/Cache/Adapter/Redis/ConnectionContext.php | 17 + src/Cache/Adapter/Redis/ConnectionError.php | 11 + .../Adapter/Redis/ConnectionException.php | 12 + src/Cache/Adapter/Redis/Envelope.php | 71 +++ src/Cache/Adapter/Redis/Multiplexing.php | 490 ++++++++++++++++++ src/Cache/Adapter/Redis/RedisError.php | 11 + tests/Cache/E2E/Redis/MultiplexingTest.php | 288 ++++++++++ tests/Cache/Unit/Redis/ClientTest.php | 249 +++++++++ tests/Cache/Unit/Redis/EnvelopeTest.php | 116 +++++ 10 files changed, 1482 insertions(+) create mode 100644 src/Cache/Adapter/Redis/Client.php create mode 100644 src/Cache/Adapter/Redis/ConnectionContext.php create mode 100644 src/Cache/Adapter/Redis/ConnectionError.php create mode 100644 src/Cache/Adapter/Redis/ConnectionException.php create mode 100644 src/Cache/Adapter/Redis/Envelope.php create mode 100644 src/Cache/Adapter/Redis/Multiplexing.php create mode 100644 src/Cache/Adapter/Redis/RedisError.php create mode 100644 tests/Cache/E2E/Redis/MultiplexingTest.php create mode 100644 tests/Cache/Unit/Redis/ClientTest.php create mode 100644 tests/Cache/Unit/Redis/EnvelopeTest.php diff --git a/src/Cache/Adapter/Redis/Client.php b/src/Cache/Adapter/Redis/Client.php new file mode 100644 index 0000000000..4663a66c79 --- /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 > 0 ? $timeout : 1.0)) { + $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..0af1e835d0 --- /dev/null +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -0,0 +1,490 @@ +|null $auth password or [username, password] + * @param int $dbIndex + */ + public function __construct( + private string $host, + private int $port = 6379, + private float $timeout = 0.0, + private float $readTimeout = 0.25, + private string|array|null $auth = null, + private int $dbIndex = 0, + ) { + if ($this->readTimeout <= 0) { + $this->readTimeout = 0.25; + } + $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( + '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/Unit/Redis/ClientTest.php b/tests/Cache/Unit/Redis/ClientTest.php new file mode 100644 index 0000000000..0f94562038 --- /dev/null +++ b/tests/Cache/Unit/Redis/ClientTest.php @@ -0,0 +1,249 @@ +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)); + } +} From ce01efb83ac741423fc9c05014ff3280bec92745 Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 12 May 2026 13:14:27 +0100 Subject: [PATCH 3/9] chore: target PHP 8.4 / Swoole 6.1 and document Redis\Multiplexing - Replace per-version Dockerfiles with a single Dockerfile.php-8.4 built on appwrite/utopia-base:php-8.4-1.0.0 (Swoole 6.1 ships Coroutine\Lock, which Multiplexing needs). - Collapse the CI matrix to 8.4 and bump composer.json to >=8.4. - Add swoole/ide-helper for phpstan stub coverage. - Add phpstan.neon scanning the swoole stubs. - Add docs/multiplexing.md, a consumer-oriented guide. Co-Authored-By: Claude Opus 4.7 --- .github/workflows/test.yml | 4 +- Dockerfile.php-8.4 | 9 +- composer.json | 3 +- composer.lock | 40 ++++++- docker-compose.yml | 2 +- docs/multiplexing.md | 211 +++++++++++++++++++++++++++++++++++++ phpstan.neon | 7 ++ 7 files changed, 261 insertions(+), 15 deletions(-) create mode 100644 docs/multiplexing.md create mode 100644 phpstan.neon diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 660061233e..6d8f3345ae 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.4'] steps: - name: Checkout repository @@ -25,4 +25,4 @@ jobs: sleep 10 - name: Run Tests - run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests + run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests \ No newline at end of file diff --git a/Dockerfile.php-8.4 b/Dockerfile.php-8.4 index 3246c041ac..d8fd97ff85 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,7 +10,7 @@ COPY composer.json /usr/local/src/ RUN composer update --ignore-platform-reqs --optimize-autoloader \ --no-plugins --no-scripts --prefer-dist - + FROM appwrite/utopia-base:php-8.4-1.0.0 as final ENV PHP_MEMCACHED_VERSION=v3.2.0 @@ -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/composer.json b/composer.json index 61905b9301..a3ad2d3359 100644 --- a/composer.json +++ b/composer.json @@ -17,7 +17,7 @@ "psr-4": {"Utopia\\Tests\\": "tests/Cache"} }, "require": { - "php": ">=8.2", + "php": ">=8.4", "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..de61c477ef --- /dev/null +++ b/docs/multiplexing.md @@ -0,0 +1,211 @@ +# Redis Multiplexing Adapter + +A Redis cache adapter for Swoole applications that lets many concurrent +coroutines share a single Redis TCP connection. Use it when you have a process +running lots of cooperative coroutines (an HTTP server, a worker pool) and you +do not want to open one Redis socket per request. + +This page covers usage. For internals, see the source under +`src/Cache/Adapter/Redis/`. + +## When to use it + +Pick `Redis\Multiplexing` if: + +- Your application runs inside Swoole (`Swoole\Coroutine`). +- You want one Redis connection serving N concurrent coroutines. +- Your Redis usage is request/response — no pub/sub, no transactions, no + pipelining APIs. + +Pick the plain `PhpRedis` adapter instead if: + +- You are not using Swoole. +- You manage one Redis connection per process or per request and that is fine. +- You need pub/sub, `MULTI`/`EXEC`, blocking commands, or anything outside + simple request/response. + +## Installation + +```bash +composer require utopia-php/cache +``` + +The adapter requires: + +- PHP 8.4+ +- The Swoole extension (with coroutine support) +- A reachable Redis server + +## Quick start + +```php +use Swoole\Coroutine; +use Utopia\Cache\Cache; +use Utopia\Cache\Adapter\Redis\Multiplexing; + +Coroutine\run(function () { + $adapter = new Multiplexing(host: 'redis', port: 6379); + $cache = new Cache($adapter); + + $cache->save('user:42', ['name' => 'Ada'], 'profile'); + $loaded = $cache->load('user:42', ttl: 60, hash: 'profile'); + + $adapter->disconnect(); +}); +``` + +`Multiplexing` must be constructed and used inside a Swoole coroutine. The +constructor opens the TCP connection, runs `AUTH` and `SELECT` if you supplied +them, and starts a background reader coroutine. + +## Constructor options + +```php +new Multiplexing( + host: 'redis', + port: 6379, + timeout: 0.0, // connect timeout (seconds, 0 = library default ~1s) + readTimeout: 0.25, // per-command response timeout (seconds) + auth: null, // string password, or [username, password], or null + dbIndex: 0, +); +``` + +### `readTimeout` — caches should fail fast + +The default is **250 ms**. If Redis does not respond to a command within that +window, the adapter throws a `Redis\ConnectionException`, tears down the +connection, and the next command will reconnect. The intent is that a slow or +unreachable cache surfaces immediately so you can fall back to your source of +truth, instead of stalling request-handling coroutines. + +If you have a higher-latency Redis (cross-region, encrypted tunnel) tune this +upwards. If you have a strict request budget, tune it down. + +### `auth` + +Pass either a string (password only) or `[username, password]` for ACL-style +auth. The adapter sends `AUTH` automatically before any user command runs on a +connection. A literal `'0'` is a valid password and will be sent — only `null` +suppresses `AUTH`. + +### `dbIndex` + +If non-zero, the adapter runs `SELECT ` after `AUTH`. + +## Adapter API + +`Multiplexing` implements `Utopia\Cache\Adapter`: + +| Method | Behaviour | +|---|---| +| `save($key, $data, $hash = '')` | Stores `data` under `key/hash`. Returns the saved data on success. | +| `load($key, $ttl, $hash = '')` | Returns the data if it was stored within the last `$ttl` seconds; `false` otherwise. | +| `touch($key, $hash = '')` | Re-stamps an existing entry's timestamp without rewriting its data. Returns `false` if the key is missing. | +| `purge($key, $hash = '')` | Deletes a single field (with `$hash`) or the whole key. | +| `list($key)` | Returns the field names (`HKEYS`) under a key. | +| `flush()` | Issues `FLUSHDB`. | +| `getSize()` | Returns `DBSIZE`. | +| `ping()` | Returns `true` if Redis answers `PONG`. | + +In addition: + +| Method | Purpose | +|---|---| +| `disconnect()` | Closes the connection and stops the reader coroutine. Call this on shutdown. | +| `setMaxRetries($n)` / `setRetryDelay($ms)` | Configure connection-error retries. Defaults: 0 retries. | +| `getName()` | Returns `'redis-multiplexing'`. | + +### Storage format + +Cached entries are stored as JSON envelopes: + +```json +{"time": 1700000000, "data": } +``` + +`load()` returns `data` only if `time + ttl > now()`. This means TTLs are +enforced by the adapter, not by Redis — a freshly-flushed Redis loses +everything, but a long-running Redis will keep stale entries until they are +overwritten or purged. If you need Redis-side eviction, set a `maxmemory` +policy on the server. + +## Concurrency model + +A single `Multiplexing` instance is safe to share across coroutines. +Coroutines issue commands concurrently; the adapter serialises bytes onto the +wire and dispatches replies back to the originating coroutine. Redis's +guarantee of in-order replies is what makes this work — the adapter pairs the +N-th reply with the N-th request. + +You can run thousands of coroutines through one `Multiplexing` instance. The +practical limit is the latency of your Redis: if each round-trip is 1 ms and +you sustain 1000 commands per second, queueing inside the adapter will be +minimal. If you saturate Redis, all coroutines slow down equally. + +## Error handling + +Two exception types come out of the adapter: + +- `\RedisException` — Redis returned a server-side error (`WRONGTYPE`, + `NOAUTH`, etc.). The connection is fine; the command was wrong. +- `Utopia\Cache\Adapter\Redis\ConnectionException` — the underlying connection + failed (TCP error, timeout, send failure, server closed the socket). The + adapter has already torn down the connection; the next command reconnects. + +Only `ConnectionException` is retried (when `setMaxRetries()` is non-zero). + +### What happens on a timeout + +If one command's response takes longer than `readTimeout`, that command fails +with `ConnectionException`. As a side-effect the adapter discards the +connection — every other in-flight command on that connection also fails with +`ConnectionException`. The next command from any coroutine will open a fresh +connection. + +This is by design. The alternative — letting one slow command block while +others continue — would require per-request resync logic that adds significant +complexity for little gain. A cache should fail fast and let callers fall +through to the source of truth. + +## Lifecycle and shutdown + +The adapter starts a background reader coroutine when it connects. That +coroutine holds a reference to the adapter, which means PHP's `__destruct` +will not fire while the connection is open. Call `disconnect()` explicitly +when you are done: + +```php +Coroutine\run(function () { + $adapter = new Multiplexing(host: 'redis'); + try { + // ... use $cache ... + } finally { + $adapter->disconnect(); + } +}); +``` + +In an HTTP server, that typically means: open the adapter once at server +start, share it across requests, close it on `WorkerStop`. + +## Limitations + +- **Swoole only.** Constructing the adapter outside a coroutine context does + not work. +- **No pub/sub.** Use a dedicated connection. +- **No transactions or pipelining APIs.** Commands are multiplexed + individually. +- **No cluster support.** Use `Adapter\RedisCluster` (non-multiplexed). +- **One Redis per adapter instance.** Multiple Redis hosts means multiple + adapters. +- **Connection sharing is per-process.** Each PHP worker has its own adapter + instance and its own TCP socket. + +## See also + +- `Utopia\Cache\Adapter\PhpRedis` — non-coroutine Redis adapter built on + `ext-redis`. +- `Utopia\Cache\Adapter\RedisCluster` — Redis Cluster support. +- `Utopia\Cache\Adapter\Sharding` — client-side sharding across multiple + cache adapters. 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 From 940da16553378beaf1b77c852eba9d277d577655 Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 12 May 2026 13:22:54 +0100 Subject: [PATCH 4/9] refactor: route Redis adapter through Redis\Envelope codec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the inline {time, data} JSON encode/decode/touch in Adapter\Redis with calls to Adapter\Redis\Envelope. Same logic as before, except load() now applies the envelope-shape guard the multiplexing adapter already used — previously Redis::load would crash on missing keys or non-int 'time'. Also fix the empty()-based auth check so a literal '0' password is preserved (same fix Multiplexing already had). Drop a stray testGetSize pollution in RedisTest by flushing first. Co-Authored-By: Claude Opus 4.7 --- src/Cache/Adapter/Redis.php | 43 ++++++++--------------------- tests/Cache/E2E/Redis/RedisTest.php | 1 + 2 files changed, 12 insertions(+), 32 deletions(-) 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/tests/Cache/E2E/Redis/RedisTest.php b/tests/Cache/E2E/Redis/RedisTest.php index ea385b4c7f..1d1e7bb5d9 100644 --- a/tests/Cache/E2E/Redis/RedisTest.php +++ b/tests/Cache/E2E/Redis/RedisTest.php @@ -18,6 +18,7 @@ class RedisTest extends Base public function testGetSize(): void { + self::$cache->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'); From 2cb1a0258a7d11903fbc43ee09b48910770dd907 Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 12 May 2026 15:25:50 +0100 Subject: [PATCH 5/9] chore: matrix on PHP 8.3/8.4/8.5 with utopia-base 2.0.0 The 2.0.0 utopia-base images all ship Swoole 6.2 with Coroutine\Lock plus ext-redis, so we no longer need a custom Swoole image. Drop 8.2 (no longer published in the 2.0.0 line), add 8.5, and bump the php-memcached extension to v3.4.0 (8.5-compatible). Lower the composer.json floor to >=8.3 to match the matrix. Co-Authored-By: Claude Opus 4.7 --- .github/workflows/test.yml | 2 +- Dockerfile.php-8.3 | 13 ++++--------- Dockerfile.php-8.4 | 4 ++-- Dockerfile.php-8.2 => Dockerfile.php-8.5 | 10 ++++------ composer.json | 2 +- docs/multiplexing.md | 2 +- 6 files changed, 13 insertions(+), 20 deletions(-) rename Dockerfile.php-8.2 => Dockerfile.php-8.5 (87%) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 6d8f3345ae..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.4'] + php-versions: ['8.3', '8.4', '8.5'] steps: - name: Checkout repository 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 d8fd97ff85..386f1efdac 100644 --- a/Dockerfile.php-8.4 +++ b/Dockerfile.php-8.4 @@ -11,9 +11,9 @@ 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 +FROM appwrite/utopia-base:php-8.4-2.0.0 as final -ENV PHP_MEMCACHED_VERSION=v3.2.0 +ENV PHP_MEMCACHED_VERSION=v3.4.0 LABEL maintainer="team@appwrite.io" 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 a3ad2d3359..06b863c009 100644 --- a/composer.json +++ b/composer.json @@ -17,7 +17,7 @@ "psr-4": {"Utopia\\Tests\\": "tests/Cache"} }, "require": { - "php": ">=8.4", + "php": ">=8.3", "ext-json": "*", "ext-memcached": "*", "ext-redis": "*", diff --git a/docs/multiplexing.md b/docs/multiplexing.md index de61c477ef..a0ac1ea3fd 100644 --- a/docs/multiplexing.md +++ b/docs/multiplexing.md @@ -32,7 +32,7 @@ composer require utopia-php/cache The adapter requires: -- PHP 8.4+ +- PHP 8.3+ - The Swoole extension (with coroutine support) - A reachable Redis server From 9b4093c766f83f8802f5d983bda5e4413ded3c13 Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 12 May 2026 15:41:03 +0100 Subject: [PATCH 6/9] docs: shorten multiplexing.md and reframe vs. connection pools The previous draft posed the choice as multiplexing vs. a non-coroutine PhpRedis adapter, but the realistic alternative for Swoole apps is a pool of phpredis connections (Adapter\Pool wrapping Adapter\Redis). Reframe accordingly and trim to the parts a consumer actually needs. Co-Authored-By: Claude Opus 4.7 --- docs/multiplexing.md | 211 +++++++++---------------------------------- 1 file changed, 41 insertions(+), 170 deletions(-) diff --git a/docs/multiplexing.md b/docs/multiplexing.md index a0ac1ea3fd..b2d14c9598 100644 --- a/docs/multiplexing.md +++ b/docs/multiplexing.md @@ -1,40 +1,23 @@ # Redis Multiplexing Adapter -A Redis cache adapter for Swoole applications that lets many concurrent -coroutines share a single Redis TCP connection. Use it when you have a process -running lots of cooperative coroutines (an HTTP server, a worker pool) and you -do not want to open one Redis socket per request. +A Redis cache adapter for Swoole that serves many concurrent coroutines from a +single Redis TCP connection. -This page covers usage. For internals, see the source under -`src/Cache/Adapter/Redis/`. +## When to use it vs. a connection pool -## When to use it +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. -Pick `Redis\Multiplexing` if: +`Redis\Multiplexing` is the alternative for *cache* traffic specifically: -- Your application runs inside Swoole (`Swoole\Coroutine`). -- You want one Redis connection serving N concurrent coroutines. -- Your Redis usage is request/response — no pub/sub, no transactions, no - pipelining APIs. +- 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. -Pick the plain `PhpRedis` adapter instead if: - -- You are not using Swoole. -- You manage one Redis connection per process or per request and that is fine. -- You need pub/sub, `MULTI`/`EXEC`, blocking commands, or anything outside - simple request/response. - -## Installation - -```bash -composer require utopia-php/cache -``` - -The adapter requires: - -- PHP 8.3+ -- The Swoole extension (with coroutine support) -- A reachable Redis server +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 @@ -44,168 +27,56 @@ use Utopia\Cache\Cache; use Utopia\Cache\Adapter\Redis\Multiplexing; Coroutine\run(function () { - $adapter = new Multiplexing(host: 'redis', port: 6379); + $adapter = new Multiplexing(host: 'redis'); $cache = new Cache($adapter); $cache->save('user:42', ['name' => 'Ada'], 'profile'); - $loaded = $cache->load('user:42', ttl: 60, hash: 'profile'); + $cache->load('user:42', ttl: 60, hash: 'profile'); $adapter->disconnect(); }); ``` -`Multiplexing` must be constructed and used inside a Swoole coroutine. The -constructor opens the TCP connection, runs `AUTH` and `SELECT` if you supplied -them, and starts a background reader coroutine. +Construct once at worker start, share across requests, `disconnect()` on +`WorkerStop`. The adapter must be constructed inside a Swoole coroutine. -## Constructor options +## Constructor ```php new Multiplexing( host: 'redis', port: 6379, - timeout: 0.0, // connect timeout (seconds, 0 = library default ~1s) - readTimeout: 0.25, // per-command response timeout (seconds) - auth: null, // string password, or [username, password], or null + timeout: 0.0, // connect timeout (s; 0 = ~1s) + readTimeout: 0.25, // per-command response timeout (s) + auth: null, // string password, [user, password], or null dbIndex: 0, ); ``` -### `readTimeout` — caches should fail fast +`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. -The default is **250 ms**. If Redis does not respond to a command within that -window, the adapter throws a `Redis\ConnectionException`, tears down the -connection, and the next command will reconnect. The intent is that a slow or -unreachable cache surfaces immediately so you can fall back to your source of -truth, instead of stalling request-handling coroutines. +## Errors -If you have a higher-latency Redis (cross-region, encrypted tunnel) tune this -upwards. If you have a strict request budget, tune it down. +- `\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. -### `auth` +## Telemetry -Pass either a string (password only) or `[username, password]` for ACL-style -auth. The adapter sends `AUTH` automatically before any user command runs on a -connection. A literal `'0'` is a valid password and will be sent — only `null` -suppresses `AUTH`. - -### `dbIndex` - -If non-zero, the adapter runs `SELECT ` after `AUTH`. - -## Adapter API - -`Multiplexing` implements `Utopia\Cache\Adapter`: - -| Method | Behaviour | -|---|---| -| `save($key, $data, $hash = '')` | Stores `data` under `key/hash`. Returns the saved data on success. | -| `load($key, $ttl, $hash = '')` | Returns the data if it was stored within the last `$ttl` seconds; `false` otherwise. | -| `touch($key, $hash = '')` | Re-stamps an existing entry's timestamp without rewriting its data. Returns `false` if the key is missing. | -| `purge($key, $hash = '')` | Deletes a single field (with `$hash`) or the whole key. | -| `list($key)` | Returns the field names (`HKEYS`) under a key. | -| `flush()` | Issues `FLUSHDB`. | -| `getSize()` | Returns `DBSIZE`. | -| `ping()` | Returns `true` if Redis answers `PONG`. | - -In addition: - -| Method | Purpose | -|---|---| -| `disconnect()` | Closes the connection and stops the reader coroutine. Call this on shutdown. | -| `setMaxRetries($n)` / `setRetryDelay($ms)` | Configure connection-error retries. Defaults: 0 retries. | -| `getName()` | Returns `'redis-multiplexing'`. | - -### Storage format - -Cached entries are stored as JSON envelopes: - -```json -{"time": 1700000000, "data": } -``` - -`load()` returns `data` only if `time + ttl > now()`. This means TTLs are -enforced by the adapter, not by Redis — a freshly-flushed Redis loses -everything, but a long-running Redis will keep stale entries until they are -overwritten or purged. If you need Redis-side eviction, set a `maxmemory` -policy on the server. - -## Concurrency model - -A single `Multiplexing` instance is safe to share across coroutines. -Coroutines issue commands concurrently; the adapter serialises bytes onto the -wire and dispatches replies back to the originating coroutine. Redis's -guarantee of in-order replies is what makes this work — the adapter pairs the -N-th reply with the N-th request. - -You can run thousands of coroutines through one `Multiplexing` instance. The -practical limit is the latency of your Redis: if each round-trip is 1 ms and -you sustain 1000 commands per second, queueing inside the adapter will be -minimal. If you saturate Redis, all coroutines slow down equally. - -## Error handling - -Two exception types come out of the adapter: - -- `\RedisException` — Redis returned a server-side error (`WRONGTYPE`, - `NOAUTH`, etc.). The connection is fine; the command was wrong. -- `Utopia\Cache\Adapter\Redis\ConnectionException` — the underlying connection - failed (TCP error, timeout, send failure, server closed the socket). The - adapter has already torn down the connection; the next command reconnects. - -Only `ConnectionException` is retried (when `setMaxRetries()` is non-zero). - -### What happens on a timeout - -If one command's response takes longer than `readTimeout`, that command fails -with `ConnectionException`. As a side-effect the adapter discards the -connection — every other in-flight command on that connection also fails with -`ConnectionException`. The next command from any coroutine will open a fresh -connection. - -This is by design. The alternative — letting one slow command block while -others continue — would require per-request resync logic that adds significant -complexity for little gain. A cache should fail fast and let callers fall -through to the source of truth. - -## Lifecycle and shutdown - -The adapter starts a background reader coroutine when it connects. That -coroutine holds a reference to the adapter, which means PHP's `__destruct` -will not fire while the connection is open. Call `disconnect()` explicitly -when you are done: - -```php -Coroutine\run(function () { - $adapter = new Multiplexing(host: 'redis'); - try { - // ... use $cache ... - } finally { - $adapter->disconnect(); - } -}); -``` - -In an HTTP server, that typically means: open the adapter once at server -start, share it across requests, close it on `WorkerStop`. +Implements `Cache\Feature\Telemetry`. Emits a +`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 only.** Constructing the adapter outside a coroutine context does - not work. -- **No pub/sub.** Use a dedicated connection. -- **No transactions or pipelining APIs.** Commands are multiplexed - individually. -- **No cluster support.** Use `Adapter\RedisCluster` (non-multiplexed). -- **One Redis per adapter instance.** Multiple Redis hosts means multiple - adapters. -- **Connection sharing is per-process.** Each PHP worker has its own adapter - instance and its own TCP socket. - -## See also - -- `Utopia\Cache\Adapter\PhpRedis` — non-coroutine Redis adapter built on - `ext-redis`. -- `Utopia\Cache\Adapter\RedisCluster` — Redis Cluster support. -- `Utopia\Cache\Adapter\Sharding` — client-side sharding across multiple - cache adapters. +- 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. From d409cd92462740471c1363069758918c09378bbe Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 12 May 2026 15:42:00 +0100 Subject: [PATCH 7/9] chore: namespace the multiplexing gauge under cache.* MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename redis_multiplexing.pending.depth → cache.redis_multiplexing.pending.depth to match the cache.* prefix the existing operation-duration histogram already uses. Co-Authored-By: Claude Opus 4.7 --- docs/multiplexing.md | 2 +- src/Cache/Adapter/Redis/Multiplexing.php | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/multiplexing.md b/docs/multiplexing.md index b2d14c9598..4e87c4e8c4 100644 --- a/docs/multiplexing.md +++ b/docs/multiplexing.md @@ -70,7 +70,7 @@ Per-request resync would add significant complexity for little gain. ## Telemetry Implements `Cache\Feature\Telemetry`. Emits a -`redis_multiplexing.pending.depth` gauge after each enqueue — non-zero +`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()`. diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php index 0af1e835d0..833161fa2e 100644 --- a/src/Cache/Adapter/Redis/Multiplexing.php +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -79,7 +79,7 @@ class Multiplexing implements Adapter, TelemetryFeature public function setTelemetry(Telemetry $telemetry): void { $this->pendingDepth = $telemetry->createGauge( - 'redis_multiplexing.pending.depth', + 'cache.redis_multiplexing.pending.depth', description: 'Pending response channels awaiting RESP frames on the multiplexed connection.', ); } From 611c1416128307259de9488a1e2b933b7b3ece9b Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 12 May 2026 15:49:54 +0100 Subject: [PATCH 8/9] fix: default connect timeout to 1.0s instead of fudging 0.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous default of 0.0 with a 'timeout > 0 ? timeout : 1.0' fallback was confusing — the documented default and the actual default disagreed. Use 1.0s directly so the constructor signature matches behaviour. Co-Authored-By: Claude Opus 4.7 --- docs/multiplexing.md | 2 +- src/Cache/Adapter/Redis/Client.php | 2 +- src/Cache/Adapter/Redis/Multiplexing.php | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/multiplexing.md b/docs/multiplexing.md index 4e87c4e8c4..aba47b1d9b 100644 --- a/docs/multiplexing.md +++ b/docs/multiplexing.md @@ -46,7 +46,7 @@ Construct once at worker start, share across requests, `disconnect()` on new Multiplexing( host: 'redis', port: 6379, - timeout: 0.0, // connect timeout (s; 0 = ~1s) + timeout: 1.0, // connect timeout (s) readTimeout: 0.25, // per-command response timeout (s) auth: null, // string password, [user, password], or null dbIndex: 0, diff --git a/src/Cache/Adapter/Redis/Client.php b/src/Cache/Adapter/Redis/Client.php index 4663a66c79..1f718ff3d2 100644 --- a/src/Cache/Adapter/Redis/Client.php +++ b/src/Cache/Adapter/Redis/Client.php @@ -32,7 +32,7 @@ class Client 'open_tcp_nodelay' => true, ]); - if (! $this->client->connect($host, $port, $timeout > 0 ? $timeout : 1.0)) { + if (! $this->client->connect($host, $port, $timeout)) { $errMsg = $this->client->errMsg; $this->close(); diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php index 833161fa2e..52a17d0c30 100644 --- a/src/Cache/Adapter/Redis/Multiplexing.php +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -51,7 +51,7 @@ class Multiplexing implements Adapter, TelemetryFeature public function __construct( private string $host, private int $port = 6379, - private float $timeout = 0.0, + private float $timeout = 1.0, private float $readTimeout = 0.25, private string|array|null $auth = null, private int $dbIndex = 0, From 2dbb72833acaa06d3657962e072be188e472aeb0 Mon Sep 17 00:00:00 2001 From: loks0n <22452787+loks0n@users.noreply.github.com> Date: Tue, 12 May 2026 15:50:41 +0100 Subject: [PATCH 9/9] fix: throw InvalidArgumentException for non-positive timeouts Previously readTimeout <= 0 was silently coerced to 0.25s. Better to fail loudly so misconfiguration surfaces during testing rather than masking the user's intent at runtime. Apply the same rule to the connect timeout. Co-Authored-By: Claude Opus 4.7 --- src/Cache/Adapter/Redis/Multiplexing.php | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/Cache/Adapter/Redis/Multiplexing.php b/src/Cache/Adapter/Redis/Multiplexing.php index 52a17d0c30..fcb9d9956c 100644 --- a/src/Cache/Adapter/Redis/Multiplexing.php +++ b/src/Cache/Adapter/Redis/Multiplexing.php @@ -56,8 +56,11 @@ class Multiplexing implements Adapter, TelemetryFeature 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) { - $this->readTimeout = 0.25; + throw new \InvalidArgumentException('readTimeout must be greater than 0'); } $this->sendLock = new Lock(); $this->setTelemetry(new NoTelemetry());