How It Works — RSpond

Liquid Compute is a Spring Boot library that makes Java services flow where they’re needed. You write a normal Java interface, annotate it with @Liquid, and implement it as a Spring bean. The framework wraps the bean in a transparent proxy. At call time, the proxy reads a distributed routing table and decides whether to invoke locally or forward the call to another node — same return type, same exceptions, same trace context either way.

No sidecar. No separate control plane. No custom wire protocol. The framework runs inside the application process and uses standard JMS for transport and Hazelcast (or Kubernetes CRDs) for coordination.

The Four Pieces

Four cooperating components make a Liquid cluster work. Each is small, replaceable, and explicit.

01 · Proxy

In-JVM call interceptor

Every call to a @Liquid interface passes through a lightweight proxy embedded in the JVM. It reads the active layout, then routes accordingly:

Local — invoke the bean directly.
Remote — serialize arguments with Gson, send over JMS, deserialize the response. The caller never knows the difference.

02 · Brain

Pluggable scheduling strategy

The brain decides which nodes serve which services. It runs on an interval (or on demand) and proposes a new layout. Two strategies ship today — Random (rotates assignments) and Manual (operators toggle from the dashboard).

A separate mode setting is independent of strategy: AUTO executes proposals immediately, MANUAL waits for operator approval.

03 · Routing table

Distributed active layout

The active layout is a cluster-wide map: for every @Liquid service, which nodes are currently assigned. It lives in Hazelcast (or as Kubernetes CRDs under a control-plane operator) and is read by every proxy on every call.

Each layout has an epoch — a monotonically increasing number that appears in metrics, traces, and Grafana annotations so you can correlate performance with rebalancing.

04 · Transition protocol

Two-phase, stability-preserving moves

When the brain rebalances, the change decomposes into a sequence of individually-safe moves. Each move runs as DEACTIVATE → ACTIVATE: losing nodes finish in-flight requests and stand down, then gaining nodes start serving.

The stability invariant guarantees at least one replica of every service stays active throughout. No traffic blackouts during rebalancing.

The Developer's View (30 seconds)

Write an interface. Add @Liquid. Implement it as a Spring bean. Deploy multiple instances. Done.

      
      PricingService.java
    
@Liquid(version = "1.0.0")
public interface PricingService {
    Price calculatePrice(Order order);
}

@Component
public class PricingServiceImpl implements PricingService {

    public Price calculatePrice(Order order) {
        // Business logic — no awareness of distribution
        var basePrice = catalog.lookup(order.itemId());
        var discount = promotions.apply(order.customerId(), basePrice);
        return new Price(discount, order.currency());
    }
}

What the framework provides for free: transparent routing, JMS serialization, OpenTelemetry tracing across nodes, Micrometer metrics (invocations, CPU, latency, bandwidth), and a live dashboard — all without changes to PricingServiceImpl.

The Service Cascade

The reference demo runs three services that compose naturally — x³ = x · x². CubeService calls SquareService and MultiplyService; SquareService calls MultiplyService. This is a real 3-deep call chain that exercises cross-node routing, trace propagation, and per-method metrics.

          
          CubeService.java
        
@Liquid(version = "1.0.0")
public interface CubeService {
    int cube(int x);
}

@Service
public class CubeServiceImpl
    implements CubeService {

  private final SquareService sq;
  private final MultiplyService mul;

  public CubeServiceImpl(
      SquareService sq,
      MultiplyService mul) {
    this.sq = sq;
    this.mul = mul;
  }

  @Override
  public int cube(int x) {
    return mul.multiply(x, sq.square(x));
  }
}

          
          SquareService.java
        
@Liquid(version = "1.0.0")
public interface SquareService {
    int square(int x);
}

@Service
public class SquareServiceImpl
    implements SquareService {

  private final MultiplyService mul;

  public SquareServiceImpl(
      MultiplyService mul) {
    this.mul = mul;
  }

  @Override
  public int square(int x) {
    return mul.multiply(x, x);
  }
}

          
          MultiplyService.java
        
@Liquid(version = "1.0.0")
public interface MultiplyService {
    int multiply(int a, int b);
}

@Service
public class MultiplyServiceImpl
    implements MultiplyService {

  @Override
  public int multiply(int a, int b) {
    return a * b;
  }
}

The resulting call chain — with each arrow potentially crossing a node boundary:

