Skip to content
LoomCache

Configuration Reference

LoomConfig provides centralized, immutable configuration for a LoomCache node. All settings ship with sensible defaults, allowing quick cluster startup with minimal overhead. The builder enforces validation rules at construction time to catch errors early.

Configuration Sources

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

J
Builder API
LoomConfig.builder()
.nodeId("node-1")
.port(5701)
.raftElectionTimeoutMs(3000)
.enablePersistence(true)
.build();
Categories
Identity3
Raft8
Network10
Persistence4
Security11
Observability7

Node Identity

Section titled “Node Identity”
PropertyTypeDefaultDescription
nodeIdString(required)Unique identifier for this node. Must not be blank.
bindAddressString0.0.0.0Network interface to bind. Use 127.0.0.1 for localhost only.
portint5701TCP port for node-to-node and client communication. Range: 1–65535.

Cluster

Section titled “Cluster”
PropertyTypeDefaultDescription
clusterMembersList<String>(empty)Bootstrap peer addresses in host:port format.

Raft Consensus

Section titled “Raft Consensus”
PropertyTypeDefaultDescription
raftElectionTimeoutMinMslong300Minimum election timeout (ms). Followers wait this duration before starting election. ≥100ms.
raftElectionTimeoutMaxMslong600Maximum election timeout (ms). Randomized between min/max to prevent split votes.
raftHeartbeatIntervalMslong100Leader heartbeat interval (ms). Must be much less than election timeout. Min 10ms.
raftPreVoteEnabledbooleantruePre-vote phase prevents disruption from partitioned nodes with stale terms.
maxEntriesPerAppendint100Max log entries per AppendEntries RPC.
replicationIntervalMslong50Interval between replication checks per follower.
replicationTimeoutMslong5000Timeout for follower replication acknowledgments.
logCompactionThresholdint10000Entries before triggering log compaction. Higher = less I/O, more memory.

Timing Guarantees

Section titled “Timing Guarantees”
  • Liveness: Heartbeat interval < min election timeout ensures followers recognize live leader
  • Safety: Randomized timeouts prevent simultaneous elections
  • Default tuning: 100ms heartbeats with 300–600ms election timeout balances responsiveness with stability
Recommended:  heartbeat 100ms, election 300ms  (3x ratio)
Aggressive:   heartbeat 50ms,  election 100ms  (2x ratio, lower latency)
Conservative: heartbeat 500ms, election 2000ms (4x ratio, lower churn)

Failure Detection & Discovery

Section titled “Failure Detection & Discovery”
PropertyTypeDefaultDescription
phiAccrualThresholddouble8.0Suspicion threshold. Higher = fewer false positives. Range: 7.0–10.0.
enableAdaptiveThresholdbooleantrueAuto-adjust threshold based on observed latency variance.
discoveryRetryBackoffMslong100Initial backoff for DNS/discovery retries. Exponential up to 500ms.
discoveryMaxRetriesint3Max retry attempts before falling back to cached addresses.
discoveryTtlAwareCachingbooleantrueRetain discovered addresses on transient DNS failures.
discoveryHealthCheckEnabledbooleantrueTCP connectivity checks on cached discovery addresses.
discoveryHealthCheckIntervalMslong30000Interval between health checks on cached addresses.

Environment tuning:

  • LAN: phi 8.0, adaptive disabled
  • WAN/cloud: phi 8.5–9.0, adaptive enabled
  • High churn: max retries 5, TTL-aware caching on

Network

Section titled “Network”
PropertyTypeDefaultDescription
maxConnectionsint10000Maximum concurrent TCP connections.
tcpReadTimeoutMslong30000Socket read timeout (ms).
tcpIdleTimeoutMslong300000Idle connection timeout (5 min default).
gracefulShutdownDrainMslong200Drain in-flight requests during shutdown.
healthCheckIntervalMslong2000Peer health check interval. Min 100ms.
metricsPortint9090Prometheus metrics HTTP endpoint port.

Circuit Breaker (Per-Peer)

Section titled “Circuit Breaker (Per-Peer)”
PropertyTypeDefaultDescription
circuitBreakerConfig.enabledbooleantruePer-peer circuit breaker isolation.
circuitBreakerConfig.failureThresholdint5Consecutive failures before OPEN.
circuitBreakerConfig.recoveryTimeoutMslong30000Time before OPEN → HALF_OPEN transition.
circuitBreakerConfig.halfOpenMaxRequestsint3Max concurrent requests in HALF_OPEN.

Persistence

Section titled “Persistence”

All writes are persisted to WAL before acknowledgment. Snapshots compact recovery logs.

PropertyTypeDefaultDescription
dataDirPath./dataWAL and snapshot directory. Use SSD/NVMe.
snapshotThresholdint10000Entries before creating a snapshot.
enablePersistencebooleanfalseEnable WAL + snapshots. Set true for production.
syncOnCommitbooleantruefsync after each commit. false = lower latency, higher crash risk.

WAL format: 4-byte length + 8-byte term + 8-byte index + command bytes + 4-byte CRC32

Recovery sequence:

  1. Load latest snapshot (if exists)
  2. Replay WAL entries after snapshot index
  3. Rejoin cluster and participate in election

Cache & Eviction

