Data tracks - outgoing manager by 1egoman · Pull Request #1810 · livekit/client-sdk-js

1egoman · 2026-02-10T19:03:38Z

This pull request introduces a new OutgoingDataTrackManager and the associated support infrastructure like LocalDataTrack to support sending data track packets from the web to the SFU.

…oming, which is incorrect and needs to be fixed!)

…correct, oops

Biggest fixed isssue: packetizer implementation payload seeking needed some updates because DataTrackFrame["payload"] is now Uint8Array, not ArrayBuffer.

ie, like: try { // ... } catch (e) { throw new WrapperErrorType(e); }

changeset-bot · 2026-02-10T19:03:46Z

🦋 Changeset detected

Latest commit: 2b70c4c

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	Patch

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

github-actions · 2026-02-10T19:05:15Z

size-limit report 📦

Path	Size
dist/livekit-client.esm.mjs	86.78 KB (+0.1% 🔺)
dist/livekit-client.umd.js	97.3 KB (+0.17% 🔺)

1egoman · 2026-02-10T19:30:24Z

@coderabbitai review

src/room/data-track/outgoing/errors.ts

1egoman · 2026-02-10T19:37:09Z

src/room/data-track/outgoing/errors.ts

+  // FIXME: this was introduced by web / there isn't a corresponding case in the rust version.
+  // Upon further reflection though I think this should exist in rust.
+  Cancelled = 6,


I have added a new DataTrackPublishErrorReason.Cancelled reason which is used when publishing a data track is aborted via an AbortSignal.

I think this might be potentially a good idea to add into the rust implementation as well, as I could see allowing cancellation of publishing a data track to be a nice behavior to pass up to the caller on the associated data track creation room method.

From 1:1 - this will be a web specific case for now, and the rust implicit cancellation behavior will be documented.

src/room/data-track/outgoing/OutgoingDataTrackManager.ts

1egoman · 2026-02-10T19:54:30Z

src/room/data-track/outgoing/OutgoingDataTrackManager.ts

+  /** Used by attached {@link LocalDataTrack} instances to broadcast data track packets to other
+   * subscribers.
+   * @internal
+   */
+  tryProcessAndSend(
+    handle: DataTrackHandle,
+    payload: Uint8Array,
+    options?: { signal?: AbortSignal },
+  ): Throws<
+    void,
+    | DataTrackPushFrameError<DataTrackPushFrameErrorReason.Dropped>
+    | DataTrackPushFrameError<DataTrackPushFrameErrorReason.TrackUnpublished>
+  > {
+    const descriptor = this.getDescriptor(handle);
+    if (descriptor?.type !== 'active') {
+      throw DataTrackPushFrameError.trackUnpublished();
+    }
+
+    const frame: DataTrackFrame = {
+      payload,
+      extensions: new DataTrackExtensions(),
+    };
+
+    try {
+      for (const packet of descriptor.pipeline.processFrame(frame)) {
+        this.emit('packetsAvailable', { bytes: packet.toBinary(), signal: options?.signal });
+      }
+    } catch (err) {
+      // FIXME: catch and log errors instead of rethrowing? That is what the rust implementation
+      // is doing instead.
+      // process_frame(...).inspect_err(|err| log::debug!("Process failed: {}", err))
+      // event_out_tx.try_send(...).inspect_err(|err| log::debug!("Cannot send packet to transport: {}", err));
+      //
+      // In the rust implementation this "dropped" error means something different (not enough room
+      // in the track mpsc channel)
+      throw DataTrackPushFrameError.dropped(err);
+    }
+  }


The behavior of this function is a bit different from the rust implementation right now, and I'm unsure exactly how it would be best to standardize this. The closest equivilent rust code is in DataTrack<Local>::try_push here and TrackTask::process_and_send here.

In rust, all the error cases here are logged (see the comments in the above code + the TrackTask::process_and_send link). The dropped error is returned when the frame_tx.try_send(...) in try_push fails.

In js, there is no frame_tx / TrackTask / etc because there isn't a need to run this across multiple processes (io is being handled in a non-blocking fashion and the computational requirements are minimal). So instead I opted to expose this dropped error as a wrapper around the debug logged errors.

I think the behavior should be aligned here, but if I go with the rust implemenattion's approach then I think there would never be a case where dropped gets thrown in the js implementation.

I agree, I think the Rust SDK needs to have better error reporting at the call site. Let's discuss this more in our 1:1.

From 1:1 -

@ladvoc rename dropped -> queueFull or something similar in rust

Consider renaming try_push

1egoman · 2026-02-10T20:08:17Z

src/room/data-track/handle.ts

@@ -57,24 +56,20 @@ export class DataTrackHandle {
    if (raw > U16_MAX_SIZE) {
      throw DataTrackHandleError.tooLarge();
    }
-    return new DataTrackHandle(raw);
-  }
-
-  constructor(raw: number) {
-    this.value = raw;
-  }
-}
+    return raw;
+  },
+};


This may prove controversial, but got rid of DataTrackHandle as a wrapper class and instead defined a type shadowing a const (docs about this) so I could continue to get the fromNumber static method, and could get the documentation benefits of being able to label the type as DataTrackHandle rather than number.

