clockworklabs / clockworklabs/SpacetimeDB
Add a ping/pong Websocket message to support RTT and similar metrics
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 25.2k
- Forks
- 1.1k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 46
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the WebSocket protocol handling and SDK message definitions; the issue does not name specific files or tests. Compare the proposed Ping and Pong messages with the existing WebSocket Ping behavior and related issues #5525 and #5357. Done should include protocol support and SDK metrics for RTT, jitter, and estimated server time without measuring normal query processing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend-api-design, game-dev, networking
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100