Webrtc-pc: When is ICE gathering triggered?

[soareschen]

Filing this issue to get clarification for PR #1399.

In the current browser implementations, ICE gathering is triggered when setLocalDescription is called. This can be tested with the following snippet: (Tested on Chrome and Firefox)

const pc = new RTCPeerConnection();

pc.addEventListener('icecandidate', 
  ev => console.log('icecandidate event:', ev.candidate));
pc.addEventListener('icegatheringstatechange', 
  ev => console.log('icegatheringstatechange event:', pc.iceGatheringState));

console.log('creating data channel');
pc.createDataChannel('');

console.log('creating offer');
pc.createOffer().then(offer => {
  console.log('setting local description');
  pc.setLocalDescription(offer);
});

However there is no normative definition in both webrtc-pc and JSEP that ICE gathering is triggered when setLocalDescription is called. The only time this is hinted is in section 3.5.4 of JSEP:

When setLocalDescription is eventually called, and the JSEP implementation goes to gather the needed ICE candidates, it SHOULD start by checking if any candidates are available in the pool. If there are candidates in the pool, they SHOULD be handed to the application immediately via the ICE candidate event. If the pool becomes depleted, either because a larger-than-expected number of ICE components is used, or because the pool has not had enough time to gather candidates, the remaining candidates are gathered as usual. This only occurs for the first offer/answer exchange, after which the candidate pool is emptied and no longer used.

It can be problematic if there is no normative requirement of when ICE gathering must be fired. This would mean application developers are hopeless of what operations they need to do first to gather ICE candidates.

I think a reasonable expectation is to go with the current browsers behavior and add steps to setLocalDescription to describe that if iceGatheringState is new, trigger ICE gathering on the new ICE transports and update gatheringState to gathering.

[ibc]

I think a reasonable expectation is to go with the current browsers behavior and add steps to setLocalDescription to describe that if iceGatheringState is "new", trigger ICE gathering on the new ICE transports and update iceGatheringState to "gathering".

Agreed. It's important that the spec states that. Otherwise, in some scenarios (such as when no Trickle ICE is used) the application doesn't know when exactly it has to set the icegatheringstatechange and icecandidate events.

[stefhak]

Section 4.1.9 "setLocalDescription" of JSEP says:

   This API indirectly controls the candidate gathering process.  When a
   local description is supplied, and the number of transports currently
   in use does not match the number of transports needed by the local
   description, the PeerConnection will create transports as needed and
   begin gathering candidates for each transport, using ones from the
   candidate pool if available.

Section 5.8 "Applying a Local Description" says:

   o   If this m= section is new, begin gathering candidates for it, as
      defined in [RFC5245], Section 4.1.1, unless it has been marked as
      bundle-only.

   o  Or, if the ICE ufrag and password values have changed, and it has
      not been marked as bundle-only, trigger the ICE agent to start an
      ICE restart, and begin gathering new candidates for the m= section
      as described in [RFC5245], Section 9.1.1.1.  If this description
      is an answer, also start checks on that media section as defined
      in [RFC5245], Section 9.3.1.1.

I thought that was pretty clear.

[soareschen]

Thanks @stefhak for pointing out. My head wasn't thinking straight when filing this issue. (Was scanning for the word "ICE" when I should have just searched for "candidate")