Data streams v2 by 1egoman · Pull Request #1192 · livekit/rust-sdks

1egoman · 2026-06-26T20:26:48Z

Overview

This change introduces data streams v2, a set of major updates to data streams to add three things:

Single packet data streams for short (< 15kb), finite length payloads
DEFLATE compression, when both the sender and all receivers support compression/decompression
A maximum 15kb size for data stream attributes to close this as a DOS vector

For information about important decisions made in data streams v2, see the spec. In particular, parts 1-5 provide a good high level overview of data streams v1 + v2, what these protocol improvements are aiming to acheive, and why certain choices were made when designing the protocol.

Also maybe of interest is the corresponding web sdk pull request.

These updates are fully backwards compatible - the sdk will fall back to data streams v1 whenever an old participant is in the room.

There is also a significant amount of new test coverage to data streams (both v1 and v2). There were some small bugs I found along the way which I fixed as well.

github-actions · 2026-06-26T20:27:17Z

Changeset

The following package versions will be affected by this PR:

Package	Bump
`livekit`	`patch`
`livekit-api`	`patch`
`livekit-datatrack`	`patch`
`livekit-ffi`	`patch`
`livekit-protocol`	`patch`
`livekit-uniffi`	`patch`

1egoman · 2026-06-26T20:29:54Z

 bytes = "1.10.1"
 bmrng = "0.5.2"
+flate2 = "1"
 base64 = "0.22"


Note that flate2 is now a required dependency of livekit. Previously it was an optional dependency of livekit-api but that's it.

Not sure if this is is worth doing yet, but it might be worth adding a "compression" feature to this crate to conditionally include this dep. It would be enabled by default, but would provide users who do not want compression to disable it at the feature level.

I lean towards not doing it and adding it later if people wanted to opt out. But, I could be convinced otherwise if there's a really good use case. Also, in case it's relevant, flate2 is ~80kb.

My concern would be more how it affects compile time and binary size; probably insignificant but it might be worth checking with cargo build --timings and cargo bloat --release --crates (crate) respectively.

1egoman · 2026-07-06T20:48:59Z

 }

