Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion client-sdk-rust
Submodule client-sdk-rust updated 167 files
57 changes: 57 additions & 0 deletions data-track-dynacast-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Data track dynacast in the C++ SDK

A data track carries a stream of application data. A subscriber is a participant who requests that stream. See the [LiveKit data track guide](https://docs.livekit.io/transport/data/data-tracks/).

Dynacast pauses sending when the server reports zero subscribers. The track stays published, so participants can still find it and subscribe. Rust rejects new frames while sending is paused.

## Match the upstream behavior

The C++ SDK currently pins Rust commit `2811b4be`. The local Rust branch `ladvoc/data-track-dynacast` adds `NO_SUBSCRIBERS` to the protocol in `b4ef0127`. The corresponding server branch sends a Boolean that reports whether a track has any subscribers. Rust accepts pushes until the server reports that the track has zero subscribers. A server that sends no updates keeps the existing behavior.

Use a released Rust revision that includes the demand update and the new error code. The demand update is the server message about subscribers. Use a compatible LiveKit Server release for the end-to-end test. The current test server pin, `v1.13.3`, lacks the demand update in the local server source. Record both release versions before enabling the new test in CI.

## Change the C++ SDK

Add `LocalDataTrackTryPushErrorCode::NO_SUBSCRIBERS = 5` in `include/livekit/data_track_error.h`. Keep the existing numeric values. Map the new protocol code in `src/data_track_error.cpp` and preserve the message from Rust. Let the SDK build generate the C++ protocol code from the Rust revision.

Keep the subscriber state and the decision to accept frames in Rust. Keep `RoomOptions::dynacast` for video. Document the new error on all three `LocalDataTrack::tryPush()` overloads. Explain that callers can drop that frame and try again with a fresh frame. Preserve the success result for an empty payload on a valid handle.

## Test the behavior

### Unit test

A unit test exercises one function without a server. Add one case to `src/tests/unit/test_data_track_error.cpp`. Pass the new protocol error to `LocalDataTrackTryPushError::fromProto()`. Make sure that it returns `NO_SUBSCRIBERS` and preserves the message. Keep the existing test for the `UNKNOWN` fallback.

### Integration test

An integration test exercises the C++ and Rust boundary. Extend `UnpublishUpdatesPublishedStateEndToEnd` in `src/tests/integration/test_data_track.cpp`. After unpublish, make sure that a nonempty `tryPush()` returns `TRACK_UNPUBLISHED`. Make sure that an empty `tryPush()` still succeeds on the same handle. Retain the published-state assertions and remove the fixed delay before unpublish.

### End-to-end test

An end-to-end test exercises two SDK clients through a live server. Extend `CanResubscribeToRemoteDataTrack` in the same file. Use one publisher and one subscriber. After publication, wait for `NO_SUBSCRIBERS` and make sure that the track stays published. Subscribe and make sure that the receiver gets a fresh frame with the expected data. Close the subscription and wait for `NO_SUBSCRIBERS` again. Subscribe again and make sure that the receiver gets a frame with a different marker.

Use the existing fixture and a bounded wait for each state change. During subscription changes, allow `NO_SUBSCRIBERS` while waiting for the next frame. Fail on any other push error. Use one thread to call `tryPush()` and close streams on timeout to release blocked readers. Run this case in the existing `e2e-testing` jobs with the compatible server pin.

## Update callers and measure cost

Keep `PublishManyTracks` focused on publication and unpublication. Use an active subscriber in the memory test to preserve its coverage of frame enqueueing. In delivery tests, retry with fresh frames if `NO_SUBSCRIBERS` occurs before subscription takes effect. Keep other push failures visible.

Use `benchmarks/data_track_throughput` to compare the current and updated SDK with one active subscriber. Measure accepted frames per second and the time from send to receipt under the same load. Use the same payload size and push rate with zero subscribers. Count `NO_SUBSCRIBERS` separately from queue-full errors and record the time per push. Disable per-frame error logging for the expected no-subscriber result during the measurement.

## Verify before merging

Initialize the shared tools with `git submodule update --init cpp-tools`. If the root `.clang-format` and `.clang-tidy` links are missing, run `./cpp-tools/install.sh`. Initialize the Rust submodule and its dependencies at the selected revision. Build with `./build.sh debug-tests` or `build.cmd debug-tests` on Windows. Run `source scripts/set-test-tokens.sh` before the test commands. Run the targeted tests and the existing supported-platform test matrix.

Run `./scripts/generate-docs.sh` to build the API reference. Run the formatter and static analysis commands in `docs/tools.md`.

With the updated SDK, run the existing data track delivery test once against `v1.13.3`. Use this run to make sure that delivery still works on a server that sends no demand updates. Record the server version, test results, and benchmark results in the pull request.

## Local verification results

On macOS, the pinned Rust build passed 364 unit tests and skipped the new protocol mapping test. LiveKit Server `v1.13.3` passed all 27 data track integration tests in that build. The preview Rust build passed all 365 unit tests and three compatibility tests against `v1.13.3`. The preview pair passed 28 data track integration tests, including the dynacast test. The dynacast test also passed five consecutive runs. The memory tester passed a syntax build, and its runtime test still needs Linux.

The preview used Rust `84a7d969` and LiveKit Server `50304fd0`. Both upstream changes still need releases before the default build and CI can enable dynacast. [Rust change](https://github.com/livekit/rust-sdks/pull/1696) · [Server change](https://github.com/livekit/livekit/pull/4656)

The benchmark sent 300 frames of 1 KiB at 100 frames per second on the preview server. With one subscriber, both builds accepted about 100 frames per second. The pinned build delivered 300 frames, and the preview delivered 299 frames. Median delivery time was 1.82 ms for the pinned build and 2.04 ms for the preview. The 95th percentile was 2.89 ms for the pinned build and 3.23 ms for the preview.

With zero subscribers, the pinned build accepted all 300 pushes and averaged 133 microseconds per push. The preview returned `NO_SUBSCRIBERS` for all 300 pushes and averaged 119 microseconds per push. Neither run returned `QUEUE_FULL`.
19 changes: 17 additions & 2 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,20 @@ LIVEKIT_CONFIG="enable_participant_data_blob: true"
livekit-server --dev
```

### Data track dynacast

The dynacast test needs a Rust core with `NO_SUBSCRIBERS` and a server that
sends data track demand updates. The current release pins lack this support.
With compatible builds, run the test from the repository root.

```bash
source scripts/set-test-tokens.sh
LIVEKIT_TEST_DATA_TRACK_DYNACAST=1 ./build-debug/bin/livekit_integration_tests \
--gtest_filter=DataTrackE2ETest.DynacastPausesAndResumesDataTrack
```

The test fails if the publisher never reports `NO_SUBSCRIBERS`.

## Environment variables

The integration and stress test suites (data tracks, RPC, media multistream,
Expand Down Expand Up @@ -196,8 +210,9 @@ or groups of scenarios:
track, captures synthetic PCM frames, unpublishes, disconnects, and shuts down.
- `video-track` repeatedly initializes the SDK, connects, publishes a video
track, captures synthetic I420 frames, unpublishes, disconnects, and shuts down.
- `data-track` repeatedly connects, publishes a data track, pushes synthetic
payloads, unpublishes it, and disconnects.
- `data-track` connects a publisher and a subscriber for each cycle. The
publisher pushes synthetic frames and unpublishes the track. The subscriber
uses `LIVEKIT_TOKEN_B`.
- `room-reuse` repeatedly connects and disconnects the same room object.
- `room-client-leave` repeatedly connects, disconnects, and destroys a room.
- `room-server-delete` repeatedly connects, publishes one synthetic video
Expand Down
2 changes: 2 additions & 0 deletions include/livekit/data_track_error.h
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@ enum class LocalDataTrackTryPushErrorCode : std::uint32_t {
TRACK_UNPUBLISHED = 2,
QUEUE_FULL = 3,
INTERNAL = 4,
/// The server reports that the published track has no subscribers.
NO_SUBSCRIBERS = 5,
};

/// @brief Error details returned when pushing a frame to a local data track fails.
Expand Down
22 changes: 13 additions & 9 deletions include/livekit/local_data_track.h
Original file line number Diff line number Diff line change
Expand Up @@ -65,32 +65,36 @@ class LIVEKIT_API LocalDataTrack {
/// Metadata about this data track.
const DataTrackInfo& info() const noexcept { return info_; }

/// Try to push a frame to all subscribers of this track.
/// @brief Try to push a frame to all subscribers of this track.
///
/// An empty payload succeeds without sending a frame to subscribers.
/// If the server reports that no one subscribes, the track stays published.
/// Drop the rejected frame and try again with a fresh frame.
///
/// @param frame The frame to push.
/// @return Success on delivery acceptance, or a typed error describing why
/// the frame could not be queued.
/// @return Success if accepted, @c NO_SUBSCRIBERS if the server reports no
/// subscribers, or another error if the frame could not be queued.
Result<void, LocalDataTrackTryPushError> tryPush(const DataTrackFrame& frame);

/// Try to push a frame to all subscribers of this track.
/// @brief Try to push a frame to all subscribers of this track.
///
/// An empty payload succeeds without sending a frame to subscribers.
/// Drop a frame rejected with @c NO_SUBSCRIBERS and try again with a fresh frame.
///
/// @param payload The payload to push.
/// @param user_timestamp Optional application-defined timestamp. The unit is
/// caller-defined.
/// @return Success on delivery acceptance, or a typed error describing why
/// the frame could not be queued.
/// @return Success if accepted, @c NO_SUBSCRIBERS if the server reports no
/// subscribers, or another error if the frame could not be queued.
Result<void, LocalDataTrackTryPushError> tryPush(std::vector<std::uint8_t>&& payload,
std::optional<std::uint64_t> user_timestamp = std::nullopt);

/// Try to push a frame from a borrowed byte buffer.
/// @brief Try to push a frame from a borrowed byte buffer.
///
/// Copies @p size bytes from @p data into an FFI request before returning;
/// the SDK does not retain the buffer.
/// An empty payload succeeds without sending a frame to subscribers.
/// Drop a frame rejected with @c NO_SUBSCRIBERS and try again with a fresh frame.
///
/// @note This avoids an intermediate copy when the caller already owns a byte
/// buffer, but it is not a zero-copy send.
Expand All @@ -101,8 +105,8 @@ class LIVEKIT_API LocalDataTrack {
/// no-op.
/// @param user_timestamp Optional application-defined timestamp. The unit is
/// caller-defined.
/// @return Success on delivery acceptance, or a typed error describing why
/// the frame could not be queued.
/// @return Success if accepted, @c NO_SUBSCRIBERS if the server reports no
/// subscribers, or another error if the frame could not be queued.
Result<void, LocalDataTrackTryPushError> tryPush(const std::uint8_t* data, std::size_t size,
std::optional<std::uint64_t> user_timestamp = std::nullopt);

Expand Down
6 changes: 5 additions & 1 deletion src/data_track_error.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,9 @@ PublishDataTrackErrorCode fromProtoCode(proto::PublishDataTrackErrorCode code) {
}

LocalDataTrackTryPushErrorCode fromProtoCode(proto::LocalDataTrackTryPushErrorCode code) {
switch (code) {
// The pinned Rust schema predates NO_SUBSCRIBERS. Use its protocol value
// until we can build against a published Rust release that names it.
switch (static_cast<int>(code)) {
case proto::LOCAL_DATA_TRACK_TRY_PUSH_ERROR_CODE_INVALID_HANDLE:
return LocalDataTrackTryPushErrorCode::INVALID_HANDLE;
case proto::LOCAL_DATA_TRACK_TRY_PUSH_ERROR_CODE_TRACK_UNPUBLISHED:
Expand All @@ -61,6 +63,8 @@ LocalDataTrackTryPushErrorCode fromProtoCode(proto::LocalDataTrackTryPushErrorCo
return LocalDataTrackTryPushErrorCode::QUEUE_FULL;
case proto::LOCAL_DATA_TRACK_TRY_PUSH_ERROR_CODE_INTERNAL:
return LocalDataTrackTryPushErrorCode::INTERNAL;
case 5:
return LocalDataTrackTryPushErrorCode::NO_SUBSCRIBERS;
case proto::LOCAL_DATA_TRACK_TRY_PUSH_ERROR_CODE_UNKNOWN:
default:
return LocalDataTrackTryPushErrorCode::UNKNOWN;
Expand Down
Loading
Loading