clockworklabs / clockworklabs/SpacetimeDB

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

Open
#5,926 2 comments 3 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.