Skip to content
18 changes: 18 additions & 0 deletions .changeset/quiet-pandas-marry.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
"client-sdk-android": patch
---

Fix the subscriber silently buffering remote ICE candidates after a resume

A soft reconnect put the subscriber into an ice restart state, but only `setRemoteDescription`
clears that and the server re-offers the subscriber only when the reconnect moved the participant
to another node. After an ordinary resume no offer arrives, so the state stayed set for the life of
the transport and every later remote candidate was queued instead of applied, leaving the
subscriber unable to adopt any new path the server proposed.

Candidates now wait on the description they belong to rather than on the reconnect. `onServerOffer`
says a description is coming before it schedules the work that applies it, so a candidate that
arrives in between is held rather than tried against the description being replaced. Each wait is
owned by what answers it, an ice restart offer by its own offer id and a server offer by its own
turn, and it ends when that attempt ends whether the description lands, is refused, or answers an
offer that has since been superseded.
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,16 @@ constructor(
) ?: throw IllegalStateException("peer connection creation failed?")
}!!
private val pendingCandidates = mutableListOf<IceCandidate>()
private var restartingIce: Boolean = false

/**
* The offers whose answers are still owed, by offer id, and how many server offers are still to
* be applied. Candidates wait while either stands, so one belonging to a description that has
* not landed is never tried against the description it replaces. Only touched on the RTC thread.
*/
private val awaitedAnswers = mutableSetOf<Int>()
private var awaitedOffers = 0

private fun awaitingDescription() = awaitedAnswers.isNotEmpty() || awaitedOffers > 0

private var renegotiate = false