Section titled “Cache & Eviction”
PropertyTypeDefaultDescription
maxMapEntriesint100000Max key-value pairs in memory.
evictionPolicyStringLRUEviction strategy: LRU, LFU, or Random.
maxMemoryByteslong1073741824Memory limit (1 GB default).

Container tip: Set maxMemoryBytes to 70–80% of the container’s memory limit.

Security (TLS/mTLS)

Section titled “Security (TLS/mTLS)”
PropertyTypeDefaultDescription
tlsConfig.enabledbooleanfalseEnable TLS encryption. Required for production.
tlsConfig.keyStorePathPath(required)PKCS12 keystore with server identity.
tlsConfig.keyStorePasswordString(required)Keystore password.
tlsConfig.trustStorePathPath(required)Truststore with trusted peer certificates.
tlsConfig.trustStorePasswordString(required)Truststore password.
tlsConfig.requireClientAuthbooleantrueEnforce mTLS (client must present certificate).
tlsConfig.protocolsList[TLSv1.3, TLSv1.2]Allowed TLS protocol versions.

Authorization (RBAC)

Section titled “Authorization (RBAC)”
PropertyTypeDefaultDescription
authConfig.enabledbooleanfalseEnable role-based authorization.
authConfig.gatewayTrustbooleantrueTrust X-Auth-User and X-Auth-Roles headers.
authConfig.userHeaderStringX-Auth-UserHeader for authenticated username.
authConfig.rolesHeaderStringX-Auth-RolesHeader for comma-separated roles.
authConfig.rolePrefixStringROLE_Prefix to strip from role names.

Supported permissions: MAP_GET, MAP_PUT, MAP_DELETE, QUEUE_PUSH, QUEUE_POP, QUEUE_PEEK, SET_ADD, SET_REMOVE, SET_CONTAINS, TOPIC_PUBLISH, TOPIC_SUBSCRIBE, LOCK_TRY, LOCK_UNLOCK, COUNTER_INCREMENT, COUNTER_GET, HEALTH_CHECK, METRICS_READ, CLUSTER_INFO, * (wildcard).

Hot Key Detection

Section titled “Hot Key Detection”
PropertyTypeDefaultDescription
hotKeyConfig.enabledbooleanfalseEnable hot key sampling.
hotKeyConfig.samplingRatedouble0.05Sample probability (0.05 = 5%).
hotKeyConfig.thresholdint100Accesses per window to classify as hot.
hotKeyConfig.windowDuration60sEvaluation window duration.
hotKeyConfig.maxTrackedKeysint10000Max distinct keys to track. FIFO eviction.

Pipelined Execution

Section titled “Pipelined Execution”
PropertyTypeDefaultDescription
pipelinedExecutionbooleanfalseBatch commands for higher throughput.
commandQueueCapacityint10000Max commands in execution queue.
commandExecutorThreadsint0Dedicated executor threads. 0 = ForkJoinPool.

Audit Logging

Section titled “Audit Logging”
PropertyTypeDefaultDescription
auditEnabledbooleanfalseLog all data operations for compliance.
auditQueueCapacityint10000Max queued audit entries before dropping. Never blocks data path.

Audit format: timestamp | nodeId | clientId | command | key | result | durationMs | requestId

Discovery Strategies

Section titled “Discovery Strategies”
StrategyConfigurationUse Case
Static ListclusterMembers in builderSmall fixed clusters
Seed NodesLOOMCACHE_NODES env varGrowing clusters with gossip
MulticastEnable on LANLocal datacenter
DNS/Service DiscoveryConsul, Eureka, DNS SRVCloud-native and Kubernetes
Hardcoded DefaultEmpty clusterMembersLocal development

Environment Variables

Section titled “Environment Variables”
VariablePurposeExample
LOOMCACHE_NODESSeed node addressesnode1:5701,node2:5701
LOOMCACHE_PORTServer port override6000

System properties take precedence over environment variables. Builder defaults apply if neither is set.

Validation Rules

Section titled “Validation Rules”

The builder enforces these constraints at construction:

  • nodeId must not be null or blank
  • port and metricsPort must be 1–65535
  • raftElectionTimeoutMs ≥ 100ms
  • raftHeartbeatIntervalMs ≥ 10ms
  • healthCheckIntervalMs ≥ 100ms
  • snapshotThreshold > 0
  • maxMapEntries > 0
  • maxMemoryBytes > 0
  • heartbeatTimeoutMs > heartbeatIntervalMs

Full Example

Section titled “Full Example”
LoomConfig config = LoomConfig.builder()
    // Node identity
    .nodeId("cache-node-1")
    .bindAddress("192.168.1.10")
    .port(5701)


    // Cluster
    .clusterMembers(List.of(
        "192.168.1.10:5701",
        "192.168.1.11:5701"
    ))


    // Raft consensus
    .raftElectionTimeoutMs(3000)
    .raftHeartbeatIntervalMs(1000)
    .maxEntriesPerAppend(100)
    .logCompactionThreshold(10000)


    // Network
    .maxConnections(10000)
    .gracefulShutdownDrainMs(200)
    .metricsPort(9090)


    // Persistence
    .enablePersistence(true)
    .dataDir("./data")
    .snapshotThreshold(10000)
    .syncOnCommit(true)


    // Cache
    .maxMapEntries(100000)
    .evictionPolicy("LRU")
    .maxMemoryBytes(2_147_483_648L)


    // Audit
    .auditEnabled(true)
    .auditQueueCapacity(10000)


    .build();