v3 websocket transport protocol by joshua-spacetime · Pull Request #4761 · clockworklabs/SpacetimeDB

This was referenced

Apr 8, 2026

Centril

gefjon

clockwork-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 joshua-spacetime changed the title v3 websocket protocol v3 websocket transport protocol

Apr 14, 2026

@joshua-spacetime