Why does the graphql-ws subprotocol define its own ping and pong JSON messages?

## Two heartbeats, one connection WebSocket has a liveness mechanism built into the transport itself. The `graphql-ws` subprotocol nevertheless defines `ping` and `pong` as ordinary JSON **messages**, sent through the same channel as `subscribe` and `next`. Having two heartbeats on one connection looks redundant until you ask who is able to use each one, and that is exactly the question an interviewer is opening. ## The reason: the browser cannot reach the transport one A page's JavaScript gets a very narrow WebSocket API. It can open a connection, send and receive application data, and observe open, message, error and close. It cannot send the transport's own liveness probe, and it cannot observe one arriving. That machinery lives inside the browser and is not exposed. The consequence is concrete. A browser client that wants to answer "is this connection still alive, or has something in the middle quietly gone away?" has no transport-level tool to do it with. Its only option is to send something at the application layer and see whether a reply comes back. So the subprotocol gives it one. A second, more mundane reason: application messages are unambiguously traffic. Every layer that counts bytes, resets an idle timer or logs a message sees them. That is not always true of a transport-level probe, which some intermediaries handle without ever surfacing it to the application above. ## The rules, and they are short * Either side may send `ping` at any time, once the connection is acknowledged. * The receiver **must** reply with `pong` as soon as it reasonably can. * Both messages may carry an optional `payload` object, free-form. If a `ping` carried one, a courteous `pong` echoes it back — useful for correlating a reply with the probe that caused it. * A `pong` may be sent **unsolicited**, with no `ping` preceding it. That makes a one-way heartbeat legal: a client can simply emit a `pong` every N seconds purely as traffic. * Neither message carries an `id`. They are properties of the connection, not of any stream, and they are entirely independent of how many subscriptions are open. That last point is the one candidates get wrong most often. A `ping` says nothing about whether a particular subscription is still producing events; it says the socket and the two protocol implementations on either end of it are still talking. ## What it buys you in practice Three things, and it is worth naming them separately. **Detecting a dead peer.** A connection that has been severed somewhere in the middle — a NAT table entry expired, a machine went away without a close — looks exactly like an idle healthy one from either end. A client that pings on an interval and gives up if no `pong` returns within a deadline can reconnect in seconds instead of hanging until the operating system eventually gives up. **Keeping an idle connection from being reaped.** A subscription can legitimately produce nothing for a long time. In a clinical-trial registry graph, a feed of adverse events for one small study might emit twice a week; every layer in between sees a socket that has said nothing for hours and is entitled to conclude it is abandoned. Periodic `ping`/`pong` traffic prevents that judgement, and because it is application data rather than a transport probe, every layer counts it. **Measuring round-trip latency.** Send a `ping` with a timestamp in the payload, get it echoed in the `pong`, and you have a per-connection latency number that costs nothing and needs no instrumentation on the server. ## Choosing an interval The interval is a client and server setting, not a protocol constant, and the sensible way to pick one is to make it comfortably shorter than the shortest idle timeout anywhere on the path. The failure mode is asymmetric: too frequent costs a few bytes per connection, while too infrequent costs a reconnect storm when a proxy starts reaping sockets. At a peak of 1,200 new connection attempts per minute against the registry's public endpoint, a heartbeat that is a few seconds too slow is not a nuisance — it is the difference between a stable pool of long-lived sockets and a churn of clients reconnecting and re-subscribing. Do not confuse the heartbeat interval with the initialisation window, which is a different timer entirely: that one governs how long the server waits for the first message on a brand-new socket. ## The historical footnote The older `subscriptions-transport-ws` protocol approached this differently, with a server-emitted keep-alive message and no client-initiated probe. The move to a symmetric `ping`/`pong` pair, where either side can ask and either side must answer, is one of the meaningful improvements in the newer subprotocol — it lets the *client* be the one that decides the connection is dead, which is the side that can actually do something about it. None of this appears in the GraphQL specification, which defines no transport and therefore no heartbeat.