[breaking] make RTCPeerConnection.addIceCandidate a coroutine

This will be needed to support mDNS candidates. It also matches the
JavaScript WebRTC API more closely.

Author: jlaine

docs/changelog.rst

@@ -3,6 +3,15 @@ Changelog
 
 .. currentmodule:: aiortc
 
+1.0.0
+-----
+
+Breaking
+........
+
+ * Make :meth:`RTCPeerConnection.addIceCandidate` a coroutine.
+ * Make :meth:`RTCIceTransport.addRemoteCandidate` a coroutine.
+
 0.9.28
 ------
 

examples/apprtc/apprtc.py

@@ -83,7 +83,7 @@ def on_track(track):
                 await pc.setLocalDescription(await pc.createAnswer())
                 await signaling.send(pc.localDescription)
         elif isinstance(obj, RTCIceCandidate):
-            pc.addIceCandidate(obj)
+            await pc.addIceCandidate(obj)
         elif obj is BYE:
             print("Exiting")
             break

examples/datachannel-cli/cli.py

@@ -28,7 +28,7 @@ async def consume_signaling(pc, signaling):
                 await pc.setLocalDescription(await pc.createAnswer())
                 await signaling.send(pc.localDescription)
         elif isinstance(obj, RTCIceCandidate):
-            pc.addIceCandidate(obj)
+            await pc.addIceCandidate(obj)
         elif obj is BYE:
             print("Exiting")
             break

examples/datachannel-filexfer/filexfer.py

@@ -25,7 +25,7 @@ async def consume_signaling(pc, signaling):
                 await pc.setLocalDescription(await pc.createAnswer())
                 await signaling.send(pc.localDescription)
         elif isinstance(obj, RTCIceCandidate):
-            pc.addIceCandidate(obj)
+            await pc.addIceCandidate(obj)
         elif obj is BYE:
             print("Exiting")
             break

examples/datachannel-vpn/vpn.py

@@ -26,7 +26,7 @@ async def consume_signaling(pc, signaling):
                 await pc.setLocalDescription(await pc.createAnswer())
                 await signaling.send(pc.localDescription)
         elif isinstance(obj, RTCIceCandidate):
-            pc.addIceCandidate(obj)
+            await pc.addIceCandidate(obj)
         elif obj is BYE:
             print("Exiting")
             break

examples/videostream-cli/cli.py

@@ -115,7 +115,7 @@ def on_track(track):
                 await pc.setLocalDescription(await pc.createAnswer())
                 await signaling.send(pc.localDescription)
         elif isinstance(obj, RTCIceCandidate):
-            pc.addIceCandidate(obj)
+            await pc.addIceCandidate(obj)
         elif obj is BYE:
             print("Exiting")
             break

src/aiortc/rtcicetransport.py

@@ -270,7 +270,7 @@ def state(self) -> str:
         """
         return self.__state
 
-    def addRemoteCandidate(self, candidate: Optional[RTCIceCandidate]) -> None:
+    async def addRemoteCandidate(self, candidate: Optional[RTCIceCandidate]) -> None:
         """
         Add a remote candidate.
 

src/aiortc/rtcpeerconnection.py

