tiny-redis-server

A high-performance, Redis-compatible in-memory key-value database engine implemented in modern C++ (C++20). Designed with a single-threaded non-blocking Reactor event loop (kqueue on macOS / POSIX BSD), zero third-party dependencies, and 100% behavioral parity verified against official Redis servers.

• Non-blocking Reactor Pattern: Native kqueue event-driven architecture delivering sub-millisecond latency and concurrency without thread-synchronization overhead.
• Run-to-Completion Concurrency Model: Atomic command execution per request avoids locking granularity penalties and race conditions.
• Full RESP2 Protocol Engine: Incremental, zero-copy buffer parsing supporting both inline requests and multibulk payloads. Pipelining-friendly by batching responses.
• Production-Grade SkipList with Span Ranks: Hand-crafted SkipList matching Redis's dual-index specification (dict + skiplist), maintaining level spans for $O(\log N)$ rank calculation, reverse rank lookup, and score range queries.
• Dual Expiration Mechanism: Combines millisecond-precision passive/lazy expiration on access with active randomized adaptive bucket sampling cycles.
• RDB Snapshot Persistence: Binary snapshotting with CRC32 integrity checksums and asynchronous BGSAVE powered by fork() Copy-On-Write (COW).
• Transactions & Multidatabase: Full support for MULTI / EXEC / DISCARD atomic execution queues, syntax pre-validation, and 16 configurable logical databases.
• Zero External Dependencies: Pure C++20 using only the standard library and OS POSIX system calls.

graph TD
    Client[Client Connections / redis-cli / SDKs] -->|RESP2 Protocol| Kqueue[Reactor Event Loop: kqueue]
    
    subgraph Engine [tiny-redis-server Core]
        Kqueue -->|I/O Demux| Parser[RESP2 Incremental Request Parser]
        Parser -->|Parsed Command Vectors| Dispatcher[Command Dispatcher & Arity Validator]
        
        Dispatcher -->|Multi / Tx Queue| Tx[Transaction Manager]
        Dispatcher -->|Direct Execution| Storage[Multi-Database Storage 0..15]
        
        subgraph Data Structures
            Storage --> STR[String / SDS]
            Storage --> HASH[Hash / std::unordered_map]
            Storage --> LIST[List / std::deque]
            Storage --> SET[Set / std::unordered_set]
            Storage --> ZSET[ZSet: SkipList + Hash Table]
        end
        
        Storage --> Expire[Expiration Engine: Lazy & Active Sampler]
        Storage --> Memory[Real-Time Memory Accounting]
    end
    
    subgraph Persistence [Persistence Subsystem]
        Storage -.->|SAVE: Synchronous Block| RDBFile[(dump.rdb Binary CRC32)]
        Storage -.->|BGSAVE: fork Copy-On-Write| ChildProc[Background COW Worker]
        ChildProc -->|Atomic Rename| RDBFile
    end

Tested on Apple M4 (10 cores, 16GB RAM, macOS Darwin ARM64) using official redis-benchmark comparing tiny-redis directly against official redis-server 8.6.2.

• Test parameters: -n 20000 -c 50 -d 100 -q (20,000 requests, 50 concurrent connections, 100-byte payloads).

Conclusion: tiny-redis consistently delivers 240,000 ~ 255,000 requests per second across string, hash, list, set, and sorted-set operations, with median p50 latency hovering around 0.1 ms, achieving parity with production C Redis.

To ensure absolute adherence to Redis specifications, tiny-redis includes a differential parity testing framework (scripts/smoke.sh):

1. Unit Test Suite:
   • test_resp: Validates inline, multibulk, malformed payloads, and edge cases.
   • test_zskiplist: Verifies SkipList insertion, duplicate handling, forward/backward spans, rank calculations, and rank range slices.
   • test_ttl_rdb: Verifies CRC32 verification, active/passive expiration, and fork-based BGSAVE snapshot restoration.
   • test_commands: Tests state transitions across all 60+ commands.
2. Side-by-Side Dual Engine Parity Matrix:
   • Simultaneously spins up tiny-redis and official redis-server.
   • Runs 127 complex command sequences through the official redis-cli.
   • Compares raw protocol replies byte-for-byte.
   • Result: == parity: 127 pass, 0 fail == (100% Pass Rate).

• Modern C++ compiler supporting C++20 (clang++ $\ge 14$ or g++ $\ge 11$).
• macOS / POSIX BSD (kqueue).
• Optional: redis-tools (redis-cli, redis-benchmark) for parity and load tests.

# Build server and all unit test binaries
make -j$(sysctl -n hw.ncpu)

# Run full test suite
make test

# Run on default port 6379
./build/tiny-redis

# Or run with custom port and directory
./build/tiny-redis -p 6398 -d /tmp/redis-data

redis-cli -p 6398

127.0.0.1:6398> SET greeting "Hello, Modern C++"
OK
127.0.0.1:6398> GET greeting
"Hello, Modern C++"
127.0.0.1:6398> ZADD leaderboard 100 alice 200 bob 150 charlie
(integer) 3
127.0.0.1:6398> ZREVRANGE leaderboard 0 -1 WITHSCORES
1) "bob"
2) "200"
3) "charlie"
4) "150"
5) "alice"
6) "100"
127.0.0.1:6398> BGSAVE
+Background saving started

make smoke

1. Why kqueue instead of epoll or Boost.Asio?
   • Zero-dependency minimalism with raw syscalls. Demonstrates deep understanding of OS-level I/O multiplexing, changelist semantics, and event filters (EVFILT_READ, EVFILT_WRITE, EVFILT_SIGNAL).
2. Why hand-roll SkipList with level spans?
   • Most hobbyist Redis implementations use std::set or std::map, sacrificing $O(\log N)$ rank calculation (ZRANK / ZREVRANGE). Maintaining span during insert and delete enables true logarithmic rank retrieval and exact Redis compatibility.
3. Copy-On-Write Persistence via fork():
   • Implements zero-downtime background snapshotting. The child process writes to a temporary file with CRC32 integrity check and atomically renames to dump.rdb upon completion, eliminating file corruption risks.

MIT License. See LICENSE for details.