How chengchen/leadership-consul works
Project type and purpose
• This is a Java library (“open-source tool”) that provides leader-election functionality on top of Consul (with an alternative HTTP-only variant).
• Its core offering is a Gambler abstraction that emits leadership events (elected, revoked, etc.) by interacting with Consul’s session and key-value APIs.
File structure
• Top-level build files: Gradle wrappers and build.gradle.
• src/main/java/net/kinguin/leadership/core: core interfaces and abstractions (e.g., Member, ElectionMessage, AbstractClusterFactory).
• src/main/java/net/kinguin/leadership/consul: Consul-based implementation, with subpackages for configuration (config), election (election), factory (factory), and operations (operation).
• src/main/java/net/kinguin/leadership/http: HTTP-only fallback client implementation.
• Tests mirror that structure, plus a docker-compose.yml to spin up Consul for integration tests.
README for additional insights
• Usage examples show how SimpleClusterFactory builds a Gambler that “asObservable” emits events.
• A Spring integration example wires in SessionConsulClient and KeyValueConsulClient beans.
Main components and their relationships
a. Core library (package “core”)
• Interfaces / data models: Member, ElectionMessage, ElectionState, ClusterConfiguration
• Factory abstraction: AbstractClusterFactory → produces Gambler instances
b. Consul implementation (package “consul”)
• Clients: SessionConsulClient, KeyValueConsulClient
• Operations: CreateSession, UpkeepSession (manage TTL/session refresh)
• Cluster factory: SimpleConsulClusterFactory uses clients + operations to instantiate a ConsulMember
c. HTTP-only implementation (package “http”)
• HttpMember, HttpMemberProperties, ElectionResponse (for environments that proxy Consul HTTP themselves)
d. External service
• Consul agent (on TCP 8500) – provides HTTP APIs for sessions and KV store
e. Consumers
• Application code subscribes to the Observable returned by Gambler.asObservable() to react to leadership events
Essential architectural elements to capture
• Core vs. implementation modules
• Factory → Member → Client → External Consul
• Reactive event stream returning to the user’s application
• Configuration inputs (ClusterConfiguration, Spring-style properties)