Configuration Reference

Configuration flows through three immutable classes — ClusterConfig, TlsConfig, AuthConfig — plus the Spring Boot loomcache.* binding declared in LoomProperties.

Configuration Sources

45+ properties across 12 groups. Three ways to configure.

Builder APIapplication.ymlEnvironment

J

Builder API

LoomConfig.builder()

.nodeId("node-1")

.port(5701)

.raftElectionTimeoutMs(60000)

.enablePersistence(true)

.build();

Categories

Identity3

Raft8

Network10

Persistence4

Security11

Observability7

ClusterConfig

Property	Type	Default	Notes
clusterId	String	random UUID	Nodes with different IDs ignore each other’s JOIN.
nodeId	String	node-1	Must be non-blank.
host	String	127.0.0.1	Advertised/routable node host. Use bindAddress for the listener bind address.
port	int	5701	1–65535.
instanceNumber	int	1	≥ 0.
seeds	List	[]	host:port bootstrap peers.
heartbeatIntervalMs	long	2000	≥ 100.
heartbeatTimeoutMs	long	6000	Must exceed heartbeatIntervalMs.
maxMemoryBytes	long	1 GiB	Eviction trigger for the data-structure registry.
auditEnabled	boolean	false	Internal audit queue — not exposed on the wire.
auditQueueCapacity	int	10_000	> 0.
maxExecutorTaskPayloadBytes	int	1_048_576	Maximum serialized Callable payload accepted by EXECUTOR_* submit operations.
readBackupData	boolean	false	When true, member-local reads may use local backup data instead of read-index; values can be stale.
tlsConfig	TlsConfig	TlsConfig.disabled()	See below.
endpointTlsConfig	EndpointTlsConfig	EndpointTlsConfig.disabled()	Member, client, and WAN endpoint TLS roles.
authConfig	AuthConfig	AuthConfig.disabled()	See below.
dataDir	String	./data/wal	Set to null to disable WAL + snapshots.
idempotencyTtlMs	long	60_000	TTL for idempotency dedup cache.
queueConfigs	Map	{}	Per-queue capacity/max-size and empty-queue TTL declarations.
priorityQueueConfigs	Map	{}	Per-priority-queue comparator class declarations.

TlsConfig

Property	Default	Notes
enabled	false
keyStorePath	null	PKCS12 / JKS, or a provider-supported type.
keyStorePassword	""	Masked in toString().
keyStoreType	PKCS12
trustStorePath	null
trustStorePassword	""
trustStoreType	PKCS12
requireClientAuth	false	mTLS switch.
protocols	["TLSv1.3", "TLSv1.2"]
cipherSuites	[]	Empty → JVM defaults.
provider	JDK	JDK, OPENSSL, or OPENSSL_REFCNT. FIPS-controlled deployments should use JDK with a validated JSSE provider.
certExpirationWarningDays	30	Logged warning threshold.
certExpirationCriticalDays	7	Critical threshold — alerting territory.
revocationCheckingEnabled	false	Enable CRL/OCSP.
revocationSoftFail	true	Ignore CRL/OCSP fetch failures.
acceptTimeoutMs	2000	Server-socket SO_TIMEOUT.

Hot reload is handled by CertificateWatcher + CertificateReloader.

EndpointTlsConfig

EndpointTlsConfig lets one node carry separate TLS settings for member-to-member, member-to-client, and WAN roles:

EndpointTlsConfig endpointTls = EndpointTlsConfig.builder()
    .defaults(tls)
    .memberTlsConfig(memberTls)
    .clientTlsConfig(clientTls)
    .wanTlsConfig(wanTls)
    .build();

The legacy tlsConfig setter remains backward-compatible: one TlsConfig is applied to every endpoint. When endpoint TLS is supplied explicitly, the legacy tlsConfig() accessor exposes the member endpoint config. The current binary TCP listener is still a single socket and consumes the member endpoint config at runtime; client and WAN configs are parsed, validated, exposed, and preserved for deployments and future listener splits.

AuthConfig

Property	Default	Notes
enabled	false
gatewayTrust	false	Trust forwarded headers from an API gateway. This is opt-in; when auth is enabled without gateway trust, cert permissions, JAAS, LDAP, Kerberos, or token config, startup fails closed. Production profiles reject gatewayTrust=true.
userHeader	—	Header to read the authenticated user from.
rolesHeader	—	Header to read roles from.
rolePrefix	""	Prefix stripped from role names (e.g. ROLE_).
roleSeparator	,
trustedGatewayAddresses	{}	Only trust gateway headers from these source addresses. The properties loader supplies loopback defaults (127.0.0.1, ::1, 0:0:0:0:0:0:0:1, localhost) only when gatewayTrust=true is explicitly configured and this property is omitted.
roles	{}	Role → permission set.
certPermissions	{}	mTLS CN pattern → permission level.

