feat: Support in-place ICE restart with a new Agent

jvb/src/main/kotlin/org/jitsi/videobridge/Endpoint.kt

@@ -85,11 +85,13 @@ import org.jitsi.videobridge.relay.RelayedEndpoint
 import org.jitsi.videobridge.rest.root.debug.EndpointDebugFeatures
 import org.jitsi.videobridge.stats.PacketTransitStats
 import org.jitsi.videobridge.transport.dtls.DtlsTransport
+import org.jitsi.videobridge.transport.ice.IceRestartResult
 import org.jitsi.videobridge.transport.ice.IceTransport
 import org.jitsi.videobridge.util.ByteBufferPool
 import org.jitsi.videobridge.util.TaskPools
 import org.jitsi.videobridge.util.looksLikeDtls
 import org.jitsi.videobridge.websocket.colibriWebSocketServiceSupplier
+import org.jitsi.videobridge.websocket.generateColibriWebSocketPassword
 import org.jitsi.xmpp.extensions.colibri.WebSocketPacketExtension
 import org.jitsi.xmpp.extensions.jingle.DtlsFingerprintPacketExtension
 import org.jitsi.xmpp.extensions.jingle.IceUdpTransportPacketExtension
@@ -170,6 +172,13 @@ class Endpoint @JvmOverloads constructor(
         }
     }
 
+    /**
+     * The password which authenticates the colibri WebSocket of this endpoint. It is independent of ICE and
+     * stays the same for the lifetime of the endpoint, because the client re-dials the URL which contains it
+     * each time the WebSocket reconnects. See [generateColibriWebSocketPassword].
+     */
+    private val webSocketPassword = generateColibriWebSocketPassword()
+
     /* TODO: do we ever want to support useUniquePort for an Endpoint? */
     private val iceTransport = IceTransport(id, iceControlling, false, supportsPrivateAddresses, logger)
     private val dtlsTransport = DtlsTransport(logger, id).also { it.cryptex = CryptexConfig.endpoint }
