A SWIM+INF+Susp cluster membership library for Elixir.
Nodes in a cluster automatically discover each other, detect failures, and converge on a shared view of membership — all over UDP, with no central coordinator.
children = [
{SwimEx.Supervisor,
host: "10.0.0.1",
port: 7771,
seeds: [{"10.0.0.2", 7771}, {"10.0.0.3", 7771}]}
]
SwimEx.subscribe()
# receives {:swim, :node_up, {"10.0.0.2", 7771, "c1"}} etc.
SwimEx.members()
#=> [{"10.0.0.2", 7771, "c1", :alive, 3}, {"10.0.0.3", 7771, "c1", :suspect, 1}]SWIM (Scalable Weakly-consistent Infection-style Membership) is a gossip protocol from a 2002 Cornell paper. Each node periodically pings one other node. If the ping fails, it asks a few random nodes to relay an indirect ping. Only if both fail does the target become suspect. After a suspicion timeout it is declared dead.
This library implements the SWIM+INF+Susp variant, which adds:
- Incarnation numbers — each node carries a monotonically increasing counter. A suspected node can refute false positives by broadcasting an alive event with a higher incarnation number.
- Suspicion period — a configurable delay between first suspecting a node and declaring it dead, reducing false positives from GC pauses or transient packet loss.
swim_ex detects membership changes; it does not provide consensus, leader election, or reliable delivery. If you need those, layer them on top with a library such as Ra. swim_ex's value is low overhead: O(1) messages per node per period regardless of cluster size.
Messages are encoded with :erlang.term_to_binary/1.
This is trivially fast in Elixir and requires zero
dependencies, but it means non-BEAM nodes cannot
participate. If polyglot clusters matter, the codec
module is the only place that needs to change.
SWIM is designed for UDP. Occasional dropped messages are tolerable — the protocol's redundant gossip and repeated pinging absorb them. Adding TCP would reduce false positives in pathological networks but defeats much of SWIM's simplicity. The tradeoff is documented; Lifeguard extensions (Hashicorp's local health multiplier) were deliberately excluded to keep the implementation small.
A node's identity is its {host, port, cookie} tuple, stable
across restarts. On each startup, the incarnation
number is seeded from System.system_time(:millisecond)
so a restarted node can always override stale dead
events from its previous life — without needing a
persistent incarnation counter on disk. The caveat:
a large NTP step-back in the window between crash and
restart can delay re-joining. See DESIGN.md §9 for the
full analysis.
The membership state machine (SwimEx.Membership) and
gossip queue (SwimEx.GossipQueue) are pure functions
over immutable structs. SwimEx.Protocol is a thin
GenServer shell that owns timers and sockets and
delegates all state transitions to those modules. This
separation makes the protocol logic testable without
starting any processes, and makes the StreamData
property tests possible.
The production transport is UDP only. An
SwimEx.Transport.InMemory implementation lives in
test/support/ and is not part of the public API. It
lets integration tests inject packet loss, delay, and
reorder without any real sockets. A shared
Network process acts as the routing hub between
in-memory nodes.
Early release. The protocol implementation is complete and tested, but the library has not been run in production. Bug reports and pull requests welcome.
Tested on: Elixir 1.15 / OTP 26.
- USAGE.md — installation, configuration reference, API, telemetry, and testing guide
- DESIGN.md — full design decisions and rationale, including every tradeoff answered before the first line of code was written
MIT. See LICENSE.