noleader

A small, ergonomic Rust crate for leader election using NATS KeyValue (KV) as the distributed locking mechanism. Does not require a fixed set of nodes—any number of candidates can join or drop out dynamically.

Disclaimer

This library is still young and the API is subject to change.

Features

Distributed locking with TTL Uses NATS JetStream KV store to create a key with a TTL, ensuring only one leader at a time.
Automatic renewal with jitter Renews leadership every ~10 s (plus a random back-off) to avoid thundering‐herd elections.
Graceful shutdown Integrates with tokio_util::sync::CancellationToken so you can cancel leadership and ongoing work cleanly.
Leader-only work loop do_while_leader runs your async closure as long as you hold leadership, cancelling it immediately upon relinquish.
No required cluster size Nodes can join or leave at any time—no minimum/maximum constraints.

Intended use-case

Noleader is not built for distributed consensus, or fast re-election produces. It take upwards to a minute to get reelected, state is the users responsibility to handle.

Noleader is pretty much just a distributed lock, intended for use-cases where the use wants to only have a single node scheduling work etc.

Good alternatives are:

Raft (for distributed consensus)
Relational databases (for locking)

Installation

[dependencies]
noleader = "0.1"

Then in your code:

use noleader::Leader;

Quick Example

use tokio_util::sync::CancellationToken;
use tracing_subscriber::EnvFilter;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Set up logging
    tracing_subscriber::fmt()
        .with_env_filter(
            EnvFilter::from_default_env()
                .add_directive("noleader=debug".parse().unwrap())
                .add_directive("info".parse().unwrap()),
        )
        .init();

    let bucket = "my_bucket";
    let key    = "election_key";
    let client = async_nats::connect("localhost:4222").await?;

    // Create a new leader election instance
    let leader = Leader::new(bucket, key, client.clone());

    // Ensure the KV bucket exists
    leader.create_bucket().await?;

    // Attempts to acquire election loop, will call inner function if it wins, if it loses it will retry over again.
    // Will block until either the inner function returns and error, or the election processes crashes, intended to allow the application to properly restart
    leader
        .acquire_and_run({
            move |token| {
                let leader_id = leader_id.clone();

                async move {
                    loop {
                        if token.is_cancelled() {
                            return Ok(());
                        }

                        tracing::info!(leader_id, "do work as leader");
                        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
                    }
                }
            }
        })
        .await?;


    Ok(())
}

API Overview

Leader::new(bucket: &str, key: &str, client: async_nats::Client) -> Leader Create a new election participant.
create_bucket(&self) -> anyhow::Result<()> Ensures the KV bucket exists (no-op if already created).
start(&self, token: CancellationToken) -> anyhow::Result<()> Begins the background leader-election loop; renews TTL on success or retries on failure.
do_while_leader<F, Fut>(&self, f: F) -> anyhow::Result<()> Runs your closure as long as you hold leadership; cancels immediately on loss.
leader_id(&self) -> Uuid Returns your unique candidate ID.
is_leader(&self) -> Status Returns Status::Leader or Status::Candidate, taking shutdown into account.

Types

pub enum Status {
    Leader,
    Candidate,
}

License

This crate is licensed under the same terms as the workspace (MIT or Apache-2.0). See LICENSE-MIT and LICENSE-APACHE.

Contribute

Issues and PRs are welcome! Repository: https://git.front.kjuulh.io/kjuulh/noleader Development happens publicly on the main branch—feel free to fork and send a merge request.

noleader 0.1.2