A lightweight, standalone, in-memory caching daemon built entirely from first principles in Java 21 with zero third-party dependencies. Speaks the Redis Serialization Protocol (RESP) over raw TCP sockets, featuring a custom separate-chaining hash table, sentinel-based
$O(1)$ LRU queue eviction, absolute 64-bit epoch TTLs, and a multi-threaded connection server.
MiniCache requires zero build tools (no Maven, no Gradle) and zero external libraries. All you need is JDK 21+.
git clone https://github.com/logicbyabhinav/MiniCache.git && cd MiniCache && javac -d bin -sourcepath src src/com/minicache/*.java src/com/minicache/engine/*.java src/com/minicache/command/*.java src/com/minicache/server/*.java && java -cp bin com.minicache.MiniCache- Windows:
run.bat
- Linux / macOS:
chmod +x run.sh && ./run.sh
MiniCache will bind to TCP port 6379. Connect using any standard Redis client or telnet:
redis-cli -p 6379127.0.0.1:6379> PING
PONG
127.0.0.1:6379> SET user abhinav EX 60
OK
127.0.0.1:6379> GET user
"abhinav"
MiniCache lives directly alongside your primary database to serve repetitive reads in nanoseconds from volatile RAM:
[ Web Client / Microservice ]
│
│ HTTP / RPC
▼
┌────────────────────────────────────────────────────────┐
│ Application Server (Node.js / Python / Go) │
│ • Authenticates requests & executes business logic │
└───────────────┬────────────────────────┬───────────────┘
│ │
(1) Fast Cache Query │ (3) DB Query on Cache Miss
(Sub-millisecond) │ (~15ms disk fetch)
▼ ▼
┌───────────────────────┐ ┌────────────────────────┐
│ MiniCache │ │ Primary Database │
│ (Java TCP Daemon) │ │ (PostgreSQL / SQLite) │
│ Port: 6379 │ │ Durable Disk Storage │
└───────────────────────┘ └────────────────────────┘
MiniCache is organized into three strictly decoupled pillars:
+---------------------------------+
| MiniCache.java |
| (Bootstrap Orchestration) |
+---------------------------------+
|
v
+-----------------------------------------------------------------------------------------------+
| PILLAR 1: SERVER (Network Transport Layer) : com.minicache.server |
| - MiniCacheServer.java |
| • Binds to TCP port 6379 via ServerSocket. |
| • Dedicated Acceptor loop dispatches connections to an ExecutorService thread pool. |
| • Manages per-client socket streams (BufferedReader / PrintWriter with auto-flush). |
+-----------------------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------------------+
| PILLAR 2: COMMAND (Protocol & Dispatcher Layer) : com.minicache.command |
| - CommandHandler.java |
| • Splits raw lines into command tokens via whitespace regex (\\s+). |
| • Enforces arity & syntax validation (PING, SET, GET, DEL, EXISTS). |
| • Serializes outputs into standard Redis RESP wire protocol (+OK, $len, :int, -ERR, $-1). |
+-----------------------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------------------+
| PILLAR 3: ENGINE (Core Data Store & Eviction Layer) : com.minicache.engine |
| - CacheObject.java : Raw data envelope, 64-bit epoch deadlines, access timestamps. |
| - CacheMap.java : Custom separate-chaining hash table with polynomial rolling hash. |
| - CacheEngine.java : Thread-safe policy controller, O(1) LRU eviction, and lazy TTL pruning. |
+-----------------------------------------------------------------------------------------------+
When capacity is reached, MiniCache evicts the least-recently used key in strict
- Sentinels (
headandtail): Guard boundaries ensure insertions and deletions execute in zero boundary null-checks. - Direct Reference Pointer Hook:
CacheObjectholds a direct reference to itsNodein the LRU queue. Access promotion duringget()requires zero hash lookup hops.
MiniCache is wire-compatible with Redis 2.0+ specifications:
| Command | Syntax | Success Return | Error / Miss Return | Wire Description |
|---|---|---|---|---|
PING |
PING [msg] |
+PONG\r\n or $<len>\r\n<msg>\r\n
|
-ERR wrong number of arguments... |
Heartbeat & connection check |
SET |
SET <k> <v> [EX sec] |
+OK\r\n |
-ERR syntax error / -ERR value...
|
Stores key with optional TTL |
GET |
GET <k> |
$<len>\r\n<val>\r\n |
$-1\r\n (Null Bulk String) |
Fetches value; promotes in LRU |
DEL |
DEL <k> |
:1\r\n (if deleted) |
:0\r\n (if absent) |
Unlinks from hash table & LRU |
EXISTS |
EXISTS <k> |
:1\r\n (if present) |
:0\r\n (if absent/expired) |
Probes key without LRU promotion |
Every design choice is formally documented with context, alternatives, and trade-offs in ENGINEERING_DECISIONS.md:
- ADR-001: The 3-Pillar Architecture vs. Deep Modularization
- ADR-002: Data Envelope Attributes & Memory Representation
- ADR-003: Absolute 64-Bit Epoch Deadlines vs. Relative Offsets
- ADR-004: Fail-Fast Key Validation vs. Silent Fallback
- ADR-005: Lazy On-Access Pruning vs. Active Background Sweeping
-
ADR-006: Custom Separate Chaining Hash Table vs.
ConcurrentHashMap -
ADR-007: Polynomial Rolling Hash (
$p=31$ ) vs.Object.hashCode() - ADR-008: Bitwise Index Masking vs. Modulo Arithmetic
- ADR-009: CacheObject Immutability vs. Mutable In-Place Payloads
- ADR-010: Synchronized Monitors vs. ReadWriteLocks
- ADR-011: Non-Intrusive Separation: "Books cannot make a shelf"
-
ADR-012: Decoupling Hash Collisions from LRU Queuing (
Storevs.Node) - ADR-013: Chasing Pointer Deletion with Pop-Style Semantics
-
ADR-014:
$O(1)$ LRU Eviction via Doubly Linked List with Sentinels - ADR-015: RESP Length-Prefixed Framing & Binary Safety
- ADR-016: Multi-Threaded TCP ServerSocket & Graceful Shutdown Hooks
MiniCache contains end-to-end integration test harnesses verifying hash collisions, sentinel pointers, LRU promotion, lazy TTL eviction, RESP wire framing, and multi-client socket concurrency:
# Run Core Engine Tests (LRU Eviction + TTL Expiration + Hash Collisions)
javac -d bin -sourcepath src -cp bin test/TestEngine.java && java -ea -cp bin test.TestEngine
# Run Protocol & Command Tests (RESP Formatting + Edge Cases)
javac -d bin -sourcepath src -cp bin test/TestCommandHandler.java && java -ea -cp bin test.TestCommandHandler
# Run Live Multi-Threaded TCP Socket Tests (Concurrent Client Threads)
javac -d bin -sourcepath src -cp bin test/TestLiveServer.java && java -ea -cp bin test.TestLiveServerRecommended tags for this repository:
cache · redis · resp-protocol · java21 · systems-programming · in-memory-database · lru-cache · tcp-sockets · data-structures · zero-dependencies
MiniCache's forward engineering path is documented in ROADMAP.md:
- v1.1.0: Multi-line RESP 2 Array Parser (
*<count>\r\n), active background TTL sweeping, and counter primitives (INCR/DECR/MGET/MSET). - v1.2.0: Durability via Append-Only File (AOF) write-ahead logging,
fsyncpolicies, and background compaction (BGREWRITEAOF). - v1.3.0: Rich collection primitives: Doubly-linked Lists, embedded Hash Maps, and Sets.
- v2.0.0: Non-blocking Java NIO Reactor architecture (
Selectorevent loop) and pipelining benchmarked againstredis-benchmark.
Released under the MIT License. Copyright (c) 2026 Abhinav Kishore.