Bluetape4k Leader manual
Latest stable Based on Leader release 1.0.0
A release-faithful guide to choosing, running, and operating distributed leader election with bluetape4k-leader 1.0.0.
Core capabilities
Section titled “Core capabilities”- Election models: Single, group, and strategic election support one global leader, bounded parallel leaders, and policy-driven ownership.
- Execution APIs: Blocking, future, virtual-thread, and coroutine APIs preserve the same election result semantics across application execution models.
- Lease lifecycle: Lease extension and the lease lifecycle guide define wait time, lease time, minimum hold, renewal, release, and loss behavior.
- Distributed backends: The backend selection guide covers Redis, SQL, document stores, cluster coordination systems, and control-plane leases without changing the core contract.
- Framework integration: Spring Boot, Ktor, and Micrometer modules connect configuration, lifecycle, and metrics to the host application.
- Operations and workshops: Observability and operations plus runnable scheduler, migration, and dashboard examples turn election behavior into deployable runbooks.
Start with the decision, not the backend
Section titled “Start with the decision, not the backend”Leader election is useful when every service instance can see the same work but only one, or a bounded number, should execute it. This manual starts with execution semantics and failure boundaries before it asks you to choose Redis, SQL, MongoDB, or a control-plane lease.
The central contract is deliberate: ordinary contention is not an error. runIfLeader() executes the action when elected and returns null when another contender owns the lease. Use the result APIs when the action itself may return null.
Recommended route
Section titled “Recommended route”- Follow Getting started with a local elector.
- Choose single, group, or strategic election.
- Match the API to blocking, future, virtual-thread, or coroutine execution.
- Select a backend from infrastructure you already operate.
- Define the lease lifecycle, then add metrics and runbooks.
Reference by task
Section titled “Reference by task”- Learn the shared contract in Leader core.
- Compare Lettuce and Redisson for Redis.
- Choose Exposed JDBC or Exposed R2DBC for SQL-backed election.
- Integrate with Spring Boot, Ktor, or Micrometer.
- Start from a runnable scenario such as the batch scheduler, migration gate, or Prometheus dashboard.
Release boundary
Section titled “Release boundary”Every behavior and source link in this manual targets release 1.0.0 at commit e70146330302758f563a46b7286e3ce25f1bac49. Examples are learning projects, not published artifacts. Application builds should normally import io.github.bluetape4k:bluetape4k-dependencies and omit versions from individual leader modules.