Aeron Cache

A key value store with counters built using Aeron, Agrona and SBE. RAFT clustered or single node - fast by design. UI with NextJS, Shadcn and Tailwind. Includes HTTP, WS, SSE and Aeron transport (UDP and IPC) interfaces.

Deployable on Kubernetes with helm or locally with brew.

• Features
• How To Run - Brew
• How To Run - K8s/Helm
• API Specs
• Demo Videos

Features

• Key-value and counter caches with item level TTL support

• Bulk atomic operations across caches and counters

• Streaming multi-cache (and key) subscriptions

• PATCH support for writing partial updates to JSON values including partial streaming subscriptions (JSON Merge Patch RFC 7386)

• Near cache implementation - support for hydrating and keyed subscriptions as well as synthetic PATCH generation

• HTTP (Request-Response), WS (UniDi and BiDi), SSE (UniDi) and SBE-Aeron (BiDi) APIs

• Embedded cache polyglot clients:

  • Aeron Transport (BIDI) - Java and Rust
  • HTTP and WS - Java, Rust, Typescript and Python

• Rust based CLI

How To Run

Brew

brew tap bhf/aeroncache
brew install aeron-cache
aeron-cache

You should see something like:

Initializing Aeron Cache...

    ___    __________  ____  _   __   _________   ________  _________
   /   |  / ____/ __ \/ __ \/ | / /  / ____/   | / ____/ / / / ____/
  / /| | / __/ / /_/ / / / /  |/ /  / /   / /| |/ /   / /_/ / __/   
 / ___ |/ /___/ _, _/ /_/ / /|  /  / /___/ ___ / /___/ __  / /___   
/_/  |_/_____/_/ |_|\____/_/ |_/   \____/_/  |_\____/_/ /_/_____/   

              🌲 https://github.com/bhf/aeron-cache 🌲

✅ Aeron Cache is running!
   UI      : http://localhost:3000
   Backend : PID 6221
   Config  : /home/user1/.aeron-cache
   Log     : /home/user1/.aeron-cache/aeron-cache.log

Press Ctrl+C to stop.

Configuring the monolith

The brew install runs the monolith (cluster node plus the interfaces below) and the UI. On first run a default config is written to ~/.aeron-cache/backend.env

Interface	Variable	Default
HTTP (REST) and cluster tools	always on	enabled
WebSocket gateway	WEBSOCKET_GATEWAY_ENABLED	true
SSE gateway	SSE_GATEWAY_ENABLED	true
Aeron (SBE) gateway	AERON_GATEWAY_ENABLED	false

Other options:

Variable	Default	Description
GATEWAY_TRANSPORT_MEDIA	udp	Aeron gateway transport, udp or ipc (only used when the Aeron gateway is enabled)
MONOLITH_EMBEDDED_DRIVER	true	true launches an embedded media driver; false attaches to an external aeronmd already running at AERON_DIR
DYNAMIC_CACHE_CREATION	false	Allow caches to be created dynamically
CACHE_MODE	RAFT	Cache mode (set in the generated config)

For example, to enable the Aeron gateway over IPC and disable SSE, add to ~/.aeron-cache/backend.env:

AERON_GATEWAY_ENABLED=true
GATEWAY_TRANSPORT_MEDIA=ipc
SSE_GATEWAY_ENABLED=false

A disabled gateway is not started, so the matching UI streaming features (WebSocket/SSE) will not connect.

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

All targets below are run from k8s/helm/. Each install-* target has a matching uninstall-*.

make install-backend              # backend only
make install-frontend             # frontend (UI) only
make install-backend-ephemeral    # ephemeral backend only
make install-all-ephemeral        # ephemeral backend + UI
make uninstall-all                # tear down

Individual components can also be installed on their own, e.g. make install-http or make install-ui.

External media driver

Pass EXTERNAL_MEDIA_DRIVER=true to any install target to run the Aeron C media driver (aeronmd) as a sidecar.

Build the driver image with make build-media-driver (part of make build-backend).

make install-all EXTERNAL_MEDIA_DRIVER=true
make install-backend EXTERNAL_MEDIA_DRIVER=true
make install-backend-ephemeral EXTERNAL_MEDIA_DRIVER=true

Using images from GHCR

By default the charts use images built into Minikube. Pass GHCR=true to pull the released images from ghcr.io instead (no local build needed).

make install-all GHCR=true
make install-backend-ephemeral GHCR=true EXTERNAL_MEDIA_DRIVER=true
make install-all GHCR=true GHCR_TAG=1.2.3          # a specific release

Observability (Prometheus + Grafana)

Deploy an in-cluster Prometheus + Grafana stack with make install-observability. It installs into the aeroncache namespace alongside the apps and ships a pre-provisioned "Aeron Cache - Interface Apps" Grafana dashboard (JVM memory/CPU/GC and HTTP request rate/latency).

Metrics come from the OpenTelemetry Java agent, which is optional and off by default. Pass JAVAAGENT=true to any interface-app install target to activate the agent (baked into the HTTP, WS, SSE and near-cache images) so it serves a Prometheus endpoint; Prometheus auto-discovers the instrumented pods via annotations. Without JAVAAGENT=true the apps run uninstrumented and expose no metrics.

make install-observability                  # Prometheus + Grafana
make install-backend JAVAAGENT=true         # apps with the agent on

Top

API Specs

• REST OpenAPI
• Streaming Websocket OpenAPI
• Streaming SSE OpenAPI
• BiDi Websocket OpenAPI
• BiDi Aeron Transport Gateway SBE

Top