Skip to content

Bundle the publisher offer with the /rtc/v1 join request - #1070

Open
changt wants to merge 6 commits into
mainfrom
sc/single-pc-offer-on-join
Open

changt wants to merge 6 commits into
mainfrom
sc/single-pc-offer-on-join

Conversation

@changt

@changt changt commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

In single peer connection mode the client makes every offer, so the first one no longer waits for the join to finish. The publisher peer connection, its three data channels and the initial offer are created before the signal socket opens, and the offer travels in JoinRequest.publisher_offer. The server answers it over the signal channel right after the JoinResponse, which removes one offer/answer round trip from connecting. Same approach as livekit/client-sdk-js#1846, livekit/rust-sdks#996 and livekit/client-sdk-swift#1111.

Follows #1066. Only joins with ConnectOptions.singlePeerConnection are affected.

PeerConnectionTransport

  • createInitialOffer creates and munges the offer but does not apply it: setLocalDescription would start ICE gathering before the server's ICE servers are known. The offer stays pending, and setRemoteDescription applies it as the local description just before the answer.
  • While the initial offer is pending, negotiate queues a renegotiation, the same way it does for an offer already in flight. A publish that races the join therefore waits for the answer instead of offering over the bundled offer.
  • If the munge leaves nothing, the unmunged offer is bundled. The pending offer is always the bundled one, so what the server answers is what gets set locally (as in rust-sdks).
  • Offer creation and munging are shared with createAndSendOffer through createMungedOffer.

RTCEngine

  • The early publisher and its observer live in engine fields. configure adopts them into the transport and installs the server's ICE servers and relay policy through updateRTCConfig. SignalClient holds responses until configure is done, so the answer is applied after that.
  • An early publisher that is never adopted does not outlive its join. close disposes it even when the join ended before its response, a point at which the engine still counts as closed. A new join disposes one left by an earlier attempt, such as a region retry. closeResources disposes it on teardown and before a full reconnect's join.
  • On the /rtc/v1 404 fallback the early publisher and its data channels are closed before the legacy join, so that join starts from nothing.
  • makeRTCConfig accepts a missing server response, for the configuration the early publisher starts with.

Signal

  • SignalClient.join takes an optional publisherOffer and passes it to SignalUrlBuilder.buildJoinRequestUrl.
  • SinglePeerConnectionTransport skips the eager negotiate on join while the initial offer is pending.

Not included

  • A timeout for a bundled offer that is never answered. As with any initial connect today, nothing times out waiting for the peer connection.
  • Preallocated receive sections, negotiated data channels, and publishing tracks with the join request.

Tests

PeerConnectionTransportTest (new) covers the initial offer: offer id, constraints, munging, the empty-munge case, not being applied or sent, being applied before the answer, and queued negotiation. SinglePeerConnectionMockE2ETest now answers the offer decoded from the join request and checks that nothing is offered over the signal connection. SinglePeerConnectionFallbackMockE2ETest covers the 404 fallback and the reconnects after it. SinglePeerConnectionFailedJoinMockE2ETest (new) covers a rejected join and a join that follows a rejected one: in both, the earlier publisher is closed.

Not yet run on a device against a live server.

In single peer connection mode the client is the only offerer, so the
publisher, its three data channels and the first offer are built before
the signal socket opens and the offer travels in
JoinRequest.publisher_offer. The server answers it over the signal
channel right after the JoinResponse, which removes one offer/answer
round trip from the connect path.

PeerConnectionTransport.createInitialOffer creates and munges the offer
but does not apply it: setLocalDescription would start ICE gathering
before the server's ICE servers are known. The offer stays pending and
setRemoteDescription applies it just before the answer. While it is
pending, negotiate queues a renegotiation the same way as for an offer
already in flight. Offer creation and munging are shared with
createAndSendOffer through createMungedOffer.

RTCEngine builds the early publisher with a client-side configuration
(makeRTCConfig with no server response) and configure adopts it,
installing the server's ICE servers and relay policy through
updateRTCConfig before the pending offer can be applied. The eager
negotiate on join is skipped while the initial offer is pending.

