Spring Properties Reference

This page documents the current dsm.* Spring Boot configuration surface. It is organized to match DsmProperties in dsm-spring-boot-autoconfigure.

Use the Spring Boot guide for the integration sequence. Use this page when you need exact property names, defaults, and validation boundaries.

Root Properties

Property	Default	Required	Notes
dsm.cluster-id	none	yes	Logical DSM cluster boundary. Nodes with different cluster IDs must not share runtime traffic.
dsm.service-id	none	yes	Service-family boundary inside a cluster. Peers for one service should share this value.

Node Properties

Property	Default	Required	Notes
dsm.node.id	random UUID	no	Set explicitly in production so diagnostics and lease ownership are stable across restarts when that is desired.
dsm.node.host	resolved local host address	no	Must be reachable by peers in real multi-node deployments.
dsm.node.port	9090	no	Local DSM node port used by the selected membership/runtime wiring.

Runtime Properties

Property	Default	Required	Notes
dsm.runtime.dynamic-registration	false	no	Allows collection registration after runtime construction. Prefer false for predictable production bootstrap.
dsm.runtime.eviction-scan-interval	60s	no	How often the default runtime scans registered collections with non-empty eviction policies.

Cluster Properties

Property	Default	Required	Notes
dsm.cluster.mode	STANDALONE	no	Allowed values: STANDALONE, MULTICAST, UNICAST.

Multicast

Property	Default	Required	Notes
dsm.cluster.multicast.group	239.0.77.1	no	Multicast group for trusted LAN/VPC discovery.
dsm.cluster.multicast.port	4446	no	Multicast discovery port.
dsm.cluster.multicast.heartbeat-interval	1s	no	Heartbeat interval used by multicast membership.
dsm.cluster.multicast.failure-threshold	5	no	Missed heartbeat threshold before peer failure handling.

Unicast Gossip

Property	Default	Required	Notes
dsm.cluster.unicast.gossip-port	4447	no	Gossip transport port.
dsm.cluster.unicast.gossip-interval	1s	no	Interval between gossip rounds.
dsm.cluster.unicast.gossip-fanout	3	no	Number of peers contacted per gossip round.
dsm.cluster.unicast.failure-threshold	5	no	Base failure detection threshold.
dsm.cluster.unicast.suspicion-enabled	true	no	Enables SWIM-style SUSPECT before confirmed failure.
dsm.cluster.unicast.suspicion-quorum	3	no	Independent reporters needed to confirm suspicion. Must be positive.
dsm.cluster.unicast.suspicion-timeout	derived	no	Defaults to gossip-interval * failure-threshold * 2; must be positive when set.
dsm.cluster.unicast.seed-nodes	empty list	no	Static seed nodes, usually host:port.
dsm.cluster.unicast.dns.hostname	none	no	DNS seed hostname, commonly a Kubernetes headless service.
dsm.cluster.unicast.dns.port	9090	no	Port used for DNS-discovered seed nodes.

Sync Properties

Delta Coalescing

Property	Default	Required	Notes
dsm.sync.delta-coalescing.enabled	false	no	Enables short-window batching of outbound deltas.
dsm.sync.delta-coalescing.window-duration	10ms	no	Coalescing window. Keep this small; it trades latency for fewer messages.
dsm.sync.delta-coalescing.max-batch-size	64	no	Maximum number of deltas in one batch.

Proactive Anti-Entropy

Property	Default	Required	Notes
dsm.sync.anti-entropy.sweep-enabled	true	no	Starts background data-plane repair sweeps. Disable only for tightly controlled tests.
dsm.sync.anti-entropy.sweep-interval	30s	no	Interval between sweep rounds.
dsm.sync.anti-entropy.max-concurrent-repairs	2	no	Maximum repair attempts initiated in one sweep round.

Observability Properties

Property	Default	Required	Notes
dsm.observability.trace-context.enabled	false	no	Enables inbound HTTP trace-context extraction in Spring wiring so DSM can inject W3C trace context into outbound platform envelopes.

Security Properties

Property	Default	Required	Notes
dsm.security.enabled	false	no	Enables secure envelope signing, replay protection, and admission controls.
dsm.security.cluster-secret	none	when security enabled	Shared secret material. Prefer environment-backed secret injection.
dsm.security.per-node-key-derivation	false	no	Derives per-node keys from cluster secret material when enabled.
dsm.security.min-acceptable-key-version	1	no	Rejects envelopes below this signing key version to prevent downgrade.
dsm.security.challenge-interval	5m	no	Interval for cluster re-authentication challenge behavior.

Nonce Replay Protection

