# `MqttX.Server.Cluster`
[🔗](https://github.com/cignosystems/mqttx/blob/v0.13.0/lib/mqttx/server/cluster.ex#L1)

One broker across several nodes.

When the node is part of an Erlang cluster, the listeners started with the
same `:name` on each node form a group (via `:pg`). Nothing is configured:
a listener joins its group when it starts, and on a node that is not
distributed the group has one member and none of this costs anything.
Within a group:

  * `MqttX.Server.deliver/3` fans a message out on every node with a
    matching subscription: each node tells the others which filters its
    sessions subscribe to.
  * A client may connect to any node. Its CONNECT reaches every other node
    of the group, which disconnects a connection it still holds for that
    client id (§3.1.4 takeover), cancels its pending Will Delay and
    Session Expiry, and hands its stored session over (Clean Start 0) or
    discards it (Clean Start 1).
  * Retained messages are replicated to every node; a node that joins
    receives the others' retained messages. Concurrent writes to one topic
    resolve to the latest, and a clear is remembered for an hour, so a
    node that missed it cannot bring the message back.
  * A shared subscription (§4.8) delivers each message once across the
    cluster: shared group membership is replicated, and the delivering node
    picks one member wherever it is connected. The node holding that member
    answers whether it took the message; if not — its client is offline,
    its session is gone, or the node leaves before answering — the next
    member is picked, a connected one first.

A session lives on one node at a time. While it moves, the node it left
forwards what it matches for it and the node it moved to drops the copies
it already has, and holds back what it matches itself until everything
sent to the old node before the move has been forwarded — so a message
published meanwhile is delivered once, in its publisher's order. A node
that goes down takes its sessions with it, unless the listener has a
`MqttX.Server.SessionBackend` that the other nodes reach too
(`MqttX.Server.SessionBackend.Replicated`). `docs/design/clustering.md`
has the design notes.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `members`

```elixir
@spec members(term()) :: [pid()]
```

The member processes of a listener's group, one per node that runs it.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
