Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Differential testing against redis-rs

The differential corpus uses redis-rs as an independent implementation oracle, not as the Redis specification. Both clients run commands against the same server version but use separate key namespaces for every mutation. When the clients disagree, Redis documentation and server behavior decide the expected contract.

The test-only dependency is pinned to redis = 1.7.0; the per-PR job records the resolved oracle package with cargo tree alongside the Redis server version. It is not a production dependency. Standalone command and conversion failures report the case, command or step, adapter side, selected RESP protocol, live Redis version, both client versions, and deterministic seed (0x52454449535f4d43). Connection failures use server=unavailable because no server version can be queried safely. A synthetic user/password regression drives both adapters through connection failure and verifies that neither the target nor raw error text reaches the captured panic message.

Initial MCP-derived case ledger

BehaviorInput and isolated setupExpected semanticsProtocol/server requirementredis-tower adapterredis-rs adapter
Scalar, null, empty, and binaryGET missing; binary-safe SET/GET/ECHO; MGET over present, missing, and empty values in per-client namespacesNull stays distinct from empty bytes; arbitrary bytes round-trip without UTF-8 lossRESP2 and RESP3; Redis 7.4.3 and 8.0.6 per PRRedisConnection + RawCommandasync MultiplexedConnection + Cmd
Remaining typed binary familiestyped RENAME, EVAL, ECHO, PUBLISH, GEOADD, PFADD, and BITOP with invalid UTF-8, NUL, CR/LF, and protocol-looking bytesTyped serialization and server-visible results agree without decoding opaque argumentsRESP2 and RESP3typed command buildersCmd with byte-slice arguments
Numeric boundaries and decodingStore u64::MAX, -1, and invalid UTF-8 as bulk valuesBoth decode the maximum as u64; both reject negative-to-u64 and invalid UTF-8-to-String conversionsRESP2 and RESP3TypedRawCommand<u64/String>FromRedisValue<u64/String>
Typed builder optionsExercise Set::nx().get() against an existing key and Set::xx().get() against a missing key; compare the returned old value and a follow-up GETBuilder options reach the wire: NX preserves the existing value and XX does not create a missing keyRESP2 and RESP3typed Set builderCmd with explicit NX/XX/GET arguments
Hashes and unordered setsInvalid-UTF-8 keys, binary hash value plus multiple fields; set members inserted in a different lexical orderHGETALL compares as sorted pairs; SMEMBERS compares as a sorted collectionRESP2 flat pairs / arrays and RESP3 maps / setstyped HSet / SAdd, raw response normalized after decodeCmd request and raw response
Lists and sorted setsInvalid-UTF-8 keys, ordered list including binary bytes; ZRANGE WITHSCORESList order is preserved; zset member/score pairs survive RESP2/RESP3 shape differencesRESP2 and RESP3typed RPush / ZAdd, raw responseCmd request and raw response
Streams and nested repliesInvalid-UTF-8 stream key, deterministic typed XADD 1-0, then XRANGEEntry IDs, field order, binary values, and nested structure agreeRedis 5+; RESP2 and RESP3typed XAdd, raw responseCmd request and raw response
Server and conversion errorsGET against a list; INCR at i64::MAX; typed range/UTF-8 failuresServer error codes agree (WRONGTYPE, ERR); client-side conversion failures remain failures without pretending their library-specific categories are identicalRESP2 and RESP3RedisError classificationredis::RedisError classification
Raw and administrative shapesLua returns null, empty aggregate, status, integer, and binary values; COMMAND INFO GET returns administrative nestingOrdered nested values agree without blanket flattening or lossy conversionRESP2 and RESP3RawCommandCmd
Pipeline outcome and alignmentSET, failing HSET, then GET, followed by PINGPer-command failure is retained, later reply stays paired with GET, and the next command remains alignedRESP2 and RESP3PipelinePipeline::ignore_errors
Transaction commit and abortAtomic SET/INCR/GET; separate clients mutate a watched key before EXECCommit results agree; WATCH conflict returns an aborted transaction and does not apply its bodyRESP2 and RESP3Transaction / exclusive connectionatomic Pipeline / exclusive connection
Blocking command ownershipSeed independent lists, then BLMOVE binary data with a finite timeoutResults agree while each blocking operation owns a dedicated, unshared sessionRedis 6.2+; RESP2 and RESP3dedicated RedisConnectionunshared async connection
Public topology entry pointsBinary SET/GET through live Cluster and Sentinel fixtures, with an independent redis-rs Cluster connection or direct connection to the Sentinel-discovered masterRouting/discovery does not change the binary result; mutations remain in independent namespacesPer-PR Redis 7.4.3 and 8.0.6 Cluster/Sentinel fixture legsClusterConnection / SentinelConnectionasync Cluster connection / direct async master connection
RedisJSON module repliesIndependent JSON documents; compare JSON.GET and unordered JSON.OBJKEYSJSON bytes agree and object-key order is the only normalizationPath-filtered per-PR and nightly module-enabled Redis 8; RESP2 and RESP3RawCommandCmd
Queued cancellationCancel single and multi requests before the configured batch window closesCancelled queue entries never reach the socketDeterministic in-memory/TCP fixture; no Redis processAutoPipelineServiceNot applicable: redis-tower lifecycle contract
Lost non-idempotent replyFake server records an INCR-like request, applies it once, then closes before replying; replacement socket receives a probeCaller gets an error, execution remains unknown, and reconnect never silently replays the writeDeterministic TCP fixture; no Redis processfactory-backed AutoPipelineServiceNot applicable: redis-tower lifecycle contract
Connected peer withholds repliesFake peer applies one INCR-like write while keeping TCP open; single request gets no reply, multi request gets only its first replyExplicit response timeout surfaces CommandTimeout; old socket closes, replacement probe stays aligned, and the write is not replayedBounded deterministic TCP fixture; no Redis process or packet-level partitionfactory-backed AutoPipelineServiceNot applicable: redis-tower lifecycle contract

