Summary

A new Utopia\Cache\Adapter\Redis\Multiplexing adapter that lets many concurrent Swoole coroutines share a single Redis TCP connection. Designed for Swoole-based servers that want one Redis socket serving thousands of cooperative coroutines instead of one socket per request.

Includes a small refactor that pulls the Redis cache envelope out into a shared Redis\Envelope codec so the existing Adapter\Redis and the new Adapter\Redis\Multiplexing agree on storage format.

What's in src/Cache/Adapter/Redis/

• Multiplexing — the cache adapter. Holds at most one published ConnectionContext; a single send-lock serialises pending->push + client->send so the FIFO order of registered response channels matches the order of bytes on the wire and Redis's guaranteed in-order replies pair them correctly.
• Client — Swoole TCP wrapper plus the RESP2 codec (encode/parse). Owns the socket and any unread byte buffer; handshake leftovers stay in its buffer and are drained by the reader via takeBuffer().
• 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} JSON envelope (encode/decode/touch with TTL semantics). Used by both Adapter\Redis and Adapter\Redis\Multiplexing.
• ConnectionException, ConnectionError, RedisError — typed signals so the retry loop can distinguish reconnectable transport errors from server-side Redis errors.

Behaviour highlights

• Implements Cache\Feature\Telemetry — emits a redis_multiplexing.pending.depth gauge after each enqueue, the single most useful health signal for this adapter.
• readTimeout defaults to 250 ms — caches should fail fast and let callers fall through to the source of truth.
• A response timeout poisons that connection. Other in-flight commands on the same connection also see ConnectionException and the next command publishes a fresh context. By design — alternative is per-request resync logic, much more complex.
• Fixed '0' password bug — both Adapter\Redis and Adapter\Redis\Multiplexing previously skipped AUTH when the password literal was '0' (because empty('0') === true). Both now use a strict null check.

Documentation

• docs/multiplexing.md — consumer-facing guide: when to use, constructor options, error model, lifecycle, limitations.

Test plan

• vendor/bin/phpunit --testsuite unit — 46 tests / 77 assertions, no Docker needed
  • 23 Client tests covering RESP encode/parse edge cases, unwrap rethrow at top level and nested in arrays
  • 14 Envelope tests covering shape, TTL boundary, malformed JSON, nested data, touch semantics
• vendor/bin/phpunit --testsuite e2e --filter Multiplexing — 10 tests / 28 assertions
  • basic ops (save/load/purge/touch/ping/flush/getSize)
  • large and nested JSON payloads
  • 50-way concurrent multiplexing through a single shared connection
• PHPStan level max + Pint clean
• Verified locally on PHP 8.3.31, 8.4.21, and 8.5.6 (all on Swoole 6.2.0 via appwrite/utopia-base:*-2.0.0)

Notes for reviewers

• The test layout has been split into tests/Cache/Unit/ and tests/Cache/E2E/; existing tests moved unchanged under E2E/. The two phpunit testsuites (unit, e2e) let CI run the fast unit suite without Docker if needed.
• RedisCluster.php and Redis.php were intentionally not renamed in this PR; the new code lives at Adapter\Redis\* (subnamespace) and coexists with the existing top-level Adapter\Redis class.
• The CI matrix is now ['8.3', '8.4', '8.5'], dropping 8.1/8.2.

🤖 Generated with Claude Code