The reason I did it is because I wanted to key a map by a track handle, and I couldn't look up by this given the reference of the wrapper object would change every time it was newly constructed. ie:

class Wrapper { constructor(inner) { this.inner = inner; } } const map = new Map(); map.set(new Wrapper(5), 123); map.get(new Wrapper(5)); // -> undefined

Makes sense to me. Generally, I think it is ok to diverge from the patterns in the Rust implementation if they introduce complications here.

Sounds good.

FWIW, this is more of a comment for @lukasIO, last time I used this pattern he wasn't a fan.

src/room/data-track/track.ts

1egoman · 2026-02-10T20:12:19Z

src/room/utils.ts

 export class Future<T, E extends Error> {
-  promise: Promise<T>;
+  promise: Promise<Throws<T, E>>;

  resolve?: (arg: T) => void;


Just wanted to call out explicitly since it's a fairly important change - Future now uses the Throws<...> brand type internally, and anywhere a future.promise is awaited (assuming you are in a function which returns a Throws branded type) will now result in a linting error.

Because of that last limitation (throws-transformer is opt in within functions that return Throws<...>) this is scoped to data tracks code / doesn't cause errors all over the place.

1egoman · 2026-02-10T20:25:19Z

src/room/data-track/outgoing/OutgoingDataTrackManager.ts

+/** How long to wait when attempting to publish before timing out. */
+const PUBLISH_TIMEOUT_MILLISECONDS = 10_000;
+
+export default class OutgoingDataTrackManager extends (EventEmitter as new () => TypedEmitter<DataTrackOutgoingManagerCallbacks>) {


I called it OutgoingDataTrackManager to match with the OutgoingDataStreamManager. Also @ladvoc discussed this in a 1:1 and he was good with this name. For reference, the rust implementation (in the livekit-datatrack crate) calls this local::Manager.

I am not sure what the end name should be, but IMO given these two entities have very close to the same behavior, it would be good to align on a name.

Additional context for other reviewers: the only potential downside of this naming convention is the terms "local" and "remote" are still used in the public API (e.g. LocalTrack, RemoteTrack). However, since the track managers are internal components, I don't think this necessarily needs to be consistent. Will plan on renaming in Rust if there are no objections.

Both sound fine to me.
I like Outgoing for being very explicit about what it handles and like Local mainly for consistency with the public constructs

ladvoc

Generally looks good to me!

src/room/data-track/outgoing/errors.ts

src/room/data-track/outgoing/OutgoingDataTrackManager.test.ts

src/room/data-track/outgoing/OutgoingDataTrackManager.ts

ladvoc · 2026-02-11T01:50:14Z

src/room/data-track/outgoing/OutgoingDataTrackManager.ts

+/** How long to wait when attempting to publish before timing out. */
+const PUBLISH_TIMEOUT_MILLISECONDS = 10_000;
+
+export default class OutgoingDataTrackManager extends (EventEmitter as new () => TypedEmitter<DataTrackOutgoingManagerCallbacks>) {


Additional context for other reviewers: the only potential downside of this naming convention is the terms "local" and "remote" are still used in the public API (e.g. LocalTrack, RemoteTrack). However, since the track managers are internal components, I don't think this necessarily needs to be consistent. Will plan on renaming in Rust if there are no objections.

src/room/data-track/track.ts

ladvoc · 2026-02-11T03:44:44Z

src/room/data-track/handle.ts

@@ -57,24 +56,20 @@ export class DataTrackHandle {
    if (raw > U16_MAX_SIZE) {
      throw DataTrackHandleError.tooLarge();
    }
-    return new DataTrackHandle(raw);
-  }
-
-  constructor(raw: number) {
-    this.value = raw;
-  }
-}
+    return raw;
+  },
+};


Makes sense to me. Generally, I think it is ok to diverge from the patterns in the Rust implementation if they introduce complications here.

src/room/data-track/outgoing/types.ts

ladvoc · 2026-02-11T03:55:59Z

src/room/data-track/outgoing/OutgoingDataTrackManager.ts

+  /** Used by attached {@link LocalDataTrack} instances to broadcast data track packets to other
+   * subscribers.
+   * @internal
+   */
+  tryProcessAndSend(
+    handle: DataTrackHandle,
+    payload: Uint8Array,
+    options?: { signal?: AbortSignal },
+  ): Throws<
+    void,
+    | DataTrackPushFrameError<DataTrackPushFrameErrorReason.Dropped>
+    | DataTrackPushFrameError<DataTrackPushFrameErrorReason.TrackUnpublished>
+  > {
+    const descriptor = this.getDescriptor(handle);
+    if (descriptor?.type !== 'active') {
+      throw DataTrackPushFrameError.trackUnpublished();
+    }
+
+    const frame: DataTrackFrame = {
+      payload,
+      extensions: new DataTrackExtensions(),
+    };
+
+    try {
+      for (const packet of descriptor.pipeline.processFrame(frame)) {
+        this.emit('packetsAvailable', { bytes: packet.toBinary(), signal: options?.signal });
+      }
+    } catch (err) {
+      // FIXME: catch and log errors instead of rethrowing? That is what the rust implementation
+      // is doing instead.
+      // process_frame(...).inspect_err(|err| log::debug!("Process failed: {}", err))
+      // event_out_tx.try_send(...).inspect_err(|err| log::debug!("Cannot send packet to transport: {}", err));
+      //
+      // In the rust implementation this "dropped" error means something different (not enough room
+      // in the track mpsc channel)
+      throw DataTrackPushFrameError.dropped(err);
+    }
+  }


