v3 websocket transport protocol by joshua-spacetime · Pull Request #4761 · clockworklabs/SpacetimeDB
This was referenced
Apr 8, 2026clockwork-labs-bot pushed a commit that referenced this pull request
Apr 12, 2026# Description of Changes Adds TypeScript SDK support for the `v3.bsatn.spacetimedb` websocket API which was added in #4761. `v3` just adds batching on top of `v2`, so adding support for it just required the following: 1. The client negotiates the protocol with the server and falls back to `v2` if necessary 2. When `v3` is negotiated, same-tick outbound client messages are batched into a single ws frame 3. Inbound `v3` server frames are unwrapped into their inner v2 messages and processed in-order Some notes on the batching behavior: 1. Outbound `v3` frames are capped at `256 KiB` (unless a single message exceeds the limit) 2. The SDK sends one v3 frame per flush 3. If more messages remain queued after hitting the cap, it schedules a follow-up flush on a later task instead of draining in a tight loop, so that outbound ws work doesn't starve inbound ws work or any other event-loop tasks # API and ABI breaking changes None, `v2` fallback remains supported, so existing servers that only negotiate `v2` still work with the updated client. # Expected complexity level and risk 3 Constraints that must hold: 1. Same-tick sends should coalesce under `v3` 2. `v2` should remain unaffected 3. Capped batching should not starve inbound processing 4. Server frames containing multiple logical messages must be processed in-order 5. Handshake fallback to `v2` must remain correct # Testing Added tests for the fast path and fallback behavior
joshua-spacetime
changed the title
v3 websocket protocol
v3 websocket transport protocol
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters