§ 4.5  Module 4 — The Browser Gets a Dial Tone

Perfect Negotiation: Taming Glare

Be conservative in what you do, be liberal in what you accept from others.— Jon Postel, RFC 761, 1980

Surviving hardwarephotographed 2017

4.5.1The anatomy of glare

Recall the machinery from the previous two lessons. JSEP models every RTCPeerConnection as a small state machine driven by descriptions: applying a local offer moves signalingState from stable to have-local-offer; applying the remote answer returns it to stable; the mirror-image path runs through have-remote-offer. The offer/answer model underneath (RFC 3264, Rosenberg and Schulzrinne, June 2002) is explicit about concurrency: an agent must not generate a new offer while an offer it sent is unanswered, and must not generate one while holding an offer it has not yet answered. One offer in flight, ever.

That rule is easy to state and impossible for two independent machines to obey over an asynchronous channel without coordination. Suppose peers A and B both add a track within the same few milliseconds. Both fire negotiationneeded, both create offers, both enter have-local-offer, and the two offers cross on the wire. That is glare. Each peer now receives an offer in a state where the only legal input is an answer.

Why can't both offers win? Because an offer is not a request for resources; it is a proposed next version of the shared session — the complete SDP, media section by media section. Two crossed offers are two conflicting proposals forked from the same base version, and offer/answer defines no merge operation. If A applied B's offer while B applied A's, each side would answer a different question: A's session would be (B's offer, A's answer) while B's would be (A's offer, B's answer) — two different negotiated sessions on the two ends of one connection, disagreeing about m-line order, directions, even how many media sections exist. Someone must abandon their proposal. The whole problem of glare reduces to deciding who, deterministically, with no extra round trips.

SIP resolved the same deadlock with rejection and randomized, asymmetric retry timers — workable, but it adds seconds of latency and still leaves a small re-collision probability. WebRTC can do better because the application controls the code at both endpoints: assign the asymmetry in advance. One peer is designated polite, the other impolite, and glare resolves in zero additional round trips.

4.5.2Polite society: roles and the two guard flags

The role assignment is arbitrary but must be agreed and asymmetric: exactly one polite peer per pair. Any deterministic rule works — the peer that joined the signaling room second is polite, or compare session identifiers lexicographically. The behavioral contract is short. The impolite peer, on detecting a collision, ignores the incoming offer entirely and keeps waiting for the answer to its own. The polite peer, on detecting a collision, abandons its own offer — rolls it back — applies the incoming one, and answers it. The impolite peer's offer always wins; the polite peer's abandoned changes are renegotiated immediately afterward, so nothing is lost.

Detection needs two locally scoped flags. The first, makingOffer, is set before calling setLocalDescription() in the negotiationneeded handler and cleared in a finally once it settles. It exists because of an asynchronous blind spot: from the moment the handler starts until setLocalDescription() resolves, the connection is busy producing an offer, yet signalingState still reads stable. An offer arriving inside that window is a collision that the state machine alone cannot see. The collision predicate therefore reads:

const offerCollision = description.type === 'offer' &&
    (makingOffer || pc.signalingState !== 'stable');

ignoreOffer = !polite && offerCollision;
if (ignoreOffer) return;

Listing 4.4 — The collision test. Only the impolite peer ever sets ignoreOffer.

The second flag, ignoreOffer, records that decision, and it has one further job. Trickled ICE candidates travel behind the description they belong to; if we discarded an offer, the candidates trailing it describe a session we never accepted, and addIceCandidate() will reject them. The pattern swallows addIceCandidate failures precisely when ignoreOffer is true — and only then. Swallowing candidate errors unconditionally is a classic way to hide real bugs.

4.5.3Rollback without tears

What does the polite peer's surrender actually do? Rollback is a defined transition in JSEP: applying a description of type rollback from either have-local-offer or have-remote-offer returns the connection to stable, undoing the pending offer. Rolling back a local offer disassociates the transceivers that offer had claimed — their mid values clear — but the transceivers themselves, and the tracks you added, remain and still want negotiating. Rolling back a remote offer discards transceivers that were created solely by applying it.

Early perfect-negotiation code had to perform this dance explicitly — setLocalDescription({ type: 'rollback' }), then setRemoteDescription(offer) — two chained operations with their own failure windows. The specification closed the gap with implicit rollback: calling setRemoteDescription() with an offer while in have-local-offer rolls back automatically and then applies the incoming offer, atomically from the application's point of view. The polite peer's entire collision response is one line: await pc.setRemoteDescription(description).

