Data track integration

[1egoman]

Integrates the data track managers (both incoming and outgoing) into the existing sdk Room and RemoteParticipant interfaces. Once this is merged, data tracks is fully implemented!

Interface - Publishing

const localDataTrack = await room.publishDataTrack({name: "data track name"});
await localDataTrack.tryPush(new Uint8Array(/* ... */));

// Once you are done with the local data track, it can be unpublished:
await localDataTrack.unpublish();

Interface - Subscribing

// There are two ways to get a remote data track, either a room event:
room.on(RoomEvent.RemoteDataTrackPublished, async (remoteDataTrack) => {
  // ...
});

// Or a new field on `RemoteParticipant`:
const remoteDataTrack = remoteParticipant.dataTracks.get("track name"); // Get a data track which has been published
const remoteDataTrack = await remoteParticipant.dataTracks.getDeferred("track name"); // Get a data track which _will_ be published shortly

// Either way, once you have a remoteDataTrack, you can subscribe:
const stream = await remoteDataTrack.subscribe(/* optional abort signal */);
for await (const frame of stream) {
  console.log(`Received bytes from ${remoteDataTrack.info.name}:`, frame.payload);
}

Todo:

• Decide on how to show the example app chart vs hexdump - show both? Just one? commit introducing chart.
• Add changeset

Resolves CLT-2582

[changeset-bot]

⚠️ No Changeset found

Latest commit: f63d21c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[github-actions]

size-limit report 📦

Path	Size
dist/livekit-client.esm.mjs	94.89 KB (+9.4% 🔺)
dist/livekit-client.umd.js	103.7 KB (+6.61% 🔺)

[lukasIO]

I guess this should error early (or warn and return) if isPublished is true?

[1egoman]

There is already an error that gets thrown within publishRequest if the track is already published, but I could probably make the error message a little nicer (right now it is one of those "panic" bare errors).

IMO in this case, I think an explicit throw makes sense because you really should not be publishing / unpublishing data tracks without some care. But looking at the existing tracks it looks like it just warns and that's it. So maybe it makes sense to convert this throw into a warning, not sure.

EDIT: more thoughts on this here!

[ladvoc]

From sync: giving some more thought to this, I would say publish should throw whereas unpublish should not. For publish, this is something the application might want to handle and respond to.

[lukasIO]

suggestion: might be enough to log a warning here and return early?

[1egoman]

Yea I am not sure - see my previous comment about the throw vs warning here. I like the hard error in that it is something that can be caught and explicitly handled though since this is checking an invariant. The existing track publication logic for audio / video tracks logs a warning so maybe it makes sense to update it to be consistent.

I guess one downside to the hard error is it opens this code up to a TOC-TOU issue where something like the below could happen:

if (track.isPublished) {
  // Imagine here the track is unpublished at the SFU level for some unrelated reason ...
  await track.unpublish(); // ... so this would then throw an error
}

I am definitely curious what others think here!

[ladvoc]

You make a good point; a data track unpublish can be SFU initiated (e.g., if publish data permission is revoked). Given that, I think it makes sense to treat this as a first-class error.

[lukasIO]

hm, from @1egoman 's description I'd be more inclined to treat it similarly to how other unpublish requests are handled, which is warning only

[lukasIO]

a couple of nits that would be nice to address.

More generally and important: what happens currently when running this against older servers that don't have DataTrack support?

[lukasIO]

what's the intention behind this differentiation? Why not just drop them for lossy?

[1egoman]

That's what I originally was doing but this didn't work for large data track payloads - here is some more context as to why from some notes I wrote up:

• If the _data_tracks rtc data channel buffer was full, the existing logic would drop packets (what the lossy data channel currently does).
  • This doesn't work though for data track packets, because if the first n packets of a frame get enqueued but the last packet(s) get dropped because there isn't enough room in the rtc data channel buffer, the receiver only receives a partial set of packets which will never fully decode into a data track frame.
  • If packets aren't buffered like this, then it becomes impossible to send data track payloads > ~75k bytes (the e2e tests are checking this case)
  • Solution (commit): buffer data track packets instead of dropping them if the rtc data channel buffer is full

If there's some other way to handle this, I'm open to alternatives but what I did here was the most straightforward way I could think of.