Getting Started

Cluster Bootstrap Sequence

From cold start to accepting writes in seconds.

Starting Nodes

node-1:5701

FOLLOWER

node-2:5702

FOLLOWER

node-3:5703

FOLLOWER

Prerequisites

• Java 25+ for the server (--enable-preview is required for preview APIs such as ScopedValue).
• Java 17+ is enough for the client SDK.
• The checked-in Maven wrapper (./mvnw), which verifies Maven before running.

java --version     # expect 25 or higher on the server

Build

git clone https://github.com/Loom-Cache/loom-cache.git
cd loom-cache
MVN_LOCAL_FORKS="-Dut.forkCount=2 -Dut.threadCount=1 -Dit.forkCount=2 -Dit.threadCount=1"
./mvnw clean verify $MVN_LOCAL_FORKS

The checked-in .mvn/maven.config defaults to 4 Maven forks and 2 test worker threads, so keep the lower override above on resource-constrained workstations. Run one Maven clean/test/verify command per checkout at a time; use separate worktrees for parallel agents or parallel evidence lanes.

Add the Client SDK

For published tagged releases, applications that connect to an existing cluster depend on loom-client from Maven Central. Before a release is cut, install from the source checkout into your local Maven repository and set loomcache.version to that local project version:

<dependency>
  <groupId>com.loomcache</groupId>
  <artifactId>loom-client</artifactId>
  <version>${loomcache.version}</version>
</dependency>

implementation("com.loomcache:loom-client:$loomcacheVersion")

Spring Boot applications can use the REST/autoconfiguration module:

<dependency>
  <groupId>com.loomcache</groupId>
  <artifactId>loom-spring-boot</artifactId>
  <version>${loomcache.version}</version>
</dependency>

Modules:

Module	Purpose
loom-common	Shared protocol contracts, configuration, exceptions, and Kryo serialization.
loom-server	TCP server, Raft, data structures, WAL, snapshots, CP subsystem, Chaos harness.
loom-client	Client SDK: smart routing, near cache, pooling, retry.
loom-cli	HTTP admin CLI plus local Raft log export tooling.
loom-spring-boot	Spring Boot 4.1.0 auto-configuration + REST controllers.
loom-integration-tests	Multi-node IT suite, including chaos-tagged cluster suites.

Server-only verification: ./mvnw -pl loom-server,loom-common -am clean test.

Path 1 — Embedded, single JVM

The simplest way to try LoomCache: spin up an in-process standalone node and use its data structures directly. In standalone() mode the embedded node exposes the server-side structures through getMap / getQueue / getSet / getTopic; in clustered mode that direct access is rejected and you connect with a LoomClient instead (see Path 2).

System.setProperty("loomcache.profile", "development");

EmbeddedLoomCache cache = EmbeddedLoomCache.builder()
    .nodeId("embedded-1")
    .dataDir("/absolute/path/embedded-data")     // dataDir must be an absolute path
    .standalone()                                 // required for direct data-structure access
    .build();
cache.start();

var map = cache.getMap("users");
map.put("alice", "Alice");
System.out.println(map.get("alice"));

cache.shutdown();                                 // or cache.close() — EmbeddedLoomCache is AutoCloseable

Builder options include nodeId, clusterName, port (default 5701), host(...), dataDir, allowedDataRoots(...), standalone(), joinCluster(...), enablePersistence(boolean), maxMapEntries, evictionPolicy, maxMemoryBytes, readBackupData(...). readBackupData(...) enables stale backup reads for standalone/non-production diagnostics only; production profiles reject stale backup reads. (enableRest(int) exists but the embedded REST surface is disabled — any positive port throws.)

Path 2 — 3-node Docker cluster

docker compose up -d
docker compose ps
docker compose port loomcache-node1 7654
docker compose port loomcache-node2 7654
docker compose port loomcache-node3 7654

Compose assigns loopback host ports dynamically so parallel local clusters do not collide. Use docker compose port to discover the host ports:

Service	Cluster → host	Spring REST/Actuator → host
loomcache-node1	docker compose port loomcache-node1 7654	docker compose port loomcache-node1 8080
loomcache-node2	docker compose port loomcache-node2 7654	docker compose port loomcache-node2 8080
loomcache-node3	docker compose port loomcache-node3 7654	docker compose port loomcache-node3 8080

The sample containers expose the binary member port on 7654 and the Spring Boot REST/Actuator port on 8080 (Prometheus metrics are served under /actuator/prometheus). See Deployment (Docker) for production layouts.

For a source-checkout Spring Boot smoke cluster, scripts/start-cluster.sh loads the node1, node2, and node3 profiles from config/local-cluster. Those profiles are local-development only and are intentionally not packaged in the Spring Boot jar.

Connect a client

LoomClient client = LoomClient.builder()
    .addSeed("localhost:<node1-cluster-port>")
    .addSeed("localhost:<node2-cluster-port>")
    .addSeed("localhost:<node3-cluster-port>")
    .requestTimeout(Duration.ofSeconds(15))
    .maxRetries(3)
    .build();
client.connect();

First operations

LoomMap<String, String> users = client.getMap("users");
users.put("alice", "Alice");

LoomQueue<String> tasks = client.getQueue("tasks");
tasks.offer("send-welcome-email");

LoomAtomicLong counter = client.consistencySubsystem().getAtomicLong("hits");
counter.incrementAndGet();

LoomTopic<String> events = client.getTopic("events", String.class);
int sub = events.subscribe(m -> System.out.println("got: " + m));
events.publish("hello");
events.unsubscribe(sub);

client.close();

Spring Boot (optional)

loomcache:
  cluster:
    seeds: [127.0.0.1:5701]
  client:
    enabled: true
    connect-timeout-ms: 5000
    request-timeout-ms: 120000

Seeds are binary member endpoints. The standalone defaults reserve 5702 and 5703 for direct admin health listeners, so add them as seeds only if you configured nodes to listen for member traffic on those ports.

The auto-configuration registers a LoomCache client bean (wrapping the underlying LoomClient) when loomcache.client.enabled=true. Setting loomcache.server.enabled=true runs an embedded LoomCache server; in embedded-server mode the client bean is still opt-in with loomcache.client.enabled=true.

Next

• Architecture overview — modules and request flow.
• Configuration reference — every property.
• Client API — the full client surface.
• Spring Boot integration — auto-configuration details.