The executable standalone cases live in differential_redis_rs.rs. The RedisJSON case lives in differential_module_replies.rs and is selected by the per-PR module gate and module-enabled nightly job.

Normalization policy

Normalization is deliberately narrow:

  • Sets are sorted because Redis does not promise member order.
  • RESP2 flat pair arrays, RESP3 pair arrays, and RESP3 maps become sorted pairs only for commands whose documented result is a map or pair collection.
  • Status strings and bulk strings preserve their bytes; OK is not converted through UTF-8 to compare successfully.
  • Null and empty values, ordered arrays, integer widths, binary bytes, and server error codes are never collapsed together.
  • Client-side conversion error taxonomies may differ; the shared contract is rejection, while server-originated error codes must agree.

The negative controls prove that the comparator rejects lossy binary conversion, reversed sorted-set rank order, and a removed NX option from the typed Set path. A replay-count control and the live lost-reply fixture fail if a non-idempotent request executes twice.

Cancellation and unknown execution

There are three materially different states:

  1. A request cancelled while still queued is unsent and has no server effect.
  2. A request whose complete reply was received has a known result.
  3. A request written before its connection loses the reply has unknown execution. Reconnection cannot determine whether Redis applied it.

redis-tower removes cancelled queue entries before flushing and quarantines a connection whose reply alignment is no longer knowable. It does not replay the lost non-idempotent request on the replacement socket. Applications that retry an unknown-execution write must supply their own idempotency mechanism.

An explicit AutoPipelineConfig::response_timeout also bounds a connected peer that stops replying, including after only part of a pipeline’s responses arrive. The deterministic TCP regressions keep that socket open until the timeout is observed, then verify quarantine and useful replacement work without replay. This is a client response-stall fixture, not a real network-partition test; the default has no response deadline, so applications must configure one.

Reproduction

cargo test -p redis-tower --test differential_redis_rs \
  --all-features -- --test-threads=1

# Requires REDIS_URL pointing at a RedisJSON-capable server.
cargo test -p redis-tower-modules --test differential_module_replies \
  --all-features -- --ignored --test-threads=1