Add a ping/pong Websocket message to support RTT and similar metrics

[krisajenkins]

Game developers building on SpacetimeDB want to know their connection's round-trip time, how much it jitters, and what time the server thinks it is. These are pretty standard metrics for a game's networking layer, feeding lag compensation, interpolation and "ping" displays.

The server already sends WebSocket Ping frames, but browsers never expose control frames to JavaScript (as #5525 notes), and none of the SDKs surface them. So users are building their own: Pogly runs a ping/pong system on top of ours (see #5357). Others time reducer calls, which counts reducer queueing and runs a transaction every time. The /unstable/timestamp route (#2864) gives a clock reading, but over a separate HTTP connection.

We propose adding a dedicated Ping client message and Pong server message to the protocol. The Pong echoes the client's send time and adds the server receive Timestamp and how long the server held the message before replying. The server should answer Pings ahead of the normal message handler, which runs Subscribe and OneOffQuery inline, so the measurement doesn't include query evaluation.

The SDKs then derive the metrics below, using RFC 6298 smoothing for RTT and taking the clock offset from the lowest-RTT samples.

Metric	Meaning
rtt	Smoothed round-trip time (RFC 6298 SRTT)
rttLatest	Most recent sample
rttMin	Minimum over the recent sample window
jitter	RTT variation (RFC 6298 RTTVAR)
serverNow()	Estimated server Timestamp, on the same clock as ctx.timestamp; adjusts gradually and never goes backwards

Related:
This would be independent of QUIC support (#2619), but complementary. We need the RTT for Websockets regardless, but QUIC's independent datastreams would be a very natural fit.

[krisajenkins]

For a production example, here's how BitCraft does it today.

Clock sync. At login, the client makes 20 sequential GET /v1/database/:name/unstable/timestamp requests. For each one it computes offset = local_receive_time − server_timestamp − rtt/2, then uses the median. It only resyncs when the server rejects a move with "Invalid timestamp", and at most once a minute. So the clock is sampled over a separate HTTP connection, and drift is only noticed once it breaks gameplay.

Latency display. A debug overlay shows:

• an ICMP ping to the region host (one sample, measuring the network path only)
• reducer and subscription latency from the C# SDK's conn.stats. The SDK records DateTime.UtcNow when it sends a request, matches the response by request_id, and stops the clock when the response starts arriving on the WebSocket. It keeps only the min and max for each time window. For reducers, this includes queueing and execution on the server.

Neither gives a continuous RTT or jitter figure for the WebSocket itself.

[krisajenkins]

So it's possible to estimate RTT and server time with what we currently have, but it's flawed. BitCraft uses ICMP, HTTP and WebSocket reducer timings for separate best-effort measurements, and each one measures something slightly different from the real connection. To be accurate, the ping has to travel over the same WebSocket connection as regular messages, and the server has to answer it ahead of normal message handling.

Extending the protocol would be fairly easy and mostly safe. Old clients would work fine with updated servers, because they never send a Ping and so never receive a Pong. A new client talking to an outdated server would be disconnected when it sends its first Ping. That seems acceptable.

The SDKs should then do the smoothing and clock-offset maths, so clients don't each reinvent it.