Host Migration & Failover

In GONet, every client in a session maintains enough state to potentially become the new host. This "hot-standby" approach means there is no single point of failure -- if the current host goes down, the session can continue without requiring players to reconnect or restart.

The host is responsible for authoritative state, GONetId allocation, scene management, and time sync. All other clients are potential replacement hosts, ranked by a scoring algorithm that runs continuously in the background.

GONet uses a lightweight gossip protocol to monitor the health of all participants in the session. Each client periodically exchanges heartbeat messages with other clients, building a distributed view of who is alive, who is degraded, and who has disconnected.

• •Heartbeat exchange -- Clients send periodic heartbeats. Missing heartbeats trigger suspicion, and sustained absence triggers a disconnect declaration.
• •Mesh topology -- The gossip protocol forms a mesh among all clients, so even if the direct path to the host is down, clients can learn about the host's status through other peers.
• •Fast detection -- The combination of direct heartbeats and gossip means host failure is typically detected within a few seconds.

Not all clients are equally suited to be the host. GONet maintains a continuous host score for each participant based on several factors:

• •Connection quality -- Clients with lower latency and more stable connections score higher.
• •Uptime -- Clients that have been in the session longer are preferred, as they have the most complete state.
• •Resource availability -- The scoring considers the client's ability to handle the additional responsibilities of being a host.

When a failover is triggered, the highest-scoring client is automatically elected as the new host. This election is deterministic -- all clients agree on the same new host without additional negotiation.

When the host is detected as unreachable, the failover process proceeds automatically:

1. 1.Detection -- Gossip protocol detects host absence (typically 2-3 seconds).
2. 2.Election -- All clients independently compute the same new host using the scoring algorithm. No voting round is needed.
3. 3.Promotion -- The elected client assumes host responsibilities: GONetId allocation, authoritative state, scene management, and time sync.
4. 4.Reconnection -- Other clients reconnect to the new host and resume normal operation.
5. 5.Recovery complete -- Recovery is guaranteed in under 7 seconds from host failure to full session resumption. In practice, most failovers resolve within a second.

One of the most challenging aspects of host migration is maintaining consistent time. GONet's time sync system preserves continuity across failovers:

• •The new host inherits the session's elapsed time, not its own local clock. This prevents a time jump when the host changes.
• •Clients re-synchronize against the new host's clock using the same NTP-style protocol. Convergence is fast because clients already have a good time estimate.
• •Event timestamps, interpolation buffers, and gameplay timers all remain valid across the transition.

• →Fast Iteration Mode -- Speed up your development loop by skipping code generation.
• →Time Synchronization -- Deep dive into the NTP-style protocol and Golden Sample filtering.
• →Transport Layer -- The transport protocols that power GONet's networking.