Data streams v2 by 1egoman · Pull Request #1985 · livekit/client-sdk-js

1egoman · 2026-06-23T20:57:53Z

Warning

This change relies on some new SFU updates to be able to function. Checkout main (really, livekit/livekit@86a79f8 or later), build + run the SFU locally, and point any test app at this local SFU for testing.

Overview

Data streams v2 consists of some 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

This pull request contains the initial web implementation and initial data streams spec which will be used to propagate this across all other client sdks.

Performance

Both 1 and 2 together at least doubles ⚠️ data stream throughput across the spectrum of network conenctions and payload sizes.

Before:

After:

TODO

Remove benchmark and spec before merging
Maybe make the changeset a minor release, not a patch? This is a fairly substantial change to a core sdk feature.
Cleanup cdc741a, I think I might need to rebase this

changeset-bot · 2026-06-23T20:57:57Z

🦋 Changeset detected

Latest commit: c3fd1ab

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

This PR includes changesets to release 1 package

Name	Type
livekit-client	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

1egoman · 2026-06-23T20:59:28Z

NOTE: The diff is quite large, and a big reason why it is is because I have both this example app AND the spec checked in. I'll remove these before an eventual merge which will make the diff a lot more reasonable.

Feel free to ignore this examples/data-stream-benchmark directory when reviewing.

1egoman · 2026-06-23T21:02:04Z

+/** The data-streams-v2 wire signals carried directly on the header: the compression flag and the
+ * inline single-packet payload. Both used to live in reserved header attributes; they are now
+ * first-class protobuf fields on `DataStream.Header`. */
+export interface StreamHeaderV2Fields {
+  /** Compression applied to the inline/chunked payload. Defaults to `NONE` when omitted. */
+  compression?: DataStream_CompressionType;
+  /** The full payload smuggled into the header for single-packet (inline) sends. */
+  inlineContent?: Uint8Array;
+}


Note to self: get rid of this and inline these two fields directly into the relevant function calls. Or name this something more generic if I decide to keep it.

1egoman · 2026-06-23T21:10:29Z

+      // set text part of progress to 1
+      handleProgress(1, 0);


Note to self: add some tests for the onProgress stuff. I'm not sure I've fully exercised it to make sure I didn't break anything here. Though worth noting I did find some bugs where in some paths onProgress wasn't being called before so I'm actually not convinced it was working properly before either.

Fixed this (sort of) in 4a6e2bb. It definitely works better than how it did before but I think there's still some work that could be done to improve it. Right now it measures bytes before the compression stage, which means that if the compressor were to take a long time it could potentially skew the progress.

1egoman · 2026-06-23T21:13:07Z

+    // FIXME: make this a global event to ensure "max listener" warning won't get logged for lots of
+    // in flight data streams.
    engine.once(EngineEvent.Closing, onEngineClose);


Note to self: fix this pre-existing bug as part of this larger change, I think right now there will me a "max listener" warning if you try to send too many data streams concurrently.

alternatively if the pattern is expected we can also bump the maxListener count.

I'm not a fan of just bumping the maxListener count, since you're just increasing the high water mark threshold. So IMO it either should be disabled (I forget if that's possible in the node EventEmitter implementation) or will address using a similar pattern as I did in waitForBufferStatusLow here.

yeah, the latter option sounds nice!

github-actions · 2026-06-25T16:58:43Z

size-limit report 📦

Path	Size
dist/livekit-client.esm.mjs	104.63 KB (+2.23% 🔺)
dist/livekit-client.umd.js	113.68 KB (+2.12% 🔺)

lukasIO

this is looking great already.

Really like that you consolidated a bunch of spread out things into helpers. Makes it a lot nicer to reason about.

lukasIO · 2026-06-27T13:17:56Z

+    // FIXME: make this a global event to ensure "max listener" warning won't get logged for lots of
+    // in flight data streams.
    engine.once(EngineEvent.Closing, onEngineClose);


alternatively if the pattern is expected we can also bump the maxListener count.

lukasIO

thanks for addressing all my comments!

yeongkyuyoon · 2026-07-02T02:58:35Z

Nice work!

Using sendText means that future optimizations to send a single data stream packet can be enabled.

…chanism

…a streams

…ream

…t / split into 15k MTU Doing this makes data arrive a bit faster since it's not waiting for compressed bytes to accumulate before sending out a "fully filled" packet

…am materialization

…ial stream materialization" This reverts commit 25af9bc.

…ntexts It's still not perfect - the progress events are reported pre-compressor right now so the compressor lag isn't taken into account directly (other than the side effect of it on future data "pulls" through the stream). But I think it's an improvement over the previous state of just 0 -> 1.

…hed streams

This is set fairly high and will prevent any malicious decompression bomb style payloads

…malEnd

lukasIO

great work!

just some questions around the NonSharedUint8Array usage, there are some internal Uint8Arrays declared directly in some places

…8Array in all data stream utility functions

1egoman requested review from lukasIO and xianshijing-lk as code owners June 23, 2026 20:57

This comment was marked as resolved.

Sign in to view

1egoman commented Jun 23, 2026

View reviewed changes

1egoman requested a review from ladvoc June 23, 2026 21:19

lukasIO reviewed Jun 25, 2026

View reviewed changes

Comment thread DATA_STREAMS_SPEC.md Outdated

Comment thread DATA_STREAMS_SPEC.md Outdated

Comment thread DATA_STREAMS_SPEC.md Outdated

Comment thread DATA_STREAMS_SPEC.md Outdated

Comment thread DATA_STREAMS_SPEC.md Outdated

Comment thread DATA_STREAMS_SPEC.md Outdated

1egoman force-pushed the data-streams-v2 branch from a146641 to deb8b57 Compare June 25, 2026 16:56

1egoman mentioned this pull request Jun 26, 2026

Data streams v2 livekit/rust-sdks#1192

Open

lukasIO reviewed Jun 27, 2026

View reviewed changes

xianshijing-lk reviewed Jun 29, 2026

View reviewed changes

Comment thread src/room/data-stream/incoming/IncomingDataStreamManager.ts Outdated

xianshijing-lk reviewed Jun 30, 2026

View reviewed changes

lukasIO approved these changes Jul 1, 2026

View reviewed changes

eeegoloauq mentioned this pull request Jul 6, 2026

Concurrent sendFile() calls can kill the reliable data channel #1995

Closed

This comment was marked as resolved.

Sign in to view

1egoman mentioned this pull request Jul 10, 2026

add e2e signalling tests #1998

Open

This comment was marked as resolved.

Sign in to view

1egoman added 11 commits July 20, 2026 15:30

refactor: rename constant

def3c98

fix: make rpc use datastream.sendText, NOT streamText

9f467c4

Using sendText means that future optimizations to send a single data stream packet can be enabled.

fix: convert rpc tests from streamText -> sendText

632f551

feat: add initial support for single packet data streams via hacky me…

b90d2ee

…chanism

feat: add backwards compatibility back in for old multi packet v1 dat…

cb4a54a

…a streams

feat: check all participants in room before broadcasting a v2 data st…

2d7936f

…ream

feat: add initial data stream benchmark app

a18007c

feat: add missing constants file

578dbd8

feat: add initial data stream compression implementation

7c35a52

feat: migrate compression to get rid of "pump" and compress per packe…

aac267b

…t / split into 15k MTU Doing this makes data arrive a bit faster since it's not waiting for compressed bytes to accumulate before sending out a "fully filled" packet

fix: swap else if -> switch/case

c7acc6b

1egoman added 20 commits July 20, 2026 15:30

fix: add log when unknown compression scheme encountered

e4b07a5

fix: convert intermedite streams to transformstream

2b034a7

fix: port compression to use TransformStream

2280836

feat: add zero length single packet data stream tests

dc69bf7

fix: swap break for return

1536956

fix: ensure data stream payload will only ever be compressed once

21426e2

fix: address lint error

7f48881

feat: add name / mimeType to new sendBytes method

b432685

docs: update CompressedStreamState docstring

1edcb68

feat: add compressedStream.lengthLargerThan to allow for partial stre…

a3ffb95

…am materialization

Revert "feat: add compressedStream.lengthLargerThan to allow for part…

27f4afd

…ial stream materialization" This reverts commit 25af9bc.

refactor: rename CompressedStreamState -> MaybeCollectedStream

9dca376

fix: address flipped stream controllers check

3d3e26c

fix: make sure textStreamControllers always cleaned up

f45fadc

fix: ensure destinationIdentities / compress forwarded along to attac…

2c23c34

…hed streams

feat: add max payload byte size limit to data streams

fc53b23

This is set fairly high and will prevent any malicious decompression bomb style payloads

fix: surface an abnormal data stream trailer close reason as an Abnor…

52734f1

…malEnd

feat: add new test cases for incoming / outgoing data stream handling

902b960

fix: adjust uint8array cast to get ci to pass

c8e0790

1egoman force-pushed the data-streams-v2 branch from cdc741a to 902b960 Compare July 20, 2026 19:31

lukasIO approved these changes Jul 22, 2026

View reviewed changes

Comment thread src/room/data-stream/incoming/IncomingDataStreamManager.ts

Comment thread src/room/utils.ts Outdated

Comment thread src/room/utils.ts Outdated

Comment thread package.json Outdated

1egoman added 2 commits July 22, 2026 09:46

feat: lift NonSharedUint8Array casts further up and use NonSharedUint…

a0e4921

…8Array in all data stream utility functions

fix: upgrade @livekit/protocol to 1.50.4

0d41037

1egoman mentioned this pull request Jul 22, 2026

Port data streams over to rust livekit-ffi version livekit/node-sdks#697

Draft

2 tasks

1egoman added 2 commits July 23, 2026 09:45

fix: adjust changeset to minor

f291fd8

fix: remove data streams spec and benchmark before merging

c3fd1ab

1egoman merged commit 2c45da1 into main Jul 23, 2026
6 checks passed

1egoman deleted the data-streams-v2 branch July 23, 2026 14:06

github-actions Bot mentioned this pull request Jul 23, 2026

Version Packages #2016

Merged

Uh oh!

Conversation

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

Uh oh!

Overview

Performance

TODO

Uh oh!

changeset-bot Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

This comment was marked as resolved.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1egoman Jun 29, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

size-limit report 📦

Uh oh!

lukasIO left a comment

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!

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!

lukasIO left a comment

Choose a reason for hiding this comment

Uh oh!

yeongkyuyoon commented Jul 2, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

lukasIO left a comment

Choose a reason for hiding this comment

Uh oh!

1egoman commented Jun 23, 2026 •

edited

Loading

changeset-bot Bot commented Jun 23, 2026 •

edited

Loading

1egoman Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 25, 2026 •

edited

Loading