Spring Boot

This guide is the supported Spring Boot integration path for DSM. Use it when you want runtime creation, collection registration, and lifecycle management driven by configuration and beans instead of manual bootstrap code.

What The Starter Does

The starter builds a DsmRuntime from dsm.* properties, validates collection definitions, registers configured collections, starts lifecycle management, and exposes collection handles as beans.

For most teams, that means:

1. declare the starter dependency
2. provide supporting codec and factory beans
3. describe collections in application.yml
4. inject typed collection handles into your service beans

Add The Starter

<dependency>
  <groupId>com.leanowtech.dsm</groupId>
  <artifactId>dsm-spring-boot-starter</artifactId>
  <version>${dsm.version}</version>
</dependency>

Required High-Level Properties

These two properties are required for every Spring Boot integration:

• dsm.cluster-id
• dsm.service-id

They define the DSM isolation boundary and service-family identity. Keep them stable across nodes that should belong to the same logical DSM deployment.

Supporting Beans By Collection Type

Register Collections

Provide either:

• DsmEntityCodec<E> referenced by codec-bean
• entity-type for Java record entities so the starter can derive RecordCodec

Lease Collections

Required beans:

• DsmEntityCodec<E> referenced by codec-bean, or entity-type for record-codec derivation
• Function<String, E> referenced by lease.entity-factory-bean

Lease mode can be AUTONOMOUS or QUORUM. QUORUM mode uses lease.quorum-stability-rounds to wait for stable membership before local acquire, renew, and transfer attempts are allowed.

CRDT Collections

Required beans:

• DsmEntityCodec<E> referenced by codec-bean
• MergeableStateCodec<S> referenced by crdt.state-codec-bean
• initial state bean referenced by crdt.initial-state-bean
• StateMerger<E, S> referenced by crdt.merger-bean

Minimal Configuration Example

dsm:
  cluster-id: runtime-example
  service-id: gateway-service
  cluster:
    mode: STANDALONE
  collections:
    - bean-name: routeHintsCollection
      tenant-id: shared
      application-id: gateway
      collection-id: route-hints
      schema-id: route-hints/v1
      type: REGISTER
      consistency-tier: REGISTER
      entity-type: com.example.RouteHint

Mixed Register, Lease, And CRDT Example

dsm:
  cluster-id: runtime-example
  service-id: gateway-service
  runtime:
    dynamic-registration: false
  cluster:
    mode: UNICAST
    unicast:
      gossip-port: 4447
      gossip-interval: 1s
      gossip-fanout: 3
      failure-threshold: 5
      suspicion-enabled: true
      suspicion-quorum: 3
      seed-nodes:
        - 10.0.0.11:4447
        - 10.0.0.12:4447
  sync:
    anti-entropy:
      sweep-enabled: true
      sweep-interval: 30s
      max-concurrent-repairs: 2
  security:
    enabled: true
    cluster-secret: ${DSM_CLUSTER_SECRET}
    nonce:
      window-size: 1024
      max-clock-drift: 5s
      max-tracked-senders: 1600
    rate-limit:
      max-consecutive-failures: 10
      ban-duration: 30s
    encryption:
      enabled: true
      algorithm: ChaCha20-Poly1305
  collections:
    - bean-name: routeHintsCollection
      tenant-id: shared
      application-id: gateway
      collection-id: route-hints
      schema-id: route-hints/v1
      type: REGISTER
      consistency-tier: REGISTER
      entity-type: com.example.RouteHint

    - bean-name: shardOwnersCollection
      tenant-id: shared
      application-id: worker
      collection-id: shard-owner
      schema-id: shard-owner/v1
      type: LEASE
      consistency-tier: LEASE
      codec-bean: shardOwnerCodec
      lease:
        mode: AUTONOMOUS
        quorum-stability-rounds: 3
        term: 10s
        renew-skew: 3s
        expiry-grace: 500ms
        entity-factory-bean: shardOwnerEntityFactory

    - bean-name: requestCounterCollection
      tenant-id: shared
      application-id: billing
      collection-id: request-counter
      schema-id: request-counter/v1
      type: CRDT
      consistency-tier: CRDT
      codec-bean: requestCounterCodec
      crdt:
        state-codec-bean: requestCounterStateCodec
        initial-state-bean: requestCounterInitialState
        merger-bean: requestCounterMerger