cube(3)
  └─ multiply(3, square(3))
              └─ multiply(3, 3) → 9
       └─ multiply(3, 9) → 27

Every arrow that crosses a node is routed by the proxy, traced by OpenTelemetry with W3C Trace Context, and measured by Micrometer. The framework keeps the call surface identical — including exception semantics — so business code stays oblivious to the topology underneath.

How Rebalancing Works

A layout change is not a flag flip. The brain produces a plan — an ordered list of moves — and each move executes in two phases. Operators can run plans all at once, step through one move at a time, regenerate, or stop mid-plan.

Phase 1 · DEACTIVATE

Losing nodes stand down

Nodes losing a service stop accepting new traffic for it, finish in-flight requests, and confirm completion. All losing nodes finish deactivating before any gaining node activates.

Phase 2 · ACTIVATE

Gaining nodes take over

Nodes gaining a service open up to traffic and announce activation. The routing table is published with a new epoch; every proxy in the cluster picks it up on the next call.

Stability
Invariant

At least one replica of every service stays active through the entire transition. Big rearrangements decompose into a chess game of individually-safe moves — the brain never produces a step that violates the invariant, so services never go down during rebalancing.

Large method results travel via a claim-check pattern: the responding node stores the payload and sends a small reference; the caller fetches it directly. The JMS broker stays fast regardless of payload size.

What You See on the Dashboard

A real-time web dashboard ships with the framework and is served by any node in the cluster. No separate deployment, no extra container.

Liquid Compute dashboard showing a 3-node cluster with services and RPS charts

Cluster Layout. A 3-node cluster with services pinned to nodes, per-node RPS, and toggle controls (when the brain is in MANUAL mode). Every move you make appears as a new layout epoch.

Liquid Compute service topology showing the Cube to Square to Multiply call graph

Service Topology. The Cube → Square → Multiply call graph across nodes, with invocation counts and latency on every edge. This is the actual demo cascade running live — not a mock.

Raw per-method metrics table showing invocations CPU and latency

Raw Metrics. Per-method invocation counts, CPU time, and latency tables — sortable, filterable, and exportable for ad-hoc analysis.

Cluster LayoutService-to-node assignments with manual-mode toggles.
Service TopologyLive method-to-method call graph with edge weights.
Performance ChartsReal-time RPS and average chain latency, per node and cluster-wide.
Brain ControlsStrategy selector, mode toggle, proposal approval, plan stepping.
Move HistoryEvery move with timestamp, epoch, and outcome — an audit trail of the cluster's life.

End-to-End Observability

Every proxied call produces a Micrometer timer (tagged by service, method, node, and layout epoch) and an OpenTelemetry span. Metrics flow to Prometheus; traces flow to Tempo or any OTLP-compatible collector. Layout epochs appear as Grafana annotations — performance changes line up exactly with rebalancing events.

Grafana dashboard showing invocations transport latency and bandwidth panels

Grafana metrics. Invocations, transport breakdown, latency percentiles, and bandwidth in one view. Layout-epoch annotations let you correlate every dip and spike with a specific move.

Grafana Tempo distributed trace showing a multi-node call chain

Distributed traces. A single request followed across the Cube → Square → Multiply cascade, with timing for each hop including JMS transport and claim-check fetches.

Built With

Liquid Compute composes standard open-source components rather than inventing them. There is no proprietary wire format, no special protocol, no custom storage layer.

Core Framework

Java 21 LTS
Spring Boot 3.4.4
Apache Artemis 2.31.2
Hazelcast 5.3.6
Gson

Observability

Micrometer
Prometheus
Grafana
OpenTelemetry SDK
Grafana Tempo

Kubernetes (optional)

JOSDK operator
Custom CRDs
k3d (local)
Maven
JUnit 5

No sidecar Runs inside the application process. No extra container to manage, patch, or pay for.

No custom protocol Standard JMS for transport, standard Hazelcast or K8s CRDs for coordination.

No control plane The brain runs inside the application. Nothing extra to deploy, monitor, or scale.

How Liquid Compute Works

The Four Pieces

In-JVM call interceptor

Pluggable scheduling strategy

Distributed active layout

Two-phase, stability-preserving moves

The Developer's View (30 seconds)

The Service Cascade

How Rebalancing Works

Losing nodes stand down

Gaining nodes take over

What You See on the Dashboard

End-to-End Observability

Built With

Core Framework

Observability

Kubernetes (optional)

See it in motion