See Security & mTLS for examples of both authorization styles.

Spring Boot (loomcache.*)

Mapped by LoomProperties:

loomcache.cluster

• seeds: list of host:port.
• nodeId, clusterId: optional; auto-generated when absent.

loomcache.node

• id (node-1), host (127.0.0.1), port (5701), instance (1). See Default Ports for how this binary member port relates to Docker and Kubernetes sample port 7654.

loomcache.client

• connectTimeoutMs (5000), requestTimeoutMs (3000), maxRetries (3).
• async-start (false): returns from client startup before the first member connection is established; operations fail fast until the initial connection succeeds.
• reconnect-mode (ON / ASYNC / OFF): ON retries in the background while invocations wait up to their timeout, ASYNC retries but fails invocations fast while reconnecting, and OFF closes the client on last-connection loss.
• routing-mode (ALL_MEMBERS / SINGLE_MEMBER / MULTI_MEMBER): smart routing opens member connections across the cluster; single-member routing keeps one unisocket-style member connection; multi-member routing filters seed connections to a configured member group.
• routing-member-group and routing-member-groups[].interfaces: selected member group and IP/CIDR ranges for MULTI_MEMBER client routing.
• near-cache.enabled (false in Spring Boot binding; direct LoomClient.Builder defaults to true), near-cache.max-size (10000), near-cache.ttl-seconds (30), near-cache.eviction-policy (LRU, LFU), near-cache.local-update-policy (INVALIDATE, CACHE_ON_UPDATE), near-cache.serialize-keys (false). Near-cache LRU/LFU is client-local freshness/capacity policy, not server-side data-retention or Hazelcast max-idle parity.
• near-cache.preloader.enabled (false), near-cache.preloader.directory (loomcache-near-cache-preloader), near-cache.preloader.store-initial-delay-seconds (600), and near-cache.preloader.store-interval-seconds (600) persist keys only for restart warmup.
• near-cache.reconciliation.enabled (true), near-cache.reconciliation.interval-seconds (60), and near-cache.reconciliation.tolerated-miss-count (10) periodically compare server invalidation sequences and clear a map when too many invalidations were missed.
• statistics.enabled (false) and statistics.upload-interval-seconds (3) enable best-effort periodic upload of client JVM/process, connection, and near-cache counters to a connected member.

loomcache.server

• enabled (false), port (5701), bind-address (0.0.0.0). The embedded node binds with loomcache.node.port; loomcache.server.port is a legacy property and logs a warning when it differs from loomcache.node.port.
• raft.election-timeout-ms (3000), raft.heartbeat-interval-ms (1000).
• health.icmp.* controls the optional ICMP/TCP-echo layer for failure detection: enabled, timeout-ms, interval-ms, max-attempts, and fail-fast-on-startup.
• diagnostics.slow-operation.* controls the opt-in slow operation detector: enabled, threshold-ms, sample-interval-ms, max-records, and max-stack-frames.
• persistence.enabled (true), persistence.wal-directory (./data/wal), persistence.snapshot-threshold (10000).
• migration.max-parallel-migrations (2) caps concurrent partition migrations per node.
• executor.max-task-payload-bytes (1048576) caps serialized Callable payloads for executor submit operations.
• read-backup-data (false) serves member-local reads from local backup data instead of read-index; enable only for embedded workloads that can tolerate stale reads.
• partition-group.type (PER_MEMBER / HOST_AWARE / PLACEMENT_AWARE / CUSTOM / SPI) controls primary/backup placement failure domains; PLACEMENT_AWARE expects member attributes such as zone, placement-group, and placement-partition, CUSTOM uses configured CIDR/IP member groups, and SPI uses discovery-provided partition-group member attributes.
• eviction.policy (NONE / LRU / LFU / FIFO / RANDOM), eviction.max-entries (0 in production), eviction.max-memory-bytes (9223372036854775807 in production). Production profiles must use NONE, 0, and Long.MAX_VALUE; server-side LRU/LFU/FIFO/RANDOM, finite max-entry/max-memory eviction, and max-idle remain unsupported until eviction decisions are Raft-applied and proven through WAL/snapshot/restart tests.
• hot-key.* — observability helpers only.