I agree, I think the Rust SDK needs to have better error reporting at the call site. Let's discuss this more in our 1:1.

…re to active descriptor type Per comment here: #1810 (comment)

…nterface

1egoman added 29 commits February 10, 2026 13:43

fix: get rid of DataTrackHandle wrapping class and make it just a number

5515699

fix: make Future<T, E> promise property use Throws

80d9044

docs: add Future docs comment

9443cef

feat: add initial incoming data tracks manager draft

6ef565f

feat: add initial data track pipeline for local data track (named inc…

712c779

…oming, which is incorrect and needs to be fixed!)

refactor: rename from incoming -> outgoing which I think is actually …

ec5330d

…correct, oops

feat: wire together local data track <-> outgoing manager

762706b

fix: update existing tests to get them to pass again

098101a

Biggest fixed isssue: packetizer implementation payload seeking needed some updates because DataTrackFrame["payload"] is now Uint8Array, not ArrayBuffer.

feat: add initial outgoing data track manager tests

e0946e3

refactor: separate out outgoing events

d7fec15

feat: get outgoing data tracks manager mostly tested

2c001a0

refactor: move events into separate file

7d14094

fix: run npm run format

d8a787f

feat: add data track publish timeout after 10s

2fd3eaa

feat: add in outgoing manager shutdown test

0129c66

fix: add a few FIXME comments to further ponder

c923d7c

refactor: move away fully from the manager input events pattern

6b3b653

refactor: move subscribeToEvents into its own file

899b0a8

refactor: move all errors into separate errors file

44fd5cd

refactor: rename DataTrackOutgoingManager -> OutgoingDataTrackManager

f582982

fix: add missing import

df8ba23

feat: add missing Throw error brands

35bf3d5

feat: add support for try/catch bare rethrowing to throws-transformer

fd64eb4

ie, like: try { // ... } catch (e) { throw new WrapperErrorType(e); }

fix: add missing throws branding

69c4561

fix: add throws ignore due to introduction of throws in Future

424438e

fox: run npm run format

98819fa

fix: remove unneeded error descriminator

3a85e17

fix: run npm run lint

379ee00

feat: add packet encryption test

dd43cfe

fix: add missing changeset

87ae505

fix: swap index import from packetizer -> OutgoingDataTrackManager

fe7e649

1egoman marked this pull request as ready for review February 10, 2026 19:09

fix: push empty commit to try to get the coderabbit bot to review

3087238

1egoman added 3 commits February 10, 2026 14:56

feat: add unpublishing descriptor shutdown case

2991109

fix: add more error cases

5d40107

docs: clarify docs comment

1827635

1egoman commented Feb 10, 2026

View reviewed changes

fix: add missing error cases

12aa217

ladvoc approved these changes Feb 11, 2026

View reviewed changes

1egoman mentioned this pull request Feb 11, 2026

Data tracks core livekit/rust-sdks#862

Open

1egoman added 7 commits February 11, 2026 10:22

feat: make assertions read a little better

9f852e5

feat: send unpublish event explicitly on cancellation

a90dfb9

feat: remove publishing descriptor type, instead add unpublishingFutu…

060155d

…re to active descriptor type Per comment here: #1810 (comment)

feat: get rid of lagging missing unpublishing case

0b97e14

feat: remove fixmes that have been addressed

878d5c6

fix: remove options from tryProcessAndSend

aea83e5

fix: remove options from tryPush and remove Throws type from public i…

2b70c4c

…nterface

1egoman merged commit 25418c8 into main Feb 20, 2026
6 checks passed

1egoman deleted the data-track-outgoing-manager branch February 20, 2026 15:05

This was referenced Feb 20, 2026

Version Packages #1818

Open

Version Packages wolfguidao/client-sdk-js#82

Open

1egoman mentioned this pull request Feb 20, 2026

Data tracks - incoming manager #1819

Open

github-actions bot mentioned this pull request Feb 18, 2026

Version Packages apnerve/client-sdk-js#123

Open

Comments

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

1egoman commented Feb 10, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

1egoman Feb 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!

1egoman Feb 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!

Uh oh!

1egoman Feb 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!

1egoman Feb 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!

ladvoc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

1egoman commented Feb 10, 2026 •

edited

Loading

changeset-bot bot commented Feb 10, 2026 •

edited

Loading

github-actions bot commented Feb 10, 2026 •

edited

Loading

1egoman Feb 10, 2026 •

edited

Loading

1egoman Feb 10, 2026 •

edited

Loading

1egoman Feb 10, 2026 •

edited

Loading

1egoman Feb 10, 2026 •

edited

Loading