Ronin

Masterless High-Availability Leader Election for Go.
Ronin embeds NATS JetStream (Raft) as the consensus engine so you can ship leader election as part of a single binary.

$ go get github.com/nonchan7720/ronin
Get Started
Copied!

Why Ronin?

Ronin provides leader election semantics similar to Kubernetes Lease Leader Election without depending on an external etcd or Kubernetes API Server.
Since it embeds the consensus engine, you can simplify operations by shipping a single binary.

Traditional Approach

  • Requires external etcd/Zookeeper cluster
  • High operational overhead
  • Distributed failure points & complex management

The Ronin Way

  • No external middleware: Embedded NATS + JetStream
  • Safety First: Prevents double leaders / Self-step down
  • Manager/Candidate: Multi-shard efficiency

Architecture Explorer

Click on the components below to understand how Ronin achieves scalability.

Process A (Node 1)
Manager
Infrastructure Layer
Candidate 1
Shard 1 Logic
Candidate 2
Shard 2 Logic
Embedded NATS JetStream (Raft)

Interactive Guide

Ronin uses a Manager-Candidate architecture. This separation is crucial for running hundreds of election shards within a single process efficiently.

Click a component on the diagram to learn more.

Core Features

Safety First

Prevents double leaders and self-steps down on stale leadership. Provides semantics similar to Kubernetes Lease Leader Election.

Embedded NATS

Embeds NATS JetStream (Raft) as the consensus engine. Run as a single binary without setting up complex external middleware.

OpenTelemetry

Exports metrics for leadership status, KV revision, and failure counts out of the box. Supports custom MeterProviders.

Minimal Example

main.go

Implementation Steps

Observability

Built-in Metrics

If your application configures the OpenTelemetry SDK, Ronin exports metrics automatically.

  • election.leader_status Gauge: 1 if leader, otherwise 0
  • election.leader_term Gauge: NATS KV revision (fencing token)
  • election.renew_failures_total Counter: Number of renew failures
  • election.leader_changes_total Counter: Number of observed leader changes

Live Metrics Simulation

Last 60s Now

Operational Notes

Quorum is Key

Reliable leader election needs a quorum.

3+ Nodes (Recommended) Tolerates one node failure.
1 Node For development. Single Point of Failure (SPOF).