-pub(crate) enum AnyStreamReader {
+pub enum AnyStreamReader {


Note to reviewers - some of the visibilities on some of these members had to change now that livekit-data-tracks is exposing previously crate-internal members so they can be pulled in by other crates. From the perspective of a consumer of the livekit crate, all members should have the same visibility as before.

1egoman · 2026-07-06T20:51:53Z

+#[derive(Clone, Default, Debug, Eq, PartialEq)]
+pub struct StreamTextOptions {
+    pub topic: String,
+    pub attributes: HashMap<String, String>,
+    pub destination_identities: Vec<ParticipantIdentity>,
+    pub id: Option<String>,
+    pub operation_type: Option<OperationType>,
+    pub version: Option<i32>,
+    pub reply_to_stream_id: Option<String>,
+    pub attached_stream_ids: Vec<String>,
+    pub generated: Option<bool>,
+    /// Whether to deflate-raw compress the payload when all recipients support it.
+    /// Defaults to `true` (compression opt-out). Ignored by the incremental `stream_text`.
+    pub compress: Option<bool>,
+}


Note to reviewers: compress is a new field but otherwise this should be identical. Should I introduce a new builder style construction pattern here and for StreamByteOptions?

devin-ai-integration

Devin Review found 2 potential issues.

devin-ai-integration · 2026-07-06T21:19:10Z

+        self.0.outgoing_stream_manager.send_text(text, options, self.0.as_ref()).await
    }

    fn server_version(&self) -> Option<String> {


🔍 Inverted logic in server_version() will skip version checks or panic

The server_version() method at livekit/src/room/rpc/mod.rs:112 uses .and_then(|info| info.version.is_empty().then(|| info.version)) which returns Some(version) only when the version string IS empty, and None when it's non-empty. This is inverted from the intended behavior. When a server reports a valid version like "1.9.0", the method returns None, so the minimum-version check at livekit/src/room/rpc/client.rs:60-66 is skipped entirely. When the server reports an empty version, it returns Some(""), causing Version::parse("").unwrap() to panic. The fix should be (!info.version.is_empty()).then(|| info.version). This is pre-existing (not introduced by this PR) but is in the same impl block that was refactored.

Was this helpful? React with 👍 or 👎 to provide feedback.

This might be an unrelated bug? My change didn't touch server_version().

devin-ai-integration

Devin Review found 1 new potential issue.

devin-ai-integration · 2026-07-08T19:25:40Z

+        let inline_content = header.inline_content.take();
+        let is_compressed = header.compression() == proto::CompressionType::DeflateRaw;
+
+        let Ok(info) = AnyStreamInfo::try_from_with_encryption(header, encryption_type.into())


🟡 Receive-side inline detection always reports false under the end-to-end test feature

The inline-content field is stripped from the header (header.inline_content.take() at livekit-data-stream/src/incoming/mod.rs:140) before the stream-info struct is constructed, so the test-only is_inline diagnostic is always false on the receive side.

Impact: The is_inline field on received stream info is always wrong under the __e2e-test feature, making it impossible to assert inline delivery from the receiver's perspective.

Mechanism: inline_content taken before info construction

At livekit-data-stream/src/incoming/mod.rs:140, header.inline_content.take() moves the inline content out of the header into a local variable. The header (now with inline_content = None) is then passed to AnyStreamInfo::try_from_with_encryption at line 143, which calls ByteStreamInfo::from_headers_with_encryption or TextStreamInfo::from_headers_with_encryption.

In those functions (livekit-data-stream/src/info.rs:133 and livekit-data-stream/src/info.rs:162), the __e2e-test feature checks !header.inline_content().is_empty() to set is_inline. Since inline_content was already taken, this always returns an empty slice, so is_inline is always false.

The current e2e tests only check is_inline on the sender's returned StreamInfo (not the receiver's), so no test currently fails. But the receive-side diagnostic is silently broken.

Was this helpful? React with 👍 or 👎 to provide feedback.

Breaks out a subset of the changes from #1192 into a pull request which exclusively moves the existing data streams implementation into its own crate, `livekit-data-streams`, and adds a new `livekit-common` crate (kept fairly minimal for now) for common utilities which `livekit-data-streams` and `livekit` both need. This is largely being scoped to a "lift and shift" type effort, more extensive refactoring of the `livekit-data-streams` crate will be done in #1192. ### Breaking changes There should not be any breaking changes from the perspective of `livekit`'s public api. If so, please surface them. ### Testing This pull request adds the relevant v1 data streams tests from #1192. More test coverage will be introduced as a follow up in the data streams v2 change. --------- Co-authored-by: Jacob Gelman <3182119+ladvoc@users.noreply.github.com>

…stry, and CLIENT_PROTOCOL_DATA_STREAM_V2 from livekit-common" This reverts commit ee02f26.

…est-utils" This reverts commit 8e956b4.

…llectedAsyncReader

…ing the protobufs This local layer matches how livekit-datatrack works and gives us space to make local decoupled schema updates without effecting the public types.

…ata tracks

These are used in a few spots and are fairly compression specific. It would be nice to not duplicate them.

1egoman · 2026-07-10T16:43:24Z

+            // A gap is unrecoverable for a stateful decompressor.
+            let expected = descriptor.last_chunk_index.map(|i| i + 1).unwrap_or(0);
+            if chunk.chunk_index != expected {
+                inner.close_stream_with_error(&id, StreamError::MissedChunk);
+                return;
+            }
+            descriptor.last_chunk_index = Some(chunk.chunk_index);
+


question: should descriptor.last_chunk_index be an Option<AtomicU64> rather than a Option<u64>? Not directly related to my change but I noticed this scanning through.

1egoman · 2026-07-10T17:32:53Z

+/// Reader for an incoming byte data stream.
+pub struct ByteStreamReader {
+    info: ByteStreamInfo,
+    chunk_rx: UnboundedReceiver<StreamResult<Bytes>>,
+}
+
+/// Reader for an incoming text data stream.
+pub struct TextStreamReader {
+    pub(crate) info: TextStreamInfo,
+    chunk_rx: UnboundedReceiver<StreamResult<Bytes>>,
+}


Note to self - investigate if there's a good reason for pub(crate) info vs info here between these two structs.

1egoman · 2026-07-10T18:00:44Z

+        self.0.outgoing_stream_manager.send_text(text, options, self.0.as_ref()).await
    }

    fn server_version(&self) -> Option<String> {


This might be an unrelated bug? My change didn't touch server_version().

1egoman · 2026-07-10T18:24:11Z

+#[derive(Clone)]
+pub struct Manager {
+    /// Request channel for sending packets.
+    packet_tx: UnboundedRequestSender<proto::DataPacket, Result<(), SendError>>,
+}


Note to reviewers - the outgoing manager isn't an "actor", while the incoming one is. This was a conscious choice, since the outgoing one is being used in an already async context where .awaiting the calls into this manager is fine, while the incoming one is not. The actor machinery (events, channels, etc) adds a lot of complexity which is why I didn't opt to do it to the outgoing one pre-emptively.

I'm open to alternatives here though.

…rd task shuts down

1egoman commented Jun 26, 2026

View reviewed changes

ladvoc reviewed Jun 26, 2026

View reviewed changes

Comment thread livekit/src/prelude.rs Outdated

ladvoc reviewed Jun 26, 2026

View reviewed changes

Comment thread livekit/src/room/participant/remote_participant.rs Outdated

ladvoc reviewed Jun 26, 2026

View reviewed changes

Comment thread livekit/src/room/participant/mod.rs Outdated

1egoman mentioned this pull request Jun 29, 2026

Add participant capabilities to participant list livekit-examples/rust-dev-client#19

Draft

1 task

1egoman force-pushed the data-streams-v2 branch 3 times, most recently from 3bf1532 to d9e9bb3 Compare July 6, 2026 20:05

1egoman commented Jul 6, 2026

View reviewed changes

1egoman marked this pull request as ready for review July 6, 2026 21:15

1egoman requested review from MaxHeimbrock, alan-george-lk, lukasIO, stephen-derosa and xianshijing-lk as code owners July 6, 2026 21:15

devin-ai-integration Bot reviewed Jul 6, 2026

View reviewed changes

1egoman mentioned this pull request Jul 7, 2026

Move data streams into their own crate #1227

Merged

1egoman force-pushed the data-streams-v2 branch from 15c2d7b to 9daf2a9 Compare July 8, 2026 19:21

1egoman marked this pull request as draft July 8, 2026 19:22

1egoman removed request for MaxHeimbrock, alan-george-lk, lukasIO, stephen-derosa and xianshijing-lk July 8, 2026 19:23

1egoman changed the base branch from main to data-streams-refactor July 8, 2026 19:24

devin-ai-integration Bot reviewed Jul 8, 2026

View reviewed changes

Base automatically changed from data-streams-refactor to main July 9, 2026 20:00

feat: commit initial data streams v2 implementation

3c87f5f

1egoman added 12 commits July 9, 2026 16:31

refactor: reformat somewhat_compressible to use rand

d0cbfc3

Revert "refactor: drop unused ClientCapability, RemoteParticipantRegi…

b0ffd9e

…stry, and CLIENT_PROTOCOL_DATA_STREAM_V2 from livekit-common" This reverts commit ee02f26.

Revert "refactor: merge livekit-data-stream __e2e-test feature into t…

73e7afd

…est-utils" This reverts commit 8e956b4.

fix: drop duplicate outgoing test helpers introduced by rebase merge

ad00257

refactor: use livekit_common::enum_dispatch in data-stream info dispatch

1902c2a

feat: add async-compression and thread it through via the new MaybeCo…

7960420

…llectedAsyncReader

feat: add new local struct / enum layer in livekit-data-stream mirror…

cffaf36

…ing the protobufs This local layer matches how livekit-datatrack works and gives us space to make local decoupled schema updates without effecting the public types.

refactor: port outgoing data stream manager to use new packet types

c95bd3f

feat: convert incoming data stream manager to actor

0df6add

fix: address typos in test only data stream fields

05ad3b5

refactor: rename {Incoming,Outgoing}StreamManager -> *DataStreamManager

44c6bce

fix: run cargo fmt

2552a56

1egoman force-pushed the data-streams-v2 branch from 339361a to 2552a56 Compare July 9, 2026 20:34

1egoman added 11 commits July 9, 2026 16:42

docs: remove out of date data stream comments

08c9e9a

refactor: re-organize data streams v2 changes to more closely match d…

7000fcd

…ata tracks

refactor: move INTERNAL_DATA_STREAM_TOPICS to reduce diff complexity

0ad5c31

fix: swap custom random generation for standard rand crate usage

4bf538d

fix: rename identifier to have a unit

5308924

refactor: centralize data streams test random noise generation helpers

71b3843

These are used in a few spots and are fairly compression specific. It would be nice to not duplicate them.

refactor: remove flate2 from livekit-data-streams

c1e6867

fix: remove remnants of __e2e-test livekit-data-stream feature

b1817d4

refactor: change variable names and reindent

dd6a9d1

fix: remove prost typos

2dc9945

fix: add missing test_utils module

571c558

1egoman commented Jul 10, 2026

View reviewed changes

1egoman marked this pull request as ready for review July 10, 2026 18:33

fix: run cargo fmt

16c39e7

This comment was marked as resolved.

Sign in to view

fix: ensure that data stream outgoing manager is shut down when forwa…

9ea67bc

…rd task shuts down

Uh oh!

Conversation

1egoman commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Uh oh!

github-actions Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changeset

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1egoman Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1egoman Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

1egoman commented Jun 26, 2026 •

edited

Loading

github-actions Bot commented Jun 26, 2026 •

edited

Loading

1egoman Jul 6, 2026 •

edited

Loading

devin-ai-integration Bot Jul 6, 2026 •

edited

Loading

devin-ai-integration Bot Jul 8, 2026 •

edited

Loading

1egoman Jul 10, 2026 •

edited

Loading