loomcache.queues

Declarative queue configs are keyed by queue name. capacity and max-size are aliases; 0 means unbounded. empty-queue-ttl and empty-queue-ttl-seconds are seconds, empty-queue-ttl-ms and empty-queue-ttl-millis are milliseconds, and -1 disables empty queue removal.

loomcache:
  queues:
    jobs:
      capacity: 256
      empty-queue-ttl: 30
    audit:
      max-size: 64
      empty-queue-ttl-ms: 1500

Equivalent properties:

loomcache.queue.jobs.capacity=256
loomcache.queue.jobs.empty-queue-ttl-seconds=30
loomcache.queues.audit.max-size=64
loomcache.queues.audit.empty-queue-ttl-ms=1500

Spring Boot uses the same top-level binding: loomcache.queues.<queue-name>.*.

loomcache.priority-queues

Declarative priority queue configs are keyed by queue name. priority-comparator-class-name is the fully qualified name of a class on the server classpath that implements java.util.Comparator<String>. Lower numeric priority still wins first; the comparator orders items that share the same numeric priority.

loomcache:
  priority-queues:
    critical:
      priority-comparator-class-name: com.example.CriticalComparator

Equivalent properties:

loomcache.priority-queue.critical.priority-comparator-class-name=com.example.CriticalComparator
loomcache.priority-queues.audit.comparator-class-name=com.example.AuditComparator

Spring Boot uses the same top-level binding: loomcache.priority-queues.<queue-name>.priority-comparator-class-name.

loomcache.tls

• enabled, key-store-path, key-store-password (JSON-ignored), key-store-type, trust-store-path, trust-store-password, trust-store-type, require-client-auth, protocols, provider.
• Endpoint overrides inherit the global loomcache.tls.* settings unless set: member.*, client.*, and wan.* each support enabled, key-store-path, key-store-password, key-store-type, trust-store-path, trust-store-password, trust-store-type, require-client-auth, protocols, and provider.

loomcache.auth

• enabled, gateway-trust, username, forwarded-roles, user-header, roles-header, role-prefix, role-separator, roles.<name>.permissions.

loomcache.spring-cache

• enabled (true), cache-names (list of pre-created names).

loomcache.session

• enabled (false), default-max-inactive-interval (30m), map-name (loom:sessions).

Client builder (non-Spring)

Methods on LoomClient.Builder:

• addSeed(String) / seeds(List|String...)
• connectionTimeout(Duration) / requestTimeout(Duration) / retryBaseDelay(Duration)
• maxRetries(int)
• asyncStart(boolean) / reconnectMode(ClientReconnectMode)
• tlsConfig(TlsConfig)
• auth(String user, String rolesCsv)
• nearCacheEnabled(boolean) / nearCacheTtl(Duration) / nearCacheMaxSize(int) / nearCacheEvictionPolicy(NearCacheEvictionPolicy) / nearCacheLocalUpdatePolicy(NearCacheLocalUpdatePolicy) / nearCachePreloaderConfig(NearCachePreloaderConfig) / nearCacheReconciliationConfig(NearCacheReconciliationConfig) / nearCacheSerializeKeys(boolean)
• clientStatisticsConfig(ClientStatisticsConfig) / clientStatisticsEnabled(boolean) / clientStatisticsUploadInterval(Duration)

Client async helpers:

• Pipelining.withDepth(int) or AsyncLoomClient.pipelining(int) creates a bounded in-flight helper for CompletionStage operations; add(stage) blocks at capacity and results() returns values in add order.

Client blue/green failover:

• ClientConfig.builder() captures one cluster’s seeds, timeouts, TLS, near-cache, routing, async-start, and reconnect settings.
• ClientFailoverConfig.builder().client(...).tryCount(n) orders multiple client configs and limits rollover attempts.
• FailoverLoomClient.connect(config) connects to the first reachable config; failover() closes the active client before rolling to the next reachable config. LoomCache.connectFailover(config) provides the same startup behavior for the convenience wrapper.

Client listeners:

• addLifecycleListener(LifecycleListener) observes client start, shutdown, member connection, and member disconnect states; FailoverLoomClient also emits CLIENT_CHANGED_CLUSTER after a successful blue/green rollover.
• addMembershipListener(MembershipListener) observes member add/remove events; InitialMembershipListener also receives the current member snapshot at registration.
• addDistributedObjectListener(DistributedObjectListener) observes unique client proxy creation for maps, queues, topics, CRDTs, counters, and other distributed-object handles.