Dynamic Key-Slot Resolution and Cluster Cache Sovereign Validation in Valkey Core

Engineering objective

System challenge

Module commands accessing multiple undeclared keys or executing custom command handlers relied on a cached current_client->slot value. When cross-slot keys were touched or commands were dispatched across shard boundaries, the stale slot cache caused commands to execute against incorrect cluster shards, violating client cache safety guarantees and risking assertion crashes.

Constraints

Working within real limits

• ✕Preserve ultra-low-latency fast path for standard single-slot commands (zero regression on Redis/Valkey benchmark throughput)
• ✕Support arbitrary key access patterns from third-party C module APIs
• ✕Guarantee cluster slot hash consistency (16,384 hash slots) across cluster resharding and redirection
• ✕Ensure deterministic validation with Valkey integration test battery

Approach

How it was built

1. 01

   Engineered dynamic key-to-slot resolution in Valkey cluster dispatch pipeline.

2. 02

   Re-evaluated cluster slot mapping when commands declare or access arbitrary keys outside the single-key fast path.

3. 03

   Maintained client slot cache synchronization across module command lifecycles.

4. 04

   Added regression test suite covering multi-key module commands, slot boundaries, and cluster redirection.

Technical validation

Implementation evidence

Observable engineering evidence. Discipline: MERGED UPSTREAM

Public evidence

Review the upstream contribution

Outcome

What was delivered

• Eliminated cluster routing misdirection and shard misrouting crashes for custom engine modules

• Protected client-side caching safety guarantees across 16,384 cluster hash slots

• Reviewed and approved by Valkey core maintainers, merged into valkey-io/valkey core

• Zero performance overhead on single-key command fast path

Technologies

Stack and tools

Previous and Next Engineering Systems