# vojak

> 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, and an epoch per leadership that a store can fence on.

Page: https://kotlin.website/vojak

## 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](https://github.com/youndie/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](https://kotlin.website/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:

```kotlin
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](https://reposilite.kotlin.website/snapshots/io/github/youndie/vojak/vojak-core/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.
