Aeron Cache

Written and designed without LLMs or AI Agents.

A key value store built using Aeron, Agrona and SBE. RAFT clustered and fast by default. UI with NextJS, Shadcn and Tailwind. Includes HTTP, WS and SSE interfaces with support for multi-cache joins over WS and SSE. Prometheus+cAdvisor and tracing with Jaeger+OTEL. Containerized and deployable with docker compose or on Kubernetes via helm or kubectl.

Features:

• Clustered and single node modes
• Near cache implementation (read ahead)
• Embedded cache polyglot clients in Java, Rust, Typescript and Python
• Rust based CLI
• An MCP server to power your Agentic AI and LLM workflows

Basic-Demo.webm.mov

Streaming-Demo.webm.mov

• How To Run - Docker
• How To Run - K8s/Helm
• Multi-cache Subscriptions
• Project Structure
• Overview
• Testing
• Roadmap

How To Run

Docker

git clone https://github.com/bhf/aeron-cache
cd aeron-cache/
./gradlew build
docker compose build
docker compose up

You should see something like this once the UI is ready:

cache-ws-client-1       | Starting Websocket interface
cache-http-client-1     | Starting HTTP interface
cache-ui-1              |    ▲ Next.js 15.2.3
cache-ui-1              |    - Local:        http://localhost:3000
cache-ui-1              |    - Network:      http://0.0.0.0:3000
cache-ui-1              | 
cache-ui-1              |  ✓ Starting...

You can also spin up a single node cache by using docker-compose-nonclustered.yaml

Top

K8s and Helm

The Makefile is setup to push images to Minikube.

git clone https://github.com/bhf/aeron-cache
cd aeron-cache/
make all
cd k8s/helm/
make install-all

Top

Subscribe to Multiple Caches

To subscribe to cache updates on caches with IDs 808 and 333:

uwsc http://localhost:7071/api/ws/v1/caches/808,333

You can also do this over SSE:

http://localhost:7072/api/sse/v1/caches/808,333

Top

Structure

cache-client - An Aeron cluster based client for the cache.

cache-cluster - The core cache cluster service.

cache-common - Common entities and classes used in cache implementations.

cache-http - REST interfaces around the cache-client.

cache-mcp - MCP interface using the Swagger spec with AutoMCP.

cache-ws - Websocket interfaces around the cache-client.

cache-sse - SSE interfaces around the cache-client.

cache-messages-sbe - Core SBE messages used by the cache.

cache-messages-http - Messages used by HTTP interfaces to the cache.

cache-near - Near cache implementation with a HTTP interface.

cache-ui - A UI that uses the REST API provided by cache-http-server

k8s - Helm charts and other K8s resources (work in progress)

hyperfoil - Some basic hyperfoil tests

Top

Overview

Message Flow Overview

Cluster Service Workflow

Client Flow

Top

Testing

Unit Tests

There are a number of unit tests (including some param variation) using JUnit and Mockito across both cache-cluster and cache-client which exercise the main functionality.

Core coverage > 70% (as of 4th July 2025)

JMH

There are a handful of JMH tests in cache-cluster and in cache-client.

HTTP API

There are approx 20 HTTP based integration tests (including param variation) using JUnit and RestAssured in :cache-http:http-integration-tests which cover the main functionality offered by the HTTP API.

Top

Future Work

• Industrialization and cache-ops

https://sanjdev.atlassian.net/jira/software/projects/AC/boards/22

Top