Valkey Contributor Reference

Routing

• Building/compiling -> Build & Test (building, sanitizers)
• Crash/hang investigation -> Architecture (event-loop), Threading, Monitoring (debug)
• Data type behavior -> Data Structures (encoding-transitions), Config (db-management)
• Eviction/maxmemory/LRU/LFU -> Memory (eviction)
• Memory fragmentation/allocation -> Memory (defragmentation, zmalloc, lazy-free)
• Performance work -> Threading (io-threads, prefetch), Memory, Monitoring (latency)
• New command implementation -> Architecture (command-dispatch), Modules (module-lifecycle)
• Test writing -> Build & Test (tcl-test-runner, tcl-test-api, unit-tests), Testing (ci-pipeline)
• CI failures -> Testing (ci-pipeline), Build (sanitizers)
• Security/auth -> Security (acl, tls)
• Replication/HA -> Replication, Cluster (failover), Sentinel
• Slot migration -> Cluster (slot-migration)
• Persistence/snapshots/durability -> Persistence (rdb, aof)
• Lua scripting/EVAL -> Scripting (eval, functions, scripting-engine-architecture)
• Pub/Sub internals -> Pub/Sub (pubsub, notifications)
• MULTI/EXEC/blocking commands -> Transactions (multi-exec, blocking)
• Networking/RESP/client connections -> Architecture (networking, resp-protocol)
• Key expiration/TTL -> Config (expiry)
• CONFIG system/runtime settings -> Config (config-system)
• Client-side caching -> Monitoring (tracking)
• Logging/commandlog -> Monitoring (commandlog)
• Module development -> Modules (module-lifecycle, module-patterns, custom-types, key-api-and-blocking, rust-sdk)
• RDMA/transport -> Valkey-Specific (rdma, transport-layer)
• KVStore/object internals -> Valkey-Specific (kvstore, object-lifecycle, vset)
• Contributing/PR process -> Contributing (workflow, governance)

Quick Start

# Build
make -j$(nproc)

# Run tests
./runtest --verbose
./runtest-cluster
./runtest-moduleapi
make test-unit

# Debug build
make noopt

# Build with sanitizers
make SANITIZER=address

Critical Rules

1. DCO sign-off required - every commit needs Signed-off-by (workflow)
2. clang-format-18 - CI rejects formatting violations (workflow)
3. Tests are non-negotiable - every contribution must include tests (tcl-test-runner)
4. camelCase functions, snake_case variables - see coding style in workflow
5. No anonymous contributions - real identity required

Architecture

Topic	Reference
Repository layout, valkeyServer struct, main() boot	overview
ae.c reactor pattern, epoll/kqueue, beforeSleep	event-loop
RESP parsing to command execution, processCommand	command-dispatch
Client lifecycle, buffers, I/O threading states	networking
RESP2/RESP3 types, inline/multibulk parsing	resp-protocol

Data Structures

Topic	Reference
Simple Dynamic Strings - 5 header variants, binary safe	sds
Open-addressing hash table (8.1+), 64-byte buckets, SIMD	hashtable
Legacy chained hash table, incremental rehashing	dict
Compact sequential encoding for small collections	listpack
Doubly-linked list of listpacks, LZF compression	quicklist
Probabilistic sorted structure for sorted sets	skiplist
Compressed radix tree for streams and consumer groups	rax
When Valkey switches between compact and full encodings	encoding-transitions

Persistence

Topic	Reference
RDB snapshot format, BGSAVE fork, RDB loading	rdb
Multi-part AOF (BASE + INCR + manifest), fsync policies	aof

Replication

Topic	Reference
PSYNC, replication backlog, dual IDs, propagation	overview
Dual-channel replication (8.0+), parallel RDB transfer	dual-channel

Cluster

Topic	Reference
Hash slots, gossip protocol, cluster bus, MOVED/ASK	overview
PFAIL/FAIL detection, epoch-based election, manual modes	failover
Traditional MIGRATE and atomic slot migration (9.0)	slot-migration

Sentinel

Topic	Reference
Activation, data structures, monitoring, failure detection	sentinel-monitoring
Leader election, failover state machine, commands, config, Pub/Sub events, script hooks, timing	sentinel-failover

Memory Management

Topic	Reference
zmalloc wrapper, jemalloc integration, memory tracking	zmalloc
Background deletion (UNLINK), async free via BIO	lazy-free
Active defragmentation in 500us cycles, slab analysis	defragmentation
Eviction policies, LRU/LFU approximation, maxmemory enforcement	eviction

Threading

Topic	Reference
I/O thread pool, lock-free SPSC queues, read/write offload	io-threads
Background I/O threads - fsync, lazy free, close, RDB save	bio
Batch key prefetching for 50%+ pipeline throughput gain	prefetch

Scripting

Topic	Reference
EVAL/EVALSHA, Lua integration, script caching	eval
FUNCTION LOAD/CALL, library-grouped persistent functions	functions
Scripting engine data structures, ABI versions, method table	scripting-engine-architecture
Engine registration, unregistration, debugger, adding engines	scripting-engine-lifecycle

Security

Topic	Reference
ACL system - users, selectors, command categories, audit	acl
TLS/mTLS, certificate management, background reloading	tls

Pub/Sub

Topic	Reference
Channel/pattern subscriptions, sharded pub/sub	pubsub
Keyspace notifications, event types, config flags	notifications

Transactions

Topic	Reference
MULTI/EXEC/WATCH, optimistic locking, error handling	multi-exec
Blocking commands (BLPOP etc.), key readiness, timeouts	blocking

Configuration

Topic	Reference
Config parsing, runtime CONFIG SET, type system, apply callbacks	config-system
Database selection, key lookup, SCAN, FLUSHDB	db-management
Active/lazy expiration, hash field TTL, replica expiry	expiry

Monitoring

Topic	Reference
Command logging (slow, large-request, large-reply)	commandlog
Latency monitoring framework, 25+ event types, DOCTOR	latency
Client-side caching, invalidation, broadcast mode	tracking
DEBUG command, crash reporting, software watchdog	debug

Modules

Topic	Reference
Module load/unload lifecycle, command registration, context	module-lifecycle
Error handling, memory management, versioning, example, replies, Redis module backward compatibility	module-patterns
Custom data types, RDB serialization, type methods	custom-types
Key access API, blocking commands, thread-safe contexts	key-api-and-blocking
Rust module SDK, valkey-module crate, C-vs-Rust comparison	rust-sdk

Valkey-Specific Subsystems

Topic	Reference
Multi-index KV store, Fenwick tree, per-slot organization	kvstore
robj with embedded key/expire, encoding management	object-lifecycle
Pluggable connection type framework (TCP/TLS/Unix/RDMA)	transport-layer
RDMA transport protocol, Linux-only, page-aligned buffers	rdma
Volatile set (vset) - adaptive expiry-aware set with SIMD probe	vset

Build & Test

Topic	Reference
Make/CMake, flags, dependencies, cross-platform	building
ASan, UBSan, TSan, Valgrind, Helgrind	sanitizers
Tcl test runner, directory structure, tags system	tcl-test-runner
Tcl test framework API, assertions, writing new tests	tcl-test-api
Google Test C++ unit tests	unit-tests
CI pipeline - PR gates, daily matrix, skip tokens	ci-pipeline

Contributing

Topic	Reference
PR process, coding style, DCO, commit conventions	workflow
TSC, maintainers, voting rules, release cadence	governance