Master & Thin Clients

In any cluster of two or more nodes, exactly one node is the master. The rest are thin clients. This is not a database leader-election in the traditional sense, there is no consensus protocol, no quorum, no Raft term. The master is simply the node that holds the real backend addresses for the cluster's origins.

What each role does

Why this design

Treating only the master as having "real" upstream connectivity means thin clients can be placed anywhere, a far region, a partner's network, a small embedded device, without needing direct line-of-sight to the origin web server. The master is the single point that talks to the origin, and the thin clients form a transparent fan-out around it.

Three concrete benefits fall out of this design:

• Latency. Each thin client serves its region's traffic from a local cache. Users in that region get cache hits without ever crossing to the master, which is often on a different continent.
• Security. The only network port the thin client needs open to the world is its own public port (typically fronted by your TLS terminator). Replication, cache pulls, and control-plane sync between thin and master all flow over a single encrypted port, the same port that serves end users. There is no separate "replication port" to firewall, no admin channel to secure separately. Smaller surface area, fewer rules to forget.
• Simplicity. No shared database, no quorum service, no message broker. Adding capacity is "install the package, subscribe, restart", that is the entire runbook.

Each thin client maintains its own cache for the master. If the master itself becomes unreachable, the thin client serves HEADLESS responses locally from that cache. So you get two layers of resilience:

Promoting a different node to master

From the control panel: open your cluster, click the ☆ icon next to the node you want to promote. The icon turns into a gold ★ and the API responds. On each cluster member, re-subscribe and restart:

sudo qscs subscribe domain <cluster-tag>
sudo systemctl restart qscs

Old master becomes a thin client; new master picks up real backend addresses.