Open Source Distributed Coordination

Distributed Shared Memory for Enterprise Java Services

DSM gives service teams a runtime-first coordination layer for replicated registers, lease-backed ownership, and CRDT state. The documentation is organized for real integration work: start with a guide, keep the reference open, and use scenario cookbooks when you need a recommended pattern.

Registers, leases, and CRDTs in one runtime surface
SWIM-lite gossip, adaptive repair, and cross-cluster federation
HMAC signing, replay protection, and optional AEAD encryption
Spring Boot and standalone wiring built around the same API

Start Integration Open API Reference View on GitHub

Guide-first docsMove from getting started to Spring Boot or standalone integration without leaving the site.

Reference-readyRuntime API, collection builders, handle contracts, and Spring properties are documented directly.

Scenario cookbooksUse the routing, shard ownership, and distributed counter patterns as implementation templates.

Replicate routing hints, feature flags, and control-plane metadata with deterministic runtime registration and explicit collection boundaries.

Best for shared metadata
Explicit tenant/application/collection IDs
JDK-only runtime core

DsmRuntime runtime = DsmRuntimeBuilder.builder()
    .clusterId("prod-cluster")
    .serviceId("gateway-service")
    .membership(membership)
    .build();

runtime.register(CollectionSpecBuilder.<RouteHint>register(
        "shared",
        "gateway",
        "route-hints")
    .schemaId("route-hints/v1")
    .codec(new RouteHintCodec())
    .build());

Platform highlights

A runtime surface built for control-plane data, not platform sprawl.

DSM focuses on the problems enterprise teams actually have to solve: metadata replication, shard ownership, consistent routing, and observability that matches operational reality.

Multi-Model Collections

Registers, lease collections, and CRDT collections share one runtime contract so teams can choose the right consistency tier per workload.

Self-Healing Replication

SWIM-lite gossip with a SUSPECT stage, anti-entropy digests, snapshot streaming, and adaptive per-peer repair planning keep long-lived clusters converged.

Encrypted, Signed Channels

HMAC signing, replay protection, admission validation, and optional ChaCha20-Poly1305 / AES-256-GCM payload encryption protect replication without a heavyweight stack.

Isolated Clustering

Standalone, multicast, or unicast gossip membership over a Protobuf wire, with clusterId + serviceId isolation so mismatched traffic is dropped at the discovery layer.

Cross-Cluster Federation

The dsm-federation bridge forwards register, lease, and CRDT collections across clusters with anti-entropy repair for multi-region and multi-tenant topologies.

Built-In Observability

The DsmMetrics SPI plus the Micrometer adapter and W3C trace-context propagation wire DSM straight into Prometheus, Grafana, and OpenTelemetry pipelines.

Live cluster coordination

Watch the runtime gossip, repair, and converge.

Every node runs the same DSM runtime. Membership spreads through SWIM-lite gossip, anti-entropy digests reconcile drift, and the lease owner holds a fenced token while CRDT counters merge locally and converge across the cluster.

Members alive: 0
Gossip rounds: 0
CRDT merges: 0
Repair p99: 0ms

Enterprise workloads

Use DSM where coordination data matters more than raw storage volume.

DSM is a strong fit for routing metadata, ownership coordination, distributed counters, and service-local control-plane state that still needs multi-node replication.

Service Discovery & Routing

Replicate route hints and gateway metadata across nodes so request steering stays locally fast while updates propagate through the DSM runtime.

Matches the route-hints register example in the standalone runtime sample.

Leader Election & Sharding

Lease collections coordinate shard ownership with autonomous renewal and fencing-aware handoff for workers that need a single active owner.

Backed by the shard-owner lease example and the runtime lease diagnostics surface.

Configuration Distribution

Push lightweight operational configuration and feature state across a service family without turning the runtime into an application database.

Fits DSM register collections where tenant, application, and collection boundaries stay explicit.

Cluster-Wide Metrics Aggregation

Use CRDT collections for counters and convergent state so each node can update locally while the cluster repairs toward a consistent view.

Modeled on the request-counter CRDT example in the runtime sample factory.

From API to operations in three steps

Model the collection once, then keep the same runtime path through production.

DSM keeps collection modeling, runtime wiring, cluster sync, and operator-facing diagnostics aligned. The documentation follows the same sequence: guide first, reference second, operations and architecture when needed.

Define

Register collections through a runtime-first API where tenant, application, and collection IDs are explicit instead of hidden behind framework magic.

Collection definition

CollectionSpecBuilder.<RouteHint>register(
        "shared",
        "gateway",
        "route-hints")
    .schemaId("route-hints/v1")
    .codec(new RouteHintCodec())
    .build();

Deploy

Wire DSM directly or let the Spring Boot starter assemble the runtime, membership, and configured collection handles from application properties.

Spring Boot config

dsm:
  cluster-id: runtime-example
  service-id: gateway-service
  cluster:
    mode: unicast
  collections:
    - bean-name: routeHintsCollection
      tenant-id: shared
      application-id: gateway
      collection-id: route-hints
      type: REGISTER
      codec-bean: routeHintCodec

Operate

Read runtime snapshots, cluster membership state, lease-specific diagnostics, and metrics callbacks without bolting on a second observability model.

Diagnostics API

RuntimeDiagnostics diagnostics = runtime.diagnostics();

int totalEntries = diagnostics.totalEntries();
ClusterView clusterView = diagnostics.clusterView();
List<CollectionDiagnostics> collections = diagnostics.collections();
List<LeaseCollectionDiagnostics> leaseCollections = diagnostics.leaseCollections();

Start in minutes

Choose the integration path that matches your service boundary.

The same runtime contracts support direct Java wiring for embedded services and explicit Spring Boot configuration for platform-standard deployments. After the first setup, use the reference pages and scenario cookbooks as the day-to-day implementation manual.

Maven dependency

pom.xml

<dependency>
  <groupId>com.leanowtech.dsm</groupId>
  <artifactId>dsm-runtime</artifactId>
  <version>${dsm.version}</version>
</dependency>

Minimal runtime

Java runtime

DsmRuntime runtime = DsmRuntimeBuilder.builder()
    .clusterId("runtime-example")
    .serviceId("gateway-service")
    .membership(new StandaloneClusterMembership(self))
    .build();

runtime.start();

→ Read the full Getting Started guide

Runtime API Spring Properties Routing Cookbook Shard Ownership Cookbook

Module architecture

Composable modules instead of one monolithic coordination platform.

APIdsm-apiPublic contracts: runtime facade, collection handles, specs, conflict resolvers, change streams, and observability SPI.RUNdsm-runtimeDefault runtime, collection and spec builders, in-memory register/lease/CRDT collections, built-in CRDTs, and record codec.SYNCdsm-syncControl-plane and data-plane replication with digest, snapshot, replay repair, and adaptive per-peer repair planning.CLSTdsm-clusterStandalone, multicast, and unicast gossip membership over a Protobuf cluster wire with serviceId-based isolation.SECUdsm-securityHMAC signing, replay protection, admission validation, optional AEAD payload encryption, and sender rate-limiting.FEDdsm-federationCross-cluster bridge for register, lease, and CRDT tiers with anti-entropy repair between clusters.OBSdsm-metrics-micrometerMicrometer adapter for the DsmMetrics SPI, feeding Prometheus, Grafana, and OpenTelemetry pipelines.BOOTSpring Boot StarterAutoconfiguration, runtime lifecycle hooks, collection registration, and property binding around DsmRuntime.EXdsm-examplesRunnable standalone, Spring Boot, and interactive multi-node REPL examples that map to the integration guide.