youndie@kotlin.website:~/src$ cat vojak/README.md

vojak

kmp: jvm + native · postgres · leader election · kore
Leader election and a distributed lock for Kotlin/Native and JVM services, on the Postgres they already have: advisory locks, no etcd, no ZooKeeper, no Kubernetes Lease. It promises at most one process that believes it leads, and an epoch per leadership a store can fence on.

Why it exists

Run a service as two replicas — for availability, or just for a rolling update with maxSurge — and every singleton in it runs twice: the long-polling bot client its upstream allows only once, the scheduler that sends the morning digest, the sweeper. On the JVM this is solved by ShedLock or Spring Integration's LockRegistry. On Kotlin/Native nothing exists, and the alternatives — etcd, ZooKeeper, a Kubernetes Lease with the RBAC it needs — are a second piece of infrastructure bought to answer one question.

vojak answers it with the coordinator the service already has: its Postgres, through advisory locks.

What it promises, exactly

An advisory lock alone gives "one session holds the lock", which is not "one process acts as leader". vojak promises less than "one leader", and says so: at most one process believes it leads at any instant, provided clock drift stays inside the lease margin — and a monotonically increasing epoch per leadership, so that a store can reject a stale leader's writes. Making a stale leader harmless is the store's job; vojak makes it possible.

How it holds that:

  • The lock lives in an open transaction — pg_try_advisory_xact_lock — so there is exactly one release path, and it is the one Postgres guarantees.
  • The server holds a lease too. idle_in_transaction_session_timeout on the holding transaction means a partitioned leader's session is ended by Postgres and its lock goes with it. Measured: a 5 s lease freed after 5029 ms on linuxX64 and 5045 ms on the JVM.
  • The leader steps down on a timer, half the server lease after its last successful heartbeat, rather than by waiting for a driver call that may hang under a partition.
  • A new leader waits out the old one unless the old one let go cleanly. When the server ends a session — a restart, a failover — the lock is free at once, but the old leader only learns at its next renewal; that overlap was measured in every round before the wait was built.

Modules

vojak-core names, waiting, the election
vojak-postgres the store over an sqlx4k driver, for Kotlin/Native and the JVM
vojak-jdbc the store over a javax.sql.DataSource, for a JVM service that already has JDBC — the same statements, so replicas on either store are one election
vojak-kore the election as a kore participant, so leadership is given up in the drain

Targets: jvm, linuxX64, linuxArm64.

Install

Every push to main publishes 0.1.0.<run> to the portfolio's Reposilite:

repositories {
    maven("https://reposilite.kotlin.website/snapshots") {
        mavenContent { includeGroupAndSubgroups("io.github.youndie") }
    }
}

dependencies {
    implementation("io.github.youndie.vojak:vojak-postgres:0.1.0.<run>")
}

The latest is the last one in maven-metadata.xml.

Limitations

  • Not released to Maven Central yet.
  • The promise depends on clock drift staying inside the margin between the two leases; that bound is assumed, not measured.
  • A restart or a kill of the leader costs a local lease — 7.5 s by default — of nobody leading. That is the price of the promise being true.