The companion change is parameterless setLocalDescription(). The traditional two-step — const offer = await pc.createOffer(); await pc.setLocalDescription(offer) — contains a race: between the offer being created and it being applied, an incoming offer may have been processed and moved the state to have-remote-offer, at which point applying the now-stale offer throws. Called with no argument, setLocalDescription() decides what to create when it executes on the connection's operations chain: an offer if the state is stable, an answer if it is have-remote-offer. The stale-offer race is not handled — it is abolished. The same handler line therefore serves both duties in the pattern: producing offers in negotiationneeded and producing answers after a remote offer is applied.

One more API rounded out the set: restartIce(). Before it existed, an ICE restart required createOffer({ iceRestart: true }) — but a polite peer's restart offer could be rolled back and the intent lost. restartIce() instead sets internal state that survives rollback: the next offer, whenever it happens, carries new ICE credentials.

4.5.4onnegotiationneeded: firing rules and queuing

The pattern only works because negotiationneeded has disciplined semantics. Three rules matter. First, it fires only in stable. Changes made while negotiation is in progress — a track added mid-handshake — set an internal negotiation-needed flag, and the event is delivered once the state returns to stable. This is exactly how the polite peer's rolled-back changes recover: rollback discarded the offer, not the need; back in stable, the flag is re-checked and the event fires again. (Often not even that is needed — an unassociated transceiver created by addTrack() can be matched to a new m-line in the incoming offer and ride home in the answer.)

Second, firings coalesce. The event is dispatched from a queued task, so adding three tracks synchronously yields one event describing all three changes, not three events. Third, spurious firings must be harmless, and in this pattern they are: the handler's only action is parameterless setLocalDescription(), which simply produces a fresh offer reflecting current state. The corollary is a design rule worth engraving: the negotiationneeded handler is the only place your application ever creates an offer. Code that calls createOffer() from click handlers is code that races itself.

Finally, remember from Lesson 4.4 what renegotiation is not: it reuses the existing ICE and DTLS transports unless you explicitly restart ICE, and replaceTrack() avoids it entirely when swapping media of the same kind. When you must prove that renegotiation actually delivered media — as our problem set does — do not trust connectionState; count flowing inbound-rtp streams with getStats.

4.5.5The pattern, whole

Everything above compresses into about thirty lines. Read it once as prose: the negotiationneeded handler makes offers and nothing else; the message handler applies whatever arrives unless it is a colliding offer at an impolite peer; every incoming offer is answered by the same parameterless call that made offers; candidate failures are tolerated only while ignoring.

function perfectNegotiation(pc, signaler, polite) {
  let makingOffer = false;
  let ignoreOffer = false;

  pc.onnegotiationneeded = async () => {
    try {
      makingOffer = true;
      await pc.setLocalDescription();            // offer for current state
      signaler.send({ description: pc.localDescription });
    } catch (err) {
      console.error(err);
    } finally {
      makingOffer = false;
    }
  };

  pc.onicecandidate = ({ candidate }) => signaler.send({ candidate });

  signaler.onmessage = async ({ description, candidate }) => {
    try {
      if (description) {
        const offerCollision = description.type === 'offer' &&
            (makingOffer || pc.signalingState !== 'stable');
        ignoreOffer = !polite && offerCollision;
        if (ignoreOffer) return;                 // impolite: drop it
        await pc.setRemoteDescription(description); // polite: implicit rollback
        if (description.type === 'offer') {
          await pc.setLocalDescription();        // answer for current state
          signaler.send({ description: pc.localDescription });
        }
      } else if (candidate) {
        try {
          await pc.addIceCandidate(candidate);
        } catch (err) {
          if (!ignoreOffer) throw err;           // tolerate only while ignoring
        }
      }
    } catch (err) {
      console.error(err);
    }
  };
}

Listing 4.5 — Perfect negotiation, as canonized in the W3C WebRTC 1.0 Recommendation's negotiation example.

Checkpoint § 4.5Predict the machine

Three quick state-machine predictions before the laboratory.

Problems for § 4.5Check your understanding

One adversarial laboratory — your negotiation code against a glare injector running one deterministic crossed-offer round and four randomized rounds — and one timeline quiz. The lab takes 15–40 seconds to grade; watch the two peers reconverge to two flowing inbound-rtp streams per side.

¶Field quirks

What the specifications say, and what the browsers actually do, are two different documents. These are the divergences that cost production teams their weekends.