Property	Default	Required	Notes
dsm.security.nonce.window-size	1024	no	Accepted replay window retained per sender.
dsm.security.nonce.max-clock-drift	5s	no	Maximum tolerated timestamp drift for replay validation.
dsm.security.nonce.max-tracked-senders	1600	no	Maximum sender replay windows retained before LRU eviction. Spring validates 100..10000.

Sender Rate Limiting

Property	Default	Required	Notes
dsm.security.rate-limit.max-consecutive-failures	10	no	Consecutive verification failures required before a sender is temporarily banned.
dsm.security.rate-limit.ban-duration	30s	no	Duration of a temporary sender ban.

Payload Encryption

Property	Default	Required	Notes
dsm.security.encryption.enabled	false	no	Enables secure-envelope payload encryption. Nodes requiring encryption reject plaintext inbound envelopes before HMAC verification.
dsm.security.encryption.algorithm	ChaCha20-Poly1305	no	Built-in options include ChaCha20-Poly1305 and AES-256-GCM.
dsm.security.encryption.key-derivation-salt	dsm-encryption	no	HKDF salt used to derive payload encryption keys from cluster secret material.

Collection Definitions

Collections are configured as list items under dsm.collections.

Common Fields

Field	Default	Required	Notes
bean-name	none	no	Explicit Spring bean alias. Must be unique when supplied.
tenant-id	none	yes	First part of the collection locator.
application-id	none	yes	Second part of the collection locator.
collection-id	none	yes	Third part of the collection locator.
schema-id	none	yes	Logical payload compatibility identifier. Change when semantics are not safely compatible.
type	REGISTER	no	Allowed values: REGISTER, LEASE, CRDT.
consistency-tier	REGISTER	conditionally	Must match the collection type in practice.
entity-type	none	conditionally	Fully qualified entity class used for RecordCodec derivation when codec-bean is omitted.
codec-bean	none	conditionally	Explicit entity codec bean. Required unless entity-type can derive a record codec.
qos-profile	type default	no	Built-in values: best-effort-meta, control-critical, standard.
replication-profile	type default	no	Built-in values: embedded-register, embedded-lease, embedded-crdt.
persistence-profile	type default	no	Built-in values: ephemeral, local-durable.

Type And Tier Rules

Collection type	Required consistency-tier	Default QoS	Default replication	Default persistence
REGISTER	REGISTER	best-effort-meta	embedded-register	ephemeral
LEASE	LEASE	control-critical	embedded-lease	local-durable
CRDT	CRDT	standard	embedded-crdt	local-durable

Lease Fields

Nested under dsm.collections[].lease.

Field	Default	Required	Notes
mode	AUTONOMOUS	no	AUTONOMOUS allows local lease decisions; QUORUM gates acquire, renew, and transfer on stable majority visibility.
quorum-stability-rounds	3	for QUORUM tuning	Stable membership rounds required before QUORUM lease mutations are allowed. Must be at least 1.
term	10s	no	Lease term. Must be positive.
renew-skew	3s	no	Renewal window. Must be positive and smaller than term.
expiry-grace	500ms	no	Extra grace after term expiry. Must be positive.
entity-factory-bean	none	yes for lease	Factory used to create blank lease entities by entry key.

CRDT Fields

Nested under dsm.collections[].crdt.

Field	Default	Required	Notes
state-codec-bean	none	yes for CRDT	Codec for CRDT state snapshots.
initial-state-bean	none	yes for CRDT	Initial state supplier/bean used at collection creation.
merger-bean	none	yes for CRDT	State merger used to converge local and remote updates.

Bean Naming Rules

Every configured collection handle receives a stable bean name:

dsmCollection:<tenant>/<application>/<collection>

If bean-name is set, that value is registered as an alias in addition to the stable name.

Startup Failure Conditions

Spring startup fails fast when:

• required root properties are blank
• a collection is missing locator or schema fields
• neither codec-bean nor derivable entity-type is available
• a referenced supporting bean does not exist
• two collections use the same locator
• two collections reuse the same explicit bean-name
• collection type and consistency tier do not match
• lease timing values are non-positive
• renew-skew >= term
• quorum-stability-rounds < 1
• dsm.security.nonce.max-tracked-senders is outside 100..10000

Minimal 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

Secure Production Example

dsm:
  cluster-id: prod-eu-west
  service-id: gateway-service
  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
  observability:
    trace-context:
      enabled: true
  security:
    enabled: true
    cluster-secret: ${DSM_CLUSTER_SECRET}
    min-acceptable-key-version: 1
    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
      key-derivation-salt: ${DSM_ENCRYPTION_SALT}

Related Pages

• Spring Boot
• Collection Specs
• Security Model
• Observability