@@ -731,11 +740,8 @@ class Endpoint @JvmOverloads constructor(
      * @return {@code true} iff the password matches.
      */
     fun acceptWebSocket(password: String): Boolean {
-        if (iceTransport.icePassword != password) {
-            logger.warn(
-                "Incoming web socket request with an invalid password. " +
-                    "Expected: ${iceTransport.icePassword} received $password"
-            )
+        if (webSocketPassword != password) {
+            logger.warn("Incoming web socket request with an invalid password.")
             return false
         }
         return true
@@ -786,6 +792,19 @@ class Endpoint @JvmOverloads constructor(
         iceTransport.startConnectivityEstablishment(transportInfo)
     }
 
+    /**
+     * Handles an explicit ICE restart request from this endpoint (colibri2 `<transport ice-restart="true"/>`).
+     *
+     * Creates a new ice4j Agent with freshly rotated local credentials alongside the established one, which
+     * keeps carrying media until the new one connects (make-before-break).
+     *
+     * @return what the caller must signal back to the endpoint: our new transport (returned by
+     * [describeTransport], which then describes the pending Agent) for [IceRestartResult.STARTED], the
+     * unchanged established transport for [IceRestartResult.KEEP_EXISTING], or no transport at all for
+     * [IceRestartResult.UNAVAILABLE].
+     */
+    fun requestIceRestart(): IceRestartResult = iceTransport.requestIceRestart()
+
     fun describeTransport(): IceUdpTransportPacketExtension {
         val iceUdpTransportPacketExtension = IceUdpTransportPacketExtension()
         iceTransport.describe(iceUdpTransportPacketExtension)
@@ -794,7 +813,7 @@ class Endpoint @JvmOverloads constructor(
             colibriWebsocketService.getColibriWebSocketUrls(
                 conference.id,
                 id,
-                iceTransport.icePassword
+                webSocketPassword
             ).forEach { wsUrl ->
                 val wsPacketExtension = WebSocketPacketExtension(wsUrl)
                 iceUdpTransportPacketExtension.addChildExtension(wsPacketExtension)

jvb/src/main/kotlin/org/jitsi/videobridge/colibri2/Colibri2ConferenceHandler.kt

@@ -31,6 +31,7 @@ import org.jitsi.videobridge.relay.AudioSourceDesc
 import org.jitsi.videobridge.relay.Relay
 import org.jitsi.videobridge.relay.RelayConfig
 import org.jitsi.videobridge.sctp.SctpConfig
+import org.jitsi.videobridge.transport.ice.IceRestartResult
 import org.jitsi.videobridge.util.PayloadTypeUtil.Companion.create
 import org.jitsi.videobridge.websocket.config.WebsocketServiceConfig
 import org.jitsi.videobridge.xmpp.MediaSourceFactory
@@ -257,19 +258,6 @@ class Colibri2ConferenceHandler(
         }
 
         c2endpoint.transport?.iceUdpTransport?.let { endpoint.setTransportInfo(it) }
-        if (c2endpoint.create) {
-            val transBuilder = Transport.getBuilder()
-            transBuilder.setIceUdpExtension(endpoint.describeTransport())
-            if (c2endpoint.transport?.sctp != null) {
-                transBuilder.setSctp(
-                    Sctp.Builder()
-                        .setPort(DcSctpTransport.DEFAULT_SCTP_PORT)
-                        .setRole(Sctp.Role.SERVER)
-                        .build()
-                )
-            }
-            respBuilder.setTransport(transBuilder.build())
-        }
 
         c2endpoint.sources?.let { sources ->
             if (endpoint.visitor && sources.mediaSources.isNotEmpty()) {
@@ -309,6 +297,50 @@ class Colibri2ConferenceHandler(
             endpoint.updateForceMute(it.audio, it.video)
         }
 
+        // An explicit ICE restart request. Handled after setTransportInfo, so any credentials included in this
+        // same request still belong to (and are applied to) the pre-restart Agent. The restart rotates our own
+        // ICE credentials, so the endpoint has to be told the new ones — its connectivity checks are addressed
+        // to them — even though this is not a create.
+        //
+        // Handled last, once nothing else in this request can throw: a restart is armed as a side effect (it
+        // rotates the credentials we advertise and starts the timeout), so failing the request after arming it
+        // would leave the bridge waiting out that timeout for an answer the endpoint was never asked for.
+        val iceRestartResult = if (c2endpoint.transport?.iceRestart == true) {
+            endpoint.requestIceRestart().also {
+                if (it != IceRestartResult.STARTED) {
+                    logger.warn("Did not restart ICE for endpoint ${c2endpoint.id}: $it.")
+                }
+            }
+        } else {
+            null
+        }
+
+        // How the refusal of a restart is signaled: with the *absence* of a <transport> in the
+        // conference-modified for this endpoint. There is no explicit "refused" flag, and the request is not
+        // failed with an error, because an error would fail the whole conference-modify and take every other
+        // endpoint's updates with it. Jicofo pairs a request it sent with the answer it gets back: a
+        // <transport> means the restart happened and is relayed to the endpoint, no <transport> means it did
+        // not and jicofo falls back to a re-invite.
+        //
+        // So a transport is signaled back for a restart that started (the new Agent's rotated credentials) and
+        // for one that kept the existing Agent (its unchanged credentials, so the endpoint keeps the connection
+        // it has, with no re-invite). Only IceRestartResult.UNAVAILABLE signals nothing.
+        if (c2endpoint.create || iceRestartResult == IceRestartResult.STARTED ||
+            iceRestartResult == IceRestartResult.KEEP_EXISTING
+        ) {
+            val transBuilder = Transport.getBuilder()
+            transBuilder.setIceUdpExtension(endpoint.describeTransport())
+            if (c2endpoint.transport?.sctp != null) {
+                transBuilder.setSctp(
+                    Sctp.Builder()
+                        .setPort(DcSctpTransport.DEFAULT_SCTP_PORT)
+                        .setRole(Sctp.Role.SERVER)
+                        .build()
+                )
+            }
+            respBuilder.setTransport(transBuilder.build())
+        }
+
         return respBuilder.build()
     }
 

jvb/src/main/kotlin/org/jitsi/videobridge/ice/IceConfig.kt

@@ -22,6 +22,7 @@ import org.jitsi.config.JitsiConfig
 import org.jitsi.metaconfig.config
 import org.jitsi.metaconfig.from
 import org.jitsi.metaconfig.optionalconfig
+import java.time.Duration
 
 class IceConfig private constructor() {
     /**
@@ -70,6 +71,34 @@ class IceConfig private constructor() {
         "videobridge.ice.advertise-private-candidates".from(JitsiConfig.newConfig)
     )
 
+    /**
+     * Whether ICE restarts are enabled: when an endpoint explicitly requests one (colibri2
+     * `<transport ice-restart="true"/>`), create a second [org.ice4j.ice.Agent] with rotated local credentials
+     * and run it alongside the established one, instead of rejecting the request.
+     */
+    val restartEnabled: Boolean by config(
+        "videobridge.ice.restart.enabled".from(JitsiConfig.newConfig)
+    )
+
+    /**
+     * How long the old [org.ice4j.ice.Agent] is kept alive after an ICE restart has cut over to the new one.
+     * Both Agents keep their sockets during this window, and ice4j routes each packet by the address it came
+     * from, so the endpoint's old-generation checks — which come from its old address — are answered by the old
+     * Agent rather than dropped.
+     */
+    val restartTransitionWindow: Duration by config(
+        "videobridge.ice.restart.transition-window".from(JitsiConfig.newConfig)
+    )
+
+    /**
+     * How long to wait for the new [org.ice4j.ice.Agent] of an ICE restart to connect before giving up on the
+     * restart and keeping the existing Agent. A value that is not positive disables ICE restarts: the new Agent
+     * would be freed before the endpoint could answer it.
+     */
+    val restartTimeout: Duration by config(
+        "videobridge.ice.restart.timeout".from(JitsiConfig.newConfig)
+    )
+
     companion object {
         @JvmField
         val config = IceConfig()

jvb/src/main/kotlin/org/jitsi/videobridge/relay/Relay.kt

@@ -97,6 +97,7 @@ import org.jitsi.videobridge.util.ByteBufferPool
 import org.jitsi.videobridge.util.TaskPools
 import org.jitsi.videobridge.util.looksLikeDtls
 import org.jitsi.videobridge.websocket.colibriWebSocketServiceSupplier
+import org.jitsi.videobridge.websocket.generateColibriWebSocketPassword
 import org.jitsi.xmpp.extensions.colibri.WebSocketPacketExtension
 import org.jitsi.xmpp.extensions.colibri2.Sctp
 import org.jitsi.xmpp.extensions.jingle.DtlsFingerprintPacketExtension
@@ -201,6 +202,13 @@ class Relay @JvmOverloads constructor(
         }
     }
 
+    /**
+     * The password which authenticates the colibri WebSocket of this relay. It is independent of ICE and stays
+     * the same for the lifetime of the relay, because the peer re-dials the URL which contains it each time the
+     * WebSocket reconnects. See [generateColibriWebSocketPassword].
+     */
+    private val webSocketPassword = generateColibriWebSocketPassword()
+
     private val iceTransport = IceTransport(
         id = id,
         controlling = iceControlling,
@@ -540,7 +548,7 @@ class Relay @JvmOverloads constructor(
                     val urls = colibriWebsocketService.getColibriRelayWebSocketUrls(
                         conference.id,
                         id,
-                        iceTransport.icePassword
+                        webSocketPassword
                     )
                     if (urls.isEmpty()) {
                         logger.warn("No colibri relay URLs configured")
@@ -872,11 +880,8 @@ class Relay @JvmOverloads constructor(
      * @return {@code true} iff the password matches.
      */
     fun acceptWebSocket(password: String): Boolean {
-        if (iceTransport.icePassword != password) {
-            logger.warn(
-                "Incoming web socket request with an invalid password. " +
-                    "Expected: ${iceTransport.icePassword} received $password"
-            )
+        if (webSocketPassword != password) {
+            logger.warn("Incoming web socket request with an invalid password.")
             return false
         }
         return true