Expand Down Expand Up @@ -121,7 +130,7 @@ constructor(

fun addIceCandidate(candidate: IceCandidate) {
executeRTCIfNotClosed {
if (peerConnection.remoteDescription != null && !restartingIce) {
if (peerConnection.remoteDescription != null && !awaitingDescription()) {
peerConnection.addIceCandidate(candidate)
} else {
pendingCandidates.add(candidate)
Expand All @@ -139,16 +148,13 @@ constructor(
val result = launchRTCIfNotClosed {
val currentOfferId = latestOfferId.get()
if (sd.type == SessionDescription.Type.ANSWER && currentOfferId > 0 && offerId > 0 && currentOfferId > offerId) {
// The offer this answers has been superseded, so only that offer's wait ends here;
// the offer that replaced it keeps its own.
descriptionSettled(sd, offerId, applied = false)
return@launchRTCIfNotClosed Either.Right("Old offer, ignoring. Expected: $currentOfferId, actual: $offerId")
}
val result = peerConnection.setRemoteDescription(sd)
if (result is Either.Left) {
pendingCandidates.forEach { pending ->
peerConnection.addIceCandidate(pending)
}
pendingCandidates.clear()
restartingIce = false
}
descriptionSettled(sd, offerId, applied = result is Either.Left)
return@launchRTCIfNotClosed result
} ?: Either.Right("PCT is closed.")

Expand Down Expand Up @@ -184,7 +190,6 @@ constructor(
constraints.findConstraint(MediaConstraintKeys.ICE_RESTART) == MediaConstraintKeys.TRUE
if (iceRestart) {
LKLog.d { "restarting ice" }
restartingIce = true
}

if (peerConnection.signalingState() == SignalingState.HAVE_LOCAL_OFFER) {
Expand All @@ -208,10 +213,18 @@ constructor(
// this may skip some ids, but is not an issue.
offerId = latestOfferId.incrementAndGet()

// An ice restart mints new local credentials, so candidates wait for the answer
// that carries the far side's. The wait is owned by this offer id alone.
if (iceRestart) {
awaitedAnswers.add(offerId)
}
Comment on lines +218 to +220

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Superseded restart permanently holds candidates

When a second ICE restart replaces an unanswered first offer, awaitedAnswers retains both offer IDs. The replacement's answer removes only its ID, leaving later candidates queued indefinitely.

Learn more

createAndSendOffer permits a second ICE restart while signaling is HAVE_LOCAL_OFFER: it applies the current remote description and creates a new offer. Each restart inserts its ID in awaitedAnswers, but descriptionSettled removes only the answered ID. The first offer was superseded, so its answer need never arrive. Its leftover ID makes awaitingDescription() true indefinitely and prevents all subsequent subscriber/publisher candidates on that transport from being added.

Example: Restart offer 7 remains unanswered when another reconnect triggers restart offer 8. Answer 8 arrives, but 7 remains in the set; every later publisher trickle is queued instead of applied.

Recommended fix: Retire the replaced offer's wait when starting a replacement restart, while preserving the replacement's wait and preventing a late answer to the old ID from releasing it.

Devin Review


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


val sdpOffer = when (val outcome = peerConnection.createOffer(constraints)) {
is Either.Left -> outcome.value
is Either.Right -> {
LKLog.d { "error creating offer: ${outcome.value}" }
// No offer goes out, so the answer it would have waited for is not coming.
awaitedAnswers.remove(offerId)
return@launchRTCIfNotClosed
}
}
Expand Down Expand Up @@ -352,8 +365,40 @@ constructor(
return sdp
}

fun prepareForIceRestart() {
restartingIce = true
/**
* Says a remote description is on its way, so candidates for it wait rather than land against
* the description it replaces. Called before the work that applies it is scheduled, and
* answered by the attempt to set that description whether it lands or is refused.
*/
fun expectRemoteDescription() {
executeRTCIfNotClosed { awaitedOffers++ }
}
Comment on lines +373 to +375

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Server-offer candidates reach the old description

When a server offer precedes a candidate, expectRemoteDescription never runs before the candidate arrives. onServerOffer schedules description application asynchronously, so the candidate can reach the old ICE credentials and be rejected.

Learn more

The signal client delivers offers and trickles through separate callbacks. onServerOffer launches offer handling, leaving a gap before answerServerOffer applies the subscriber description. Nothing calls expectRemoteDescription, so the new wait never covers that gap. A candidate arriving in the gap is handed to WebRTC with the preceding SDP's ICE credentials.

Example: The server sends an ICE-restart offer followed immediately by a subscriber trickle. The candidate reaches the subscriber before the offer coroutine installs the new SDP; WebRTC rejects it instead of receiving it after installation.

Recommended fix: Wire expectRemoteDescription into the subscriber offer path before onServerOffer launches its coroutine. Ensure the wait is ended if offer processing exits without calling setRemoteDescription.

Devin Review


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


/**
* Ends the wait this description answers, however it ended: an answer ends the wait its own
* offer opened and no other, a server offer ends one of the waits opened for them. Only a
* description that landed takes the candidates held, and only once nothing else is awaited. A
* wait that ended without one leaves them queued rather than dropping them, since one that no
* longer fits is refused by the connection anyway and one that still fits would be lost.
*/
private fun descriptionSettled(sd: SessionDescription, offerId: Int, applied: Boolean) {
if (sd.type == SessionDescription.Type.ANSWER) {
// A legacy answer carries no id to match itself to, so it ends whatever was owed.
if (offerId > 0) {
awaitedAnswers.remove(offerId)
} else {
awaitedAnswers.clear()
}
} else if (awaitedOffers > 0) {
awaitedOffers--
}
if (!applied || awaitingDescription()) {
return
}
pendingCandidates.forEach { pending ->
peerConnection.addIceCandidate(pending)
}
pendingCandidates.clear()
}

fun isClosed() = isClosed.get()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -75,12 +75,43 @@ class MockPeerConnection(
}

override fun getRemoteDescription(): SessionDescription? = remoteDesc

/**
* Holds remote descriptions in flight instead of applying them, so a test can put a candidate
* in the gap a real connection has between an offer arriving and its description landing.
* Released by [releaseRemoteDescriptions].
*/
var holdsRemoteDescriptions = false
private val heldRemoteDescriptions = mutableListOf<Pair<SdpObserver, SessionDescription>>()

/** Applies the oldest held description, leaving any after it still in flight. */
fun releaseHeldRemoteDescription() {
val held = heldRemoteDescriptions.removeFirstOrNull() ?: return
val holding = holdsRemoteDescriptions
holdsRemoteDescriptions = false
setRemoteDescription(held.first, held.second)
holdsRemoteDescriptions = holding
}

/** Applies everything held, in the order it arrived. */
fun releaseRemoteDescriptions() {
val held = heldRemoteDescriptions.toList()
heldRemoteDescriptions.clear()
holdsRemoteDescriptions = false
held.forEach { (observer, sdp) -> setRemoteDescription(observer, sdp) }
}

override fun setRemoteDescription(observer: SdpObserver, sdp: SessionDescription) {
if (sdp.description.isEmpty()) {
observer.onSetFailure("empty remote description")
return
}

if (holdsRemoteDescriptions) {
heldRemoteDescriptions.add(observer to sdp)
return
}

try {
signalStateMachine.handleSetMethod(Location.REMOTE, sdp.type)
} catch (e: IllegalStateException) {
Expand Down Expand Up @@ -135,7 +166,11 @@ class MockPeerConnection(
return true
}

/** Every candidate actually handed to the connection, so a test can tell added from queued. */
val addedIceCandidates = mutableListOf<IceCandidate>()

override fun addIceCandidate(candidate: IceCandidate?): Boolean {
candidate?.let { addedIceCandidates.add(it) }
return true
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -704,4 +704,148 @@ class RTCEngineMockE2ETest : MockE2ETest() {
)
}
}

/**
* A resume must leave the subscriber able to take the paths the server proposes. It used to
* enter an ice restart state that only a remote description clears, and the server re-offers
* the subscriber only when the reconnect moved us to another node, so after an ordinary resume
* every later candidate was queued and never added. Same defect as client-sdk-js#2054.
*/
@Test
fun softReconnectKeepsSubscriberApplyingRemoteCandidates() = runTest {
room.setReconnectionType(ReconnectType.FORCE_SOFT_RECONNECT)
connect()

disconnectPeerConnection()
testScheduler.advanceTimeBy(1000)
wsFactory.listener.onOpen(wsFactory.ws, createOpenResponse(wsFactory.request))
simulateMessageFromServer(TestData.RECONNECT)
connectPeerConnection()
advanceUntilIdle()

val subPeerConnection = getSubscriberPeerConnection()
val before = subPeerConnection.addedIceCandidates.size
simulateMessageFromServer(subscriberTrickle())
advanceUntilIdle()

assertEquals(before + 1, subPeerConnection.addedIceCandidates.size)
}

/**
* A candidate belonging to a server offer waits for that offer to be applied. Offer handling is
* launched rather than run inline, so without the hold the candidate would land against the
* description the offer replaces and be rejected against its ice credentials.
*/
@Test
fun candidateArrivingWithAServerOfferWaitsForItsDescription() = runTest {
connect()

val subPeerConnection = getSubscriberPeerConnection()
val before = subPeerConnection.addedIceCandidates.size

// The gap a real connection has between an offer arriving and its description landing.
// Signal responses are handled from a queue, so without holding the description here the
// offer would be applied before the candidate is even read and there would be no gap.
subPeerConnection.holdsRemoteDescriptions = true
simulateMessageFromServer(TestData.OFFER)
simulateMessageFromServer(subscriberTrickle())
advanceUntilIdle()

assertEquals(before, subPeerConnection.addedIceCandidates.size)

subPeerConnection.releaseRemoteDescriptions()
advanceUntilIdle()

assertEquals(before + 1, subPeerConnection.addedIceCandidates.size)
}

/**
* A refused offer ends its own wait. The description it would have installed never came into
* being, so the connection carries on with the one in force and later candidates reach it
* rather than piling up behind an offer that is never going to land.
*/
@Test
fun aRefusedOfferStopsHoldingCandidates() = runTest {
connect()
val subPeerConnection = getSubscriberPeerConnection()

simulateMessageFromServer(refusedOffer())
advanceUntilIdle()

val before = subPeerConnection.addedIceCandidates.size
simulateMessageFromServer(subscriberTrickle())
advanceUntilIdle()

assertEquals(before + 1, subPeerConnection.addedIceCandidates.size)
}

/**
* A stale answer ends only its own offer's wait. An ordinary offer opens none, so an answer to
* it arriving late must not release the wait an ice restart opened afterwards, or candidates
* for the restart land against the credentials it replaced.
*/
@Test
fun aStaleAnswerDoesNotEndAnotherOffersWait() = runTest {
connect()

val subPeerConnection = getSubscriberPeerConnection()
val before = subPeerConnection.addedIceCandidates.size

// Two offers in flight, the second replacing the first. A candidate arriving now belongs
// to the description still to land, so it waits for that one and not for either answer.
subPeerConnection.holdsRemoteDescriptions = true
simulateMessageFromServer(TestData.OFFER)
simulateMessageFromServer(secondOffer())
simulateMessageFromServer(subscriberTrickle())
advanceUntilIdle()

assertEquals(before, subPeerConnection.addedIceCandidates.size)

// The first offer's description lands; the second is still owed, so the wait stands.
subPeerConnection.releaseHeldRemoteDescription()
advanceUntilIdle()

assertEquals(before, subPeerConnection.addedIceCandidates.size)

subPeerConnection.releaseRemoteDescriptions()
advanceUntilIdle()

assertEquals(before + 1, subPeerConnection.addedIceCandidates.size)
}

/** A second server offer, replacing the one before it. */
private fun secondOffer(): LivekitRtc.SignalResponse {
val offer = LivekitRtc.SessionDescription.newBuilder()
.setSdp("remote_offer_2")
.setType("offer")
.setId(100)
.build()
return LivekitRtc.SignalResponse.newBuilder()
.setOffer(offer)
.build()
}

/** An empty description is the one the mock connection refuses. */
private fun refusedOffer(): LivekitRtc.SignalResponse {
val offer = LivekitRtc.SessionDescription.newBuilder()
.setSdp("")
.setType("offer")
.setId(100)
.build()
return LivekitRtc.SignalResponse.newBuilder()
.setOffer(offer)
.build()
}

private fun subscriberTrickle(): LivekitRtc.SignalResponse {
val trickle = LivekitRtc.TrickleRequest.newBuilder()
.setCandidateInit(
"""{"candidate":"candidate:1 1 UDP 1 127.0.0.1 9 typ host","sdpMLineIndex":0,"sdpMid":"0"}""",
)
.setTarget(LivekitRtc.SignalTarget.SUBSCRIBER)
.build()
return LivekitRtc.SignalResponse.newBuilder()
.setTrickle(trickle)
.build()
}
}