Property Validation Rules That Matter

The Spring integration validates collection definitions before runtime assembly. The most important rules are:

• every collection must set tenant-id, application-id, collection-id, schema-id, and codec-bean
• every collection locator must be unique
• bean-name, when present, must be unique
• every collection must provide either codec-bean or derivable entity-type
• register collections must declare consistency-tier: REGISTER
• lease collections must declare consistency-tier: LEASE
• CRDT collections must declare consistency-tier: CRDT
• lease renew-skew must be smaller than term
• QUORUM lease quorum-stability-rounds must be at least 1
• dsm.security.nonce.max-tracked-senders must be within the Spring-validated range
• referenced supporting beans must exist

Cluster Modes

Mode	Property	Best fit
Standalone	dsm.cluster.mode=STANDALONE	local development, demos, single-node experiments
Multicast	dsm.cluster.mode=MULTICAST	trusted LAN or VPC environments where multicast is available
Unicast	dsm.cluster.mode=UNICAST	Kubernetes and cloud deployments

Node Properties

• dsm.node.id default: random UUID
• dsm.node.host default: resolved local host address
• dsm.node.port default: 9090

Multicast Properties

• dsm.cluster.multicast.group default: 239.0.77.1
• dsm.cluster.multicast.port default: 4446
• dsm.cluster.multicast.heartbeat-interval default: 1s
• dsm.cluster.multicast.failure-threshold default: 5

Unicast Properties

• dsm.cluster.unicast.gossip-port default: 4447
• dsm.cluster.unicast.gossip-interval default: 1s
• dsm.cluster.unicast.gossip-fanout default: 3
• dsm.cluster.unicast.failure-threshold default: 5
• dsm.cluster.unicast.suspicion-enabled default: true
• dsm.cluster.unicast.suspicion-quorum default: 3
• dsm.cluster.unicast.suspicion-timeout default: derived
• dsm.cluster.unicast.seed-nodes default: empty list
• dsm.cluster.unicast.dns.hostname optional
• dsm.cluster.unicast.dns.port default: 9090

Production Runtime Knobs

Area	Key properties
anti-entropy repair	dsm.sync.anti-entropy.sweep-enabled, sweep-interval, max-concurrent-repairs
trace context	dsm.observability.trace-context.enabled
sender replay bounds	dsm.security.nonce.window-size, max-clock-drift, max-tracked-senders
sender ban	dsm.security.rate-limit.max-consecutive-failures, ban-duration
payload encryption	dsm.security.encryption.enabled, algorithm, key-derivation-salt

Collection Bean Naming And Injection

Each configured collection handle is exposed as a Spring bean.

Naming rules:

• if bean-name is set, it becomes an alias you can inject by name or qualifier
• a stable bean name is always registered as dsmCollection:<tenant>/<application>/<collection>

Example injection by explicit alias:

@Service
public class RouteHintService {

    private final DsmRegister<RouteHint> routeHints;

    public RouteHintService(@Qualifier("routeHintsCollection") DsmRegister<RouteHint> routeHints) {
        this.routeHints = routeHints;
    }
}

Runtime Customization Hooks

If you need to customize the builder before the runtime is built, provide a DsmRuntimeBuilderCustomizer bean.

This is the right place for advanced setup such as a custom collection store, custom registry, or clock override.

CollectionLifecycleListener beans and CollectionInterceptor<?> beans are also auto-discovered and applied to the runtime. Use lifecycle listeners for registration/freeze/unregister observation, and interceptors for audit or operation metrics around collection calls.

What Gets Auto-Configured

The Spring path creates or exposes these core beans:

• NodeInfo
• ClusterMembership
• DsmRuntime
• DsmCollectionRegistry
• DsmRuntimeLifecycle
• DsmRuntimeRegistrationReporter
• DsmMetrics

When To Use The Reference Pages

Use the Spring guide for the integration sequence. Use the reference pages when you need exact field-level detail.

• Spring Properties
• Collection Specs
• Collection Handles