Service Registry, Heartbeats, Drain, And Shutdown

Service registry lifecycle describes how login and game instances announce themselves, refresh TTL-backed records, enter drain, deregister, and tolerate shutdown races.

Purpose

Use this page when control-plane allocation sees stale instances, a draining server still receives players, or shutdown leaves registry members behind.

Registry Record Shape

Registry records include service name, instance id, placement, endpoint set, capacity, active counts, zone allocation records, tick health, version, and incarnation data. The Redis set is an index; the payload key is the current truth.

Startup Gates By Service

Control plane must be available before registration can succeed. Login registers itself and requests game assignment. Game server registers endpoint health, capacity, zones, and transport capabilities after startup readiness checks.

Heartbeat TTL

Heartbeats rewrite registry payloads with TTL. If a service stops heartbeating, payload keys expire and registry reads prune stale set members.

Drain State In Allocation

Drain state should prevent new allocation while allowing in-flight cleanup. A draining game server should keep reporting enough state for operators to see why allocation avoided it.

Deregistration And Shutdown Races

Clean shutdown should deregister. Crashes rely on TTL expiry and stale member pruning. Do not assume a registry set member means the instance is alive without reading the payload.