The SDP offer/answer race
Two peers, one reconnect, zero chance your state machine survives.
The failure mode.
A call is in progress. The device loses network for ~3 seconds — a tunnel, a lift, a 4G/Wi-Fi handoff. When connectivity returns, you kick off ICE restart. Both sides generate fresh offers. One of them wins the race, and the connection hangs in have-local-offer forever. Audio dies. CallKit still shows “Connected 02:14”. The user swears at your app.
Why RTCPeerConnection is a state machine with teeth.
Signaling state is strict: you can't set a remote offer while you're holding a local offer. The valid transitions are narrow:
stable→have-local-offer(you calledcreateOffer)stable→have-remote-offer(peer sent you one)have-local-offer+ remote answer →stablehave-remote-offer+ local answer →stable
What's invalid: have-local-offer + remote offer. That throws. And under reconnect, that's exactly what you get if both ends restart ICE at the same moment — classic glare.
Why the obvious fix is wrong.
The obvious fix is “only one side initiates offer on reconnect.” Pick the side with the lexicographically smaller peer ID. Done. Right?
Wrong. The problem isn't deciding who offers — it's that your application code isn't serialized against its own peer connection state. Even on a single side, a user tap plus a backgrounded signaling message plus an ICE event can all try to mutate the peer at once. Any one of them will throw if it happens in the wrong state. And when it throws, you probably don't retry. You just end up stalled.
The fix: an actor around the peer.
Swift's actor is purpose-built for this. One owner, one queue of transitions, no two mutations at the same time. Here's the simplified version of what's in production:
1enum SignalingState { case stable, haveLocalOffer, haveRemoteOffer, disconnected }2enum Negotiation {3 case offer4 case answer(RTCSessionDescription)5 case iceRestart6}7enum PeerError: Error {8 case invalidTransition(from: SignalingState, action: Negotiation)9}1011actor PeerCoordinator {12 private var state: SignalingState = .stable13 private let peer: RTCPeerConnection1415 init(_ peer: RTCPeerConnection) { self.peer = peer }1617 func apply(_ action: Negotiation) async throws {18 switch (state, action) {19 case (.stable, .offer):20 let sdp = try await peer.offer()21 try await peer.setLocalDescription(sdp)22 state = .haveLocalOffer23 signaling.send(.offer(sdp))2425 case (.haveLocalOffer, .answer(let remote)):26 try await peer.setRemoteDescription(remote)27 state = .stable2829 case (.disconnected, _):30 try await peer.restartIce()31 state = .stable3233 default:34 throw PeerError.invalidTransition(from: state, action: action)35 }36 }37}
Three design calls worth defending:
- The actor owns the state, not the peer connection. The
RTCPeerConnectionhas its own state, but you want your view of what's valid before dispatching the real call. The actor'sstatevariable is yours; keep it in lockstep. - ICE restart is explicit, not implicit. I had a version that auto-restarted on
iceConnectionState == .failed. It worked in lab, blew up in production becausedisconnectedis often transient and the auto-restart fired before the browser had a chance to recover. Make it an explicit action; only the layer above knows if a restart is actually warranted. - Throw on invalid transitions, don't silently ignore.Silent ignores are how this bug class lives for months. If something invalid is happening, I want the Crashlytics breadcrumb.
Testing it without a network.
You can't reliably reproduce reconnect races against a real server. Mock the signaling layer. Fire sequences of actions directly at the coordinator — order them to interleave offer/answer transitions — and assert the state machine ends where you expect, or throws cleanly.
I keep a small suite I call SignalingFuzzTests that generates random permutations of the valid actions and asserts that no permutation deadlocks. It found two bugs in my own code the first time I ran it. Both are now impossible.
What this doesn't solve.
An actor-serialized coordinator does not fix:
- True signaling glare (both peers restart at the same time) — you still need a tie-break on the server side. The actor just meansyour side never corrupts its own state while the tie-break resolves.
- Media freeze with no state change — if the peer is sending packets you can't decode, your state machine is fine but the user hears static. That's a codec or jitter-buffer problem, different chapter.
Related chapters.
If you reached this chapter after fixing the cold-start silence, your next most-likely bug is CallKit + FaceID. If you're here because of multi-device weirdness, jump to Ghost calls across devices.
The code in this chapter has been running in production at YEO Messaging on thousands of devices. The named states are from RTCSignalingState; the actions are what my application layer dispatches.