Not yet handled: closing the early publisher when the join fails, and
the /rtc/v1 404 fallback, which still adopts it. The two fallback
reconnect tests in SinglePeerConnectionFallbackMockE2ETest fail until
then.
The publisher created ahead of a single peer connection join lived in
locals of joinImpl, so a join that failed before configure ran left it
with no owner, and the /rtc/v1 404 fallback handed the already-closed
publisher to configure, which adopted it into the dual peer connection
transport.

RTCEngine now holds the early publisher and its observer in fields.
configure adopts them into the transport and clears the fields once the
data channels are in place; closeResources closes a publisher that was
never adopted, which covers a failed or cancelled join through the
engine's normal teardown. The 404 fallback calls closeEarlyPublisher
before the legacy join, so that join starts from nothing. The helper
also disposes the publisher's data channels, and closeResources reuses
it for that side of the teardown.

The two SinglePeerConnectionFallbackMockE2ETest reconnect tests pass
again.
SinglePeerConnectionMockE2ETest answered the last offer sent over the
signal connection after joining. With the publisher offer bundled in the
/rtc/v1 join request there is no such offer, so every test that connects
failed on an empty list.

The connect helper now decodes the offer from the join request URL and
answers that one by id. publisherOfferRidesInTheJoinRequest checks that
the offer travels with the join request and that nothing is offered over
the signal connection before or after its answer.

The detekt baseline entry for makeRTCConfig takes the nullable server
response the function has had since the early publisher was added.
createInitialOffer bundled the munged description as is. The ordinary
offer path sends whatever setMungedSdp managed to apply, so an empty
munge falls back to the offer libwebrtc created, but the initial offer
is sent before anything is applied and had no such step: an empty munge
went to the server as an empty publisher offer.

createInitialOffer now bundles the unmunged description in that case.
The pending offer is the bundled one, so what the server answers is
what the answer path sets locally.

In the mock E2E suite createOffer returns a placeholder that munges to
nothing, so publisherOfferRidesInTheJoinRequest can now also check that
the bundled SDP is not empty and becomes the local description once it
is answered.
@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: a730a78

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

This PR includes changesets to release 1 package
Name Type
client-sdk-android 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

devin-ai-integration[bot]

This comment was marked as resolved.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Diffuse output:

OLD: diffuse-source-file
NEW: livekit-android-sdk-release.aar

 AAR      │ old      │ new      │ diff      
──────────┼──────────┼──────────┼───────────
      jar │  3.1 MiB │  3.1 MiB │ +16.8 KiB 
 manifest │  1.5 KiB │  1.5 KiB │       0 B 
 lint-jar │ 12.7 KiB │ 12.7 KiB │       0 B 
    other │  2.4 KiB │  2.4 KiB │       0 B 
──────────┼──────────┼──────────┼───────────
    total │  3.1 MiB │  3.2 MiB │ +16.8 KiB 

 JAR     │ old   │ new   │ diff          
─────────┼───────┼───────┼───────────────
 classes │  1794 │  1803 │  +9 (+15 -6)  
 methods │ 22659 │ 22701 │ +42 (+82 -40) 
  fields │  5984 │  6022 │ +38 (+56 -18)
AAR
 size    │ diff      │ path          
─────────┼───────────┼───────────────
 3.1 MiB │ +16.8 KiB │ ∆ classes.jar 
─────────┼───────────┼───────────────
 3.1 MiB │ +16.8 KiB │ (total)
JAR
CLASSES:

   old  │ new  │ diff        
  ──────┼──────┼─────────────
   1794 │ 1803 │ +9 (+15 -6) 
  
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer
  + io.livekit.android.room.PeerConnectionTransport_MungedOffer
  + io.livekit.android.room.PeerConnectionTransport_createInitialOffer_1
  + io.livekit.android.room.PeerConnectionTransport_createInitialOffer_2_1
  + io.livekit.android.room.PeerConnectionTransport_createMungedOffer_1
  + io.livekit.android.room.RTCEngine_close__inlined_executeBlockingOnRTCThread_1
  + io.livekit.android.room.RTCEngine_close_1_1
  + io.livekit.android.room.RTCEngine_closeEarlyPublisher_1
  + io.livekit.android.room.RTCEngine_createPublisherDataChannels_1
  + io.livekit.android.room.RTCEngine_createPublisherDataChannels_2_1_1_1
  + io.livekit.android.room.RTCEngine_createPublisherDataChannels_2_1_1_2
  + io.livekit.android.room.RTCEngine_createPublisherDataChannels_2_1_1
  + io.livekit.android.room.RTCEngine_createPublisherDataChannels_2
  + io.livekit.android.room.RTCEngine_createPublisherDataChannels_3
  + io.livekit.android.room.RTCEngine_createPublisherDataChannels_4
  
  - io.livekit.android.room.RTCEngine_configure_2_2_4_1_1_1
  - io.livekit.android.room.RTCEngine_configure_2_2_4_1_1_2
  - io.livekit.android.room.RTCEngine_configure_2_2_4_1_1
  - io.livekit.android.room.RTCEngine_configure_2_2_4
  - io.livekit.android.room.RTCEngine_configure_2_2_5
  - io.livekit.android.room.RTCEngine_createPublisherDataTrackChannel_2
  

METHODS:

   old   │ new   │ diff          
  ───────┼───────┼───────────────
   22659 │ 22701 │ +42 (+82 -40) 
  
  + io.livekit.android.room.PeerConnectionTransport access_createMungedOffer(PeerConnectionTransport, MediaConstraints, Continuation) → Object
  + io.livekit.android.room.PeerConnectionTransport access_getInitialOffer_p(PeerConnectionTransport) → PeerConnectionTransport_InitialOffer
  + io.livekit.android.room.PeerConnectionTransport access_setInitialOffer_p(PeerConnectionTransport, PeerConnectionTransport_InitialOffer)
  + io.livekit.android.room.PeerConnectionTransport clearPendingInitialOffer()
  + io.livekit.android.room.PeerConnectionTransport createInitialOffer(MediaConstraints, Continuation) → Object
  + io.livekit.android.room.PeerConnectionTransport createInitialOffer_default(PeerConnectionTransport, MediaConstraints, Continuation, int, Object) → Object
  + io.livekit.android.room.PeerConnectionTransport createMungedOffer(MediaConstraints, Continuation) → Object
  + io.livekit.android.room.PeerConnectionTransport hasPendingInitialOffer() → boolean
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer <init>(SessionDescription, int)
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer component1() → SessionDescription
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer component2() → int
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer copy(SessionDescription, int) → PeerConnectionTransport_InitialOffer
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer copy_default(PeerConnectionTransport_InitialOffer, SessionDescription, int, int, Object) → PeerConnectionTransport_InitialOffer
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer equals(Object) → boolean
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer getOfferId() → int
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer getSessionDescription() → SessionDescription
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer hashCode() → int
  + io.livekit.android.room.PeerConnectionTransport_InitialOffer toString() → String
  + io.livekit.android.room.PeerConnectionTransport_MungedOffer <init>(SessionDescription, String, Long)
  + io.livekit.android.room.PeerConnectionTransport_MungedOffer getConnectionStartBitrate() → Long
  + io.livekit.android.room.PeerConnectionTransport_MungedOffer getDescription() → String
  + io.livekit.android.room.PeerConnectionTransport_MungedOffer getOriginal() → SessionDescription
  + io.livekit.android.room.PeerConnectionTransport_createInitialOffer_1 <init>(PeerConnectionTransport, Continuation)
  + io.livekit.android.room.PeerConnectionTransport_createInitialOffer_1 invokeSuspend(Object) → Object
  + io.livekit.android.room.PeerConnectionTransport_createInitialOffer_2_1 <init>(PeerConnectionTransport, MediaConstraints, Continuation)
  + io.livekit.android.room.PeerConnectionTransport_createInitialOffer_2_1 create(Object, Continuation
...✂

RTCEngine counts as closed until a join response arrives, and close
returns early in that state. The early publisher is created before the
response, so a rejected or cancelled first join left it in its field
with nothing to dispose it: Room's close after the failure did nothing,
and a retry against another region replaced the field and dropped the
only reference to the first peer connection.

close now disposes an unadopted early publisher even when the engine is
already closed, and joinImpl disposes one that an earlier join left
behind before creating the next.

SinglePeerConnectionFailedJoinMockE2ETest covers both paths.
MockPeerConnectionFactory records the peer connections it creates so
the tests can reach the early publisher.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant