Skip to content

README.md

Latest commit

 

History

History
496 lines (365 loc) · 10.5 KB

README.md

File metadata and controls

496 lines (365 loc) · 10.5 KB
Raw

Distributed Cache

A Java 21 distributed in-memory cache server with HTTP and TCP APIs, configurable eviction, TTL expiration, cache metrics, list operations, and basic cluster routing/replication.

The project is built with Spring Boot and Gradle. It can run as a single local cache node or as multiple coordinated nodes using consistent hashing and a configurable replication factor.

Features

  • In-memory key/value cache backed by ConcurrentHashMap
  • Configurable maximum capacity
  • TTL support for string values
  • Background cleanup of expired entries
  • LRU and MRU eviction policies
  • String and integer key codecs
  • String values and list values
  • HTTP REST API for cache operations
  • TCP command protocol with line-based and RESP-style command support
  • Client library for TCP access
  • Cache metrics: hits, misses, evictions, expirations, and hit rate
  • Cluster membership, health checks, gossip-based topology sharing, routing, and replication
  • Docker image support
  • Unit tests with JUnit 5 and Mockito
  • Checkstyle configuration

Technologies

  • Java 21
  • Spring Boot 3.3.4
  • Gradle
  • Spring Web
  • JUnit 5
  • Mockito
  • Checkstyle
  • Docker

Project Structure

.
|-- build.gradle
|-- Dockerfile
|-- settings.gradle
|-- config/
|   `-- checkstyle/
|-- src/
|   |-- main/
|   |   |-- java/org/cache/
|   |   |   |-- Main.java
|   |   |   |-- client/              # TCP client API and serializers
|   |   |   |-- cluster/             # Cluster membership, gossip, health, hashing
|   |   |   |-- config/              # YAML config loading and validation
|   |   |   |-- core/                # Cache abstractions and local cache implementation
|   |   |   |-- eviction/            # LRU/MRU eviction policies
|   |   |   |-- network/             # HTTP controllers and TCP server/connection code
|   |   |   `-- protocol/            # Command processor, codecs, handlers
|   |   `-- resources/
|   |       |-- config.yml
|   `-- test/
|       |-- java/org/cache/
|       `-- resources/config/
`-- gradle/

Requirements

  • JDK 21
  • Gradle wrapper included in this repository
  • Docker, optional

On Windows, use gradlew.bat. On macOS/Linux, use ./gradlew.

Build

./gradlew build

Windows:

.\gradlew.bat build

Run Tests

./gradlew test

Windows:

.\gradlew.bat test

Run the Application

Default configuration is loaded from src/main/resources/config.yml.

./gradlew bootRun

Windows:

.\gradlew.bat bootRun

The default config.yml starts:

  • HTTP server on port 8080
  • Client TCP server on port 2020
  • Cluster TCP server on port 10001

Configuration

Configuration is loaded from a classpath YAML file. The default file name is config.yml.

You can choose another config file with the cache.config system property when running the built jar:

java -Dcache.config=config-node-a.yml -jar build/libs/distributed-cache-1.0-SNAPSHOT.jar

Example:

capacity: 100
defaultTtlMillis: 0
eviction-policy: lru
key-type: string

node:
  id: node-a
  host: localhost
  http-port: 8080
  tcp-port: 2020
  cluster-port: 10001

cluster:
  replication-factor: 1
  nodes:
    - id: node-a
      host: localhost
      http-port: 8080
      tcp-port: 2020
      cluster-port: 10001
    - id: node-b
      host: localhost
      http-port: 8081
      tcp-port: 2021
      cluster-port: 10002

Configuration Options

Key Description Default
capacity Maximum number of entries stored locally before eviction 1000
defaultTtlMillis Default TTL in milliseconds. 0 means no expiration 0
eviction-policy Eviction strategy: lru or mru lru
key-type Key codec: string or int string
node.id Current node id node-a
node.host Current node host localhost
node.http-port HTTP API port 8080
node.tcp-port Public TCP cache command port 2020
node.cluster-port Internal cluster command port 10001
cluster.replication-factor Number of owners selected for each key 1 when cluster config exists
cluster.nodes List of known cache nodes none

If the cluster section is omitted, the application runs as a single local node.

HTTP API

Base path: /cache

Health Check

curl http://localhost:8080/cache/ping

Response:

{"value":"PONG"}

You can echo a custom value:

curl "http://localhost:8080/cache/ping?value=hello"

Put a String Value

curl -X PUT http://localhost:8080/cache/1 \
  -H "Content-Type: application/json" \
  -d '{"value":"Ferid"}'

With TTL:

curl -X PUT http://localhost:8080/cache/1 \
  -H "Content-Type: application/json" \
  -d '{"value":"Ferid","ttlMillis":60000}'

Get a String Value

curl http://localhost:8080/cache/1

Response:

{"value":"Ferid"}

Delete a Key

curl -X DELETE http://localhost:8080/cache/1

Clear the Cache

curl -X DELETE http://localhost:8080/cache

Cache Size

curl http://localhost:8080/cache/size

Response:

{"size":1}

Metrics

curl http://localhost:8080/cache/metrics

Response:

{
  "hits": 10,
  "misses": 2,
  "evictions": 1,
  "expirations": 0,
  "hitRate": 0.8333333333333334
}

List Operations

Append a value to a list:

curl -X POST http://localhost:8080/cache/10/list \
  -H "Content-Type: application/json" \
  -d '{"value":"write-readme"}'

Read a range:

curl "http://localhost:8080/cache/10/list?from=0&to=10"

Response:

{"values":["write-readme"]}

Cluster HTTP API

Base path: /cluster

Add a node:

curl -X POST http://localhost:8080/cluster/nodes \
  -H "Content-Type: application/json" \
  -d '{"id":"node-c","host":"localhost","httpPort":8082,"tcpPort":2022,"clusterPort":10003}'

Remove a node:

curl -X DELETE http://localhost:8080/cluster/nodes/node-c

When membership changes, the node broadcasts the updated topology to peers.

TCP API

The TCP server accepts simple line commands and RESP-style array commands. By default, the public TCP port is 2020.

Line protocol examples:

PING
PUT 1 Ferid
PUT 2 Ferid 60000
GET 1
DELETE 1
SIZE
METRICS
PUSH 10 write-readme
LRANGE 10 0 10
CLEAR

Common responses:

OK
PONG
VALUE Ferid
NOT_FOUND
SIZE 1
METRICS hits=1 misses=0 evictions=0 expirations=0 hitRate=1.0
LIST write-readme
ERROR usage: GET key

You can test the line protocol with tools such as nc:

nc localhost 2020

Then type commands, one per line.

Supported TCP Commands

Command Description
PING [value] Returns PONG or the provided value
PUT key value [ttlMillis] Stores a string value
GET key Reads a string value
DELETE key Deletes a key
SIZE Returns local cache size
CLEAR Clears local cache
METRICS Returns cache metrics
PUSH key value Appends a value to a list
LRANGE key [from] to Reads list values in a range
CLUSTER_ADD_NODE id host httpPort tcpPort clusterPort Adds a node and gossips topology
CLUSTER_REMOVE_NODE nodeId Removes a node and gossips topology
TOPOLOGY_DIGEST Internal topology digest command
TOPOLOGY_GET Internal topology fetch command
TOPOLOGY_APPLY ... Internal topology apply command

Clustering

The cluster layer uses consistent hashing to choose owners for a key. Writes are sent to every owner selected by the configured replication factor. Reads try the selected owners and return from the first available owner.

Important cluster behavior:

  • cluster.replication-factor controls how many nodes own each key.
  • Unavailable nodes are skipped by the hash ring.
  • Each node has a public TCP port and an internal cluster TCP port.
  • The public TCP/HTTP API can forward requests to the correct owner node.
  • Internal cluster commands are processed without recursive forwarding.
  • Health checks run periodically and mark peers as HEALTHY, SUSPECTED, or UNAVAILABLE.
  • Gossip runs periodically and exchanges topology versions/fingerprints between peers.

Run Two Local Nodes

Open two terminals.

Terminal 1:

./gradlew bootJar
java -Dcache.config=config-node-a.yml -jar build/libs/distributed-cache-1.0-SNAPSHOT.jar

Terminal 2:

java -Dcache.config=config-node-b.yml -jar build/libs/distributed-cache-1.0-SNAPSHOT.jar

Node A:

  • HTTP: 8080
  • TCP: 2020
  • Cluster TCP: 10001

Node B:

  • HTTP: 8081
  • TCP: 2021
  • Cluster TCP: 10002

Docker

Build the image:

docker build -t distributed-cache .

Run with the default classpath config:

docker run --rm -p 8080:8080 -p 2020:2020 -p 10001:10001 distributed-cache

The Dockerfile uses:

  • eclipse-temurin:21-jdk for building
  • eclipse-temurin:21-jre for runtime
  • CACHE_CONFIG=config.yml as the default config file
  • JAVA_OPTS for additional JVM options

Example:

docker run --rm \
  -e CACHE_CONFIG=config-node-a.yml \
  -e JAVA_OPTS="-Xms256m -Xmx512m" \
  -p 8080:8080 \
  -p 2020:2020 \
  -p 10001:10001 \
  distributed-cache

Java TCP Client Support

The org.cache.client package contains a CacheClient abstraction and a TcpCacheClient implementation. The current TcpCacheClient constructors are package-private, so application code outside org.cache.client should either add a small factory/builder or use the lower-level RespCommandClient directly.

Low-level example:

RespCommandClient client = new RespCommandClient();

client.send("localhost", 2020, List.of("PUT", "1", "Ferid", "60000"));
List<String> value = client.send("localhost", 2020, List.of("GET", "1"));
client.send("localhost", 2020, List.of("DELETE", "1"));

Cache Semantics

  • PUT stores string values.
  • PUSH creates or updates list values.
  • Calling GET on a list key returns a wrong-type error.
  • Calling LRANGE on a string key returns a wrong-type error.
  • ttlMillis = 0 means the entry does not expire.
  • Expired entries are removed on read and by a scheduled cleanup task.
  • SIZE reports the current local node size.
  • CLEAR clears the local cache service.

Development Commands

Run tests:

./gradlew test

Run Checkstyle:

./gradlew checkstyleMain checkstyleTest

Build the boot jar:

./gradlew bootJar

Run the full verification task:

./gradlew check

License

This project is licensed under the MIT License. See LICENSE for details.