@@ -149,13 +149,14 @@ def add_transport_description(
         media.dtls.fingerprints = dtlsTransport.getLocalParameters().fingerprints
 
 
-def add_remote_candidates(
+async def add_remote_candidates(
     iceTransport: RTCIceTransport, media: sdp.MediaDescription
 ) -> None:
-    for candidate in media.ice_candidates:
-        iceTransport.addRemoteCandidate(candidate)
+    coros = map(iceTransport.addRemoteCandidate, media.ice_candidates)
+    await asyncio.gather(*coros)
+
     if media.ice_candidates_complete:
-        iceTransport.addRemoteCandidate(None)
+        await iceTransport.addRemoteCandidate(None)
 
 
 def allocate_mid(mids: Set[str]) -> str:
@@ -335,7 +336,7 @@ def sctp(self) -> Optional[RTCSctpTransport]:
     def signalingState(self):
         return self.__signalingState
 
-    def addIceCandidate(self, candidate: RTCIceCandidate) -> None:
+    async def addIceCandidate(self, candidate: RTCIceCandidate) -> None:
         """
         Add a new :class:`RTCIceCandidate` received from the remote peer.
 
@@ -349,7 +350,7 @@ def addIceCandidate(self, candidate: RTCIceCandidate) -> None:
         for transceiver in self.__transceivers:
             if candidate.sdpMid == transceiver.mid and not transceiver._bundled:
                 iceTransport = transceiver._transport.transport
-                iceTransport.addRemoteCandidate(candidate)
+                await iceTransport.addRemoteCandidate(candidate)
                 return
 
         if (
@@ -358,7 +359,7 @@ def addIceCandidate(self, candidate: RTCIceCandidate) -> None:
             and not self.__sctp._bundled
         ):
             iceTransport = self.__sctp.transport.transport
-            iceTransport.addRemoteCandidate(candidate)
+            await iceTransport.addRemoteCandidate(candidate)
 
     def addTrack(self, track: MediaStreamTrack) -> RTCRtpSender:
         """
@@ -835,7 +836,7 @@ async def setRemoteDescription(
             if dtlsTransport is not None:
                 # add ICE candidates
                 iceTransport = dtlsTransport.transport
-                add_remote_candidates(iceTransport, media)
+                await add_remote_candidates(iceTransport, media)
 
                 # set ICE role
                 if description.type == "offer" and not iceTransport._role_set:

tests/test_ortc.py

@@ -31,9 +31,9 @@ async def start_ice_pair():
     await asyncio.gather(ice_a.iceGatherer.gather(), ice_b.iceGatherer.gather())
 
     for candidate in ice_b.iceGatherer.getLocalCandidates():
-        ice_a.addRemoteCandidate(candidate)
+        await ice_a.addRemoteCandidate(candidate)
     for candidate in ice_a.iceGatherer.getLocalCandidates():
-        ice_b.addRemoteCandidate(candidate)
+        await ice_b.addRemoteCandidate(candidate)
     await asyncio.gather(
         ice_a.start(ice_b.iceGatherer.getLocalParameters()),
         ice_b.start(ice_a.iceGatherer.getLocalParameters()),

tests/test_rtcicetransport.py

@@ -261,11 +261,11 @@ def test_construct(self):
         )
 
         # add candidate
-        connection.addRemoteCandidate(candidate)
+        run(connection.addRemoteCandidate(candidate))
         self.assertEqual(connection.getRemoteCandidates(), [candidate])
 
         # end-of-candidates
-        connection.addRemoteCandidate(None)
+        run(connection.addRemoteCandidate(None))
         self.assertEqual(connection.getRemoteCandidates(), [candidate])
 
     def test_connect(self):
@@ -278,9 +278,9 @@ def test_connect(self):
         # gather candidates
         run(asyncio.gather(gatherer_1.gather(), gatherer_2.gather()))
         for candidate in gatherer_2.getLocalCandidates():
-            transport_1.addRemoteCandidate(candidate)
+            run(transport_1.addRemoteCandidate(candidate))
         for candidate in gatherer_1.getLocalCandidates():
-            transport_2.addRemoteCandidate(candidate)
+            run(transport_2.addRemoteCandidate(candidate))
         self.assertEqual(transport_1.state, "new")
         self.assertEqual(transport_2.state, "new")
 
@@ -309,9 +309,9 @@ def test_connect_fail(self):
         # gather candidates
         run(asyncio.gather(gatherer_1.gather(), gatherer_2.gather()))
         for candidate in gatherer_2.getLocalCandidates():
-            transport_1.addRemoteCandidate(candidate)
+            run(transport_1.addRemoteCandidate(candidate))
         for candidate in gatherer_1.getLocalCandidates():
-            transport_2.addRemoteCandidate(candidate)
+            run(transport_2.addRemoteCandidate(candidate))
         self.assertEqual(transport_1.state, "new")
         self.assertEqual(transport_2.state, "new")
 

tests/test_rtcpeerconnection.py

@@ -394,15 +394,17 @@ def tearDown(self):
     def test_addIceCandidate_no_sdpMid_or_sdpMLineIndex(self):
         pc = RTCPeerConnection()
         with self.assertRaises(ValueError) as cm:
-            pc.addIceCandidate(
-                RTCIceCandidate(
-                    component=1,
-                    foundation="0",
-                    ip="192.168.99.7",
-                    port=33543,
-                    priority=2122252543,
-                    protocol="UDP",
-                    type="host",
+            run(
+                pc.addIceCandidate(
+                    RTCIceCandidate(
+                        component=1,
+                        foundation="0",
+                        ip="192.168.99.7",
+                        port=33543,
+                        priority=2122252543,
+                        protocol="UDP",
+                        type="host",
+                    )
                 )
             )
         self.assertEqual(
@@ -826,12 +828,12 @@ def test_connect_audio_bidirectional_with_trickle(self):
             iceGatherer = transceiver.sender.transport.transport.iceGatherer
             for candidate in iceGatherer.getLocalCandidates():
                 candidate.sdpMid = transceiver.mid
-                pc1.addIceCandidate(candidate)
+                run(pc1.addIceCandidate(candidate))
         for transceiver in pc1.getTransceivers():
             iceGatherer = transceiver.sender.transport.transport.iceGatherer
             for candidate in iceGatherer.getLocalCandidates():
                 candidate.sdpMid = transceiver.mid
-                pc2.addIceCandidate(candidate)
+                run(pc2.addIceCandidate(candidate))
 
         # check outcome
         self.assertIceCompleted(pc1, pc2)
@@ -3721,10 +3723,10 @@ def on_message(message):
         # trickle candidates
         for candidate in pc2.sctp.transport.transport.iceGatherer.getLocalCandidates():
             candidate.sdpMid = pc2.sctp.mid
-            pc1.addIceCandidate(candidate)
+            run(pc1.addIceCandidate(candidate))
         for candidate in pc1.sctp.transport.transport.iceGatherer.getLocalCandidates():
             candidate.sdpMid = pc1.sctp.mid
-            pc2.addIceCandidate(candidate)
+            run(pc2.addIceCandidate(candidate))
 
         # check outcome
         self.assertIceCompleted(pc1, pc2)