Clustering

Multiple relay instances can cluster for geographic distribution and improved latency.

Overview

moq-relay uses a simple clustering scheme:

1. Root node - A single relay (can serve public traffic) that tracks cluster membership
2. Other nodes - Accept internet traffic and consult the root for routing

When a relay publishes a broadcast, it advertises its node address to other relays via the root.

Configuration

[cluster]
root = "https://root-relay.example.com"  # Root node
node = "https://us-east.relay.example.com"  # This node's address

Cluster Arguments

• --cluster-root <HOST> - Hostname/IP of the root node (omit to make this node the root)
• --cluster-node <HOST> - Hostname/IP of this instance (needs valid TLS cert)

How It Works

1. Each relay connects to the root node on startup
2. When a publisher connects to any relay, that relay announces the broadcast
3. The root node tracks which relay has which broadcasts
4. When a subscriber connects, the relay queries the root to find the broadcast
5. Relays connect to each other to forward traffic

Benefits

• Lower latency - Users connect to nearest relay
• Higher availability - Redundancy across regions
• Geographic distribution - Serve global audiences

Example Topology

                    ┌─────────────┐
                    │  Root Node  │
                    │   (US-C)    │
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           │               │               │
    ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐
    │   US-East   │ │   EU-West   │ │   Asia-SE   │
    │   Relay     │ │   Relay     │ │   Relay     │
    └─────────────┘ └─────────────┘ └─────────────┘

Peer Authentication

Cluster peers must authenticate to each other. Two options:

JWT token

Each leaf reads a JWT from cluster.token (see Authentication) and presents it to the root on connect. The token must grant cluster privileges and full publish/subscribe access.

mTLS (recommended for new deployments)

Configure the root with tls.root pointing at the CA that signed the leaf certificates. Leaves connect with a client certificate signed by that CA — no JWT needed. The leaf's cluster node name is taken from the first DNS SAN on its certificate, so identity is bound to the cert rather than self-declared.

See Authentication → mTLS Peer Authentication for details.

Current Limitations

• Mesh topology - All relays connect to all others
• Not optimized for large clusters - 3-5 nodes recommended
• Single root node - Future: multi-root for redundancy

Production Example

The public CDN at cdn.moq.dev uses this clustering approach:

• usc.cdn.moq.dev - US Central (root)
• euc.cdn.moq.dev - EU Central
• sea.cdn.moq.dev - Southeast Asia

Clients use GeoDNS to connect to the nearest relay automatically.

Next Steps

• Deploy to Production
• Set up Authentication
• Learn about Protocol concepts