signalling: add compression envelopes for signal messages

[xianshijing-lk]

Proposal

Let signal messages on the WebSocket be compressed, the way WrappedJoinRequest already compresses the join payload in the connect URL. Adds a compressed arm to the SignalRequest / SignalResponse oneofs, carrying CompressedSignalRequest / CompressedSignalResponse and a shared SignalCompression.Type enum.

No negotiation handshake, no extra frames, no version gate. The receiver always parses a SignalRequest/SignalResponse; the oneof tag says whether the payload is compressed.

Draft — the proto compiles, but I'd like agreement on the shape before anyone implements against it.

Why

Everything after the handshake goes over the socket uncompressed. On the resume path that's where the bulk of the bytes are:

message	when	size
SyncState	every resume	two full SessionDescriptions + subscription / publish / data-channel lists
Offer (publisher ICE restart)	every resume	~5–6 KB
Offer/Answer (subscriber)	every resume	~5–6 KB
JoinResponse.other_participants	join	N × ParticipantInfo, unbounded via metadata/attributes

Measured against a real minimal one-audio/one-video offer: 5,734 bytes raw → 1,515 gzipped (3.8×).

Size isn't the only cost. Signalling is a single TCP connection, so a multi-kilobyte offer in flight head-of-line blocks everything queued behind it — including the trickle candidates the PeerConnection needs to finish its ICE restart. Compressing these directly shortens recovery on the degraded networks where recovery matters most.

How it works

message SignalResponse {
  oneof message {
    JoinResponse join = 1;
    ...
    CompressedSignalResponse compressed = 32;   // recursively, a SignalResponse
  }
}

Receiver parses SignalResponse. If it lands on compressed, it inflates signal_response and parses that as a SignalResponse. One level only; senders must not nest.

Senders use the arm only against a peer that advertised ClientInfo.CAP_COMPRESSION_DEFLATE_RAW — which clients already send today and nothing currently reads in livekit-server or cloud. An older peer would see an unknown field and silently drop the message, so the capability gate is load-bearing.

Below roughly 200 bytes, senders just use the ordinary arm — matching the threshold cloud/pkg/rtc/signal/compress.go:14 already uses internally.

Why this shape

Two earlier revisions in this branch, both worse:

1. Envelope + flag on JoinResponse. A receiver has to know whether a frame is a SignalResponse or a WrappedSignalResponse before reading anything out of it, so the agreement had to be established first — and the message establishing it couldn't itself be compressed. That permanently excluded the join roster, the biggest message in a large room.
2. Envelope + a SignalCompressionAck first frame. Fixed the above (no extra RTT — the server writes the ack and the JoinResponse back to back), but cost an extra message type and an extra frame.

As a oneof arm, the tag is the discriminator, so neither is needed. It's also cheaper on the wire: under an envelope, every message pays envelope overhead once compression is on, including small ones sent with compression = NONE. Here a small message is its ordinary arm and costs nothing, so the threshold has no downside.

Why not permessage-deflate

It would need no protocol change, and livekit-server already sets EnableCompression: true on the client-facing upgrader (pkg/service/rtcservice.go:76-77). But:

• No usable Rust WebSocket crate implements it. Checked tungstenite 0.29 (current), fastwebsockets 0.10, tokio-websockets 0.13 — none. Only soketto does, and it's a poor structural fit.
• It wouldn't reach SDKs where the host application supplies the WebSocket transport (Swift/Kotlin/Dart via livekit_net::set_ws_client). Each host would have to negotiate it independently.

Application-layer compression covers every transport uniformly, and mirrors what the SFU already does gzipping SignalRequest/SignalResponse on its own node-to-node transport.

Shape of the enum

SignalCompression is a holder message with a nested Type, rather than a top-level enum or an enum nested in each message:

• Top-level forces prefixed value names. Enum values follow C++ scoping and are siblings of their type, so a bare NONE collides with the one already in livekit_sip.proto — protoc rejects it outright.
• Nested per message avoids the prefix but yields two structurally identical, type-incompatible enums. Compression is naturally generic over direction — the SFU threads one compression type through both paths — so splitting it forces conversion code for no gain.
• Holder message gets both.

Values are numbered to match WrappedJoinRequest.Compression rather than to rank the options; two enums in one file where GZIP has different numbers invites mistakes.

Open questions

1. DEFLATE_RAW vs GZIP as the recommended default. Raw deflate saves gzip's ~18 bytes of header/trailer per message, which matters at a 200-byte threshold. Both WrappedJoinRequest and the SFU's internal path use gzip today. Recommendation, or mandate one?
2. The 200-byte threshold is documented as SHOULD, not enforced. Reasonable as guidance?
3. Capability gating. Reusing CAP_COMPRESSION_DEFLATE_RAW seemed right since it exists, is already advertised, and is read by nothing. But it was presumably minted for data streams — is overloading it acceptable, or would you rather have a distinct capability?

Notes

• protoc validates clean; Go codegen committed by the Generate workflow.
• Changeset included (minor for both Go and JS packages).
• No behaviour changes here — wire contract only. Client and server implementations follow.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 6febbf7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
github.com/livekit/protocol	Minor
@livekit/protocol	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR