MongoDB backend

Library module

Problem

Implements single/group election with token-owned MongoDB documents, atomic findOneAndUpdate, expiry, TTL indexes, and blocking/coroutine factories.

When to use it

Choose it when MongoDB is already a durable application dependency and coordination in the same replica set is operationally simpler.

Coordinates

Artifact: io.github.bluetape4k.leader:bluetape4k-leader-mongodb

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.leader:bluetape4k-leader-mongodb")
}

Core concepts

The collection stores lock documents with owner token and expireAt; atomic filters acquire and extend. TTL index cleanup is not the correctness clock.

Quick start

val collection = database.getCollection<Document>("bluetape4k_leader_locks")
val elector = MongoLeaderElector(collection)
elector.runIfLeader("tenant-aggregation") { aggregate() }

API by task

Use blocking/suspend single and group electors, factories, extensions, and optional Mongo history sink/indexer. Collection lifecycle is caller-owned.

Recommended patterns

Use majority write concern in replica sets, stable collection/name prefixes, idempotent actions, and owner-token conditions on extend/release.

Integrations

Spring can build factories from a MongoClient. tenant-aggregator demonstrates a partitioned workload.

Configuration

Configure database/collection, wait/lease/minimum lease, retry delay, group size, write concern, and history TTL/index policy.

Failure modes

Contention returns null. Network, primary election, write-concern, permission, and index errors propagate. TTL deletion delay must not control acquisition.

Operations

Monitor command latency, write concern errors, primary changes, retry rate, stale documents, TTL monitor lag, extension failures, and history growth.

Testing

Use a replica-set Testcontainer for two-client contention, failover behavior, TTL/expiry, stale owner, group slots, suspend cancellation, and index creation.

Workshops and learning path

Run tenant-aggregator, then compare MongoDB with SQL when deciding document versus transactional coordination.

Limitations

Replica-set configuration affects split-brain risk. MongoDB lease ownership does not fence writes to another system.

Release diagrams

These diagrams are loaded directly from README assets published with the 0.4.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

leader mongodb Class Structure diagram

Release README: leader-mongodb/README.md

Sources

Elector · Lock implementation · Stable guide