feat: Enhance TURN relay session handling and ICE transport policies

- Introduced `iceTransportPolicy` to `RoomMediaStartupConfiguration` to control candidate selection based on transport type (all or relay).
- Updated candidate selection logic to respect the new `iceTransportPolicy`, allowing suppression of host candidates when using relay-only TURN.
- Added support for TCP and TLS endpoints in `TURNRelaySessionConfiguration`, enabling fallback to TCP when UDP endpoints are unavailable.
- Implemented `TURNStreamTransport` for handling TCP/TLS connections, including sending and receiving data over network streams.
- Created integration tests for TURN-only media startup scenarios and validated behavior with credentialed TURN relays.
- Enhanced documentation to reflect changes in TURN relay session orchestration and ICE candidate planning.

Author: MarlonJD

README.md

@@ -213,8 +213,10 @@ maintenance execution, due action scheduling, relay ICE candidate planning,
 default UDP TURN relay allocation through the bound Room ICE socket, ChannelData
 relay bindings for relayed ICE checks/media datagrams, and TURN relay session
 configuration selection plus UDP/TCP/TLS fallback planning from parsed ICE
-server endpoints, plus bounded TURN relay session orchestration and
-deterministic setup-plan execution over abstract transports, peer
+server endpoints, plus bounded TURN relay session orchestration,
+deterministic setup-plan execution over abstract transports, TCP/TLS stream
+TURN setup execution, and relay-only ICE candidate policy for TURN-only
+validation, peer
 negotiation state reset across
 fresh join/reconnect/disconnect boundaries, RTCP
 sender/receiver report and bounded PLI/NACK subscriber feedback planning,
@@ -281,8 +283,8 @@ latest-value Room state and emitted as typed room events.
 The active implementation focus is now `1.0.0` hardening: expanding the new
 opt-in LiveKit-validated OpenSSL DTLS-SRTP publisher/subscriber media startup
 coverage, including selected ICE pair and default media/data session assertions,
-into full secure RTP/RTCP send/receive validation, TURN TCP/TLS, live
-quality-control wiring, real-device video display hardening,
+into full secure RTP/RTCP send/receive validation, live quality-control wiring,
+CI-gated TURN-only validation, real-device video display hardening,
 default-path DTLS-SCTP association receive-pump integration, LiveKit-validated
 data-channel recovery, hardening the default-gated live data-packet
 publish/receive smoke once standards SCTP is fully complete, real-device audio
@@ -401,9 +403,9 @@ configuration through `RoomOptions.automaticallyConfigureAudioSession`, and matc
 `RequestResponse` failure
 mapping are unit-tested, while LiveKit E2E media validation, real-device video
 display validation, standards-compliant live SCTP association behavior, TURN
-TCP/TLS execution, actual multi-layer simulcast/SVC media production, media
-recovery, route/interruption audio recovery, and end-to-end LiveKit hardening
-are still open.
+maintenance loop binding in default Room, CI-gated TURN-only validation, actual
+multi-layer simulcast/SVC media production, media recovery, route/interruption
+audio recovery, and end-to-end LiveKit hardening are still open.
 
 ## Benchmarks
 
@@ -491,6 +493,11 @@ are included in the default integration gate whenever
 `LIVEKIT_NATIVE_RUN_INTEGRATION=1` is set. Strict production release mode now
 requires those integration variables so the future `productionReady` marker
 cannot pass while live tests are silently skipped.
+TURN-only media startup validation is additionally gated by
+`LIVEKIT_NATIVE_RUN_TURN_ONLY=1` and requires a LiveKit server that advertises
+credentialed TURN relay ICE servers; the test uses
+`RoomOptions.iceTransportPolicy = .relay` to suppress host and
+server-reflexive candidates.
 
 ## Requirements
 

Sources/LiveKitNative/Core/Options.swift

@@ -1,5 +1,10 @@
 import Foundation
 
+public enum ICETransportPolicy: String, Equatable, Sendable {
+    case all
+    case relay
+}
+
 public struct RoomOptions: Equatable, Sendable {
     public var defaultAutoSubscribe: Bool
     public var defaultAdaptiveStream: Bool?
@@ -11,6 +16,7 @@ public struct RoomOptions: Equatable, Sendable {
     public var automaticallyPlaySubscriberAudio: Bool
     public var automaticallyConfigureAudioSession: Bool
     public var audioSessionConfiguration: AudioSessionConfiguration
+    public var iceTransportPolicy: ICETransportPolicy
 
     public init(
         defaultAutoSubscribe: Bool = true,
@@ -22,7 +28,8 @@ public struct RoomOptions: Equatable, Sendable {
         automaticallyDecodeSubscriberVideo: Bool = false,
         automaticallyPlaySubscriberAudio: Bool = false,
         automaticallyConfigureAudioSession: Bool = false,
-        audioSessionConfiguration: AudioSessionConfiguration = .voiceChat
+        audioSessionConfiguration: AudioSessionConfiguration = .voiceChat,
+        iceTransportPolicy: ICETransportPolicy = .all
     ) {
         self.defaultAutoSubscribe = defaultAutoSubscribe
         self.defaultAdaptiveStream = defaultAdaptiveStream
@@ -34,6 +41,7 @@ public struct RoomOptions: Equatable, Sendable {
         self.automaticallyPlaySubscriberAudio = automaticallyPlaySubscriberAudio
         self.automaticallyConfigureAudioSession = automaticallyConfigureAudioSession
         self.audioSessionConfiguration = audioSessionConfiguration
+        self.iceTransportPolicy = iceTransportPolicy
     }
 }
 

Sources/LiveKitNative/Core/ProductionReadiness.swift

@@ -29,7 +29,7 @@ public extension LiveKitNative {
         status: .developerPreview,
         blockers: [
             "ICEAgent nomination, local ICE trickle signaling, server ICE server configuration application, STUN UDP server-reflexive candidate gathering, bound local ICE UDP host candidate gathering and socket reuse for STUN checks and media datagrams, default Room socket-backed subscriber/publisher media-data startup configuration, OpenSSL-backed WebRTC DTLS-SRTP use_srtp handshake/exporter wiring, DTLS-SRTP packet protection, RFC 5764 DTLS/SRTP datagram demux, shared persistent DTLS application-data plus SRTP session binding, SDP DTLS role/fingerprint extraction, handshaker-backed media-session binding with result role/profile validation, injected Room publisher/subscriber media startup, injected selected-pair ICE consent freshness loop with transport closure on expiry, injected publisher transport teardown, Room publisher RTP/RTCP and subscriber RTCP bridges through injected secure media transport, publisher and subscriber RTCP receive-handler loops, deterministic NACK/PLI RTCP feedback policy primitives, bounded subscriber feedback planning from H.264/VP8 RTP loss signals, Room subscriber feedback dispatch through injected subscriber RTCP transport, bounded RTP jitter-buffer primitives, stateful Opus/H.264 publisher RTP packetizer bridges, native camera/microphone publisher capture pipelines, Room publisher RTP sender registry lifecycle coverage, and subscriber RTP jitter-buffer/feedback dispatch exist, but production readiness still needs LiveKit server E2E secure RTP/RTCP integration, default TURN relay execution, Apple-platform OpenSSL packaging validation, and the remaining media pipeline gates.",
-            "Fresh join, resume reconnect, disconnect, and failed signal-loop boundaries regenerate local ICE credentials, clear stale peer negotiation state, parse TURN UDP/TCP/TLS endpoint configuration, order TURN relay fallback candidates as UDP, TCP, then TLS while identifying the currently executable UDP datagram path, select supported TURN UDP relay session configurations from parsed ICE server endpoints with credentials, exercise TURN Allocate, Refresh, CreatePermission, and ChannelBind request/authentication/response-validation primitives with one-shot stale nonce retry, cover TURN ChannelData framing, provide deterministic allocation/permission maintenance scheduling and execution, plan relayed ICE candidates from TURN bindings, compose and execute a bounded TURN relay session setup plan over abstract transports, expose a ChannelData relay transport over an abstract media datagram transport, allocate default UDP TURN relay candidates through the bound Room ICE socket, use ChannelData relay bindings for relayed ICE checks and media datagrams, provide deterministic ICE consent freshness planning plus an injected Room startup loop, run ICEAgent connectivity checks through paced scheduling with queued triggered-check priority plus role-conflict role switching and pair-priority recompute, and rebuild reconnect SyncState SDP/trickle state with fresh local ICE credentials, but TCP/TLS TURN transport execution, LiveKit TURN-only validation, and live media recovery are not complete.",
+            "Fresh join, resume reconnect, disconnect, and failed signal-loop boundaries regenerate local ICE credentials, clear stale peer negotiation state, parse TURN UDP/TCP/TLS endpoint configuration, order TURN relay fallback candidates as UDP, TCP, then TLS, select supported TURN relay session configurations from parsed ICE server endpoints with credentials, exercise TURN Allocate, Refresh, CreatePermission, and ChannelBind request/authentication/response-validation primitives with one-shot stale nonce retry, cover TURN ChannelData framing, provide deterministic allocation/permission maintenance scheduling and execution, plan relayed ICE candidates from TURN bindings, compose and execute bounded TURN relay session setup plans over UDP datagram and TCP/TLS stream transports, expose ChannelData relay transports over abstract media datagram transports, allocate default UDP TURN relay candidates through the bound Room ICE socket, use ChannelData relay bindings for relayed ICE checks and media datagrams, provide relay-only ICE candidate policy plus an opt-in LiveKit TURN-only validation harness, provide deterministic ICE consent freshness planning plus an injected Room startup loop, run ICEAgent connectivity checks through paced scheduling with queued triggered-check priority plus role-conflict role switching and pair-priority recompute, and rebuild reconnect SyncState SDP/trickle state with fresh local ICE credentials, but TURN maintenance loop binding in default Room, CI-gated TURN-only validation, and live media recovery are not complete.",
             "Publisher camera capture can encode H.264 through VideoToolbox with bounded frame backpressure/drop control and publisher microphone capture can encode Opus through AudioToolbox before RTP/SRTP send, while subscriber RTP can pass through jitter buffering, H.264/Opus packet assembly, NACK/PLI feedback, opt-in Opus decode-to-audio-playout scheduling, opt-in H.264 VideoToolbox decode-to-pixel-buffer scheduling, application-provided subscriber video renderer handoff, UIKit/AppKit VideoView sample-buffer rendering, and opt-in iOS voice-chat audio-session lifecycle configuration; real-device video display validation, LiveKit E2E media validation, route/interruption audio recovery, and production runtime pacing remain incomplete.",
             "Production H.264 now uses real VideoToolbox encode output for publish smoke coverage, opt-in VideoToolbox decode output for subscribe smoke coverage, and UIKit/AppKit VideoView rendering for decoded frames, but production readiness still requires real-device display validation, hardware acceleration verification where the OS exposes that signal, and explicit fallback behavior instead of relying on a pure Swift codec implementation.",
             "SCTP data channel support includes packet-level DCEP/DataPacket planning, manager-assigned stream routing, queued local publish flushing, inbound DataPacket-to-RoomEvent plumbing, publisher SDP data-channel negotiation, subscriber-side data-channel receive-loop plumbing, OpenSSL DTLS application-data transport coverage, default Room shared-media DTLS/SRTP demux binding, deterministic packet fragmentation/reassembly envelopes, fragmented-packet retransmission scheduling on the DTLS-backed packet transport, opt-in standards-shaped SCTP association bootstrap with DATA/SACK exchange, fragmented DATA reassembly, duplicate DATA TSN suppression, contiguous cumulative SACK tracking with gap/duplicate reporting, ordered contiguous TSN delivery, outbound DATA TSN acknowledgement tracking with SACK gap-triggered retransmission of unacknowledged outbound DATA TSN holes, recovery reset that reopens LiveKit data channels after association restart, and default-gated two-client LiveKit DataPacket publish/receive smoke over that standards-shaped association transport, but full standards-compliant SCTP association state, congestion control, LiveKit-validated data-channel recovery, and E2E hardening are incomplete.",

Sources/LiveKitNative/Core/Room.swift

@@ -70,6 +70,7 @@ struct RoomMediaStartupConfiguration: Sendable {
         iceRole: ICEAgentRole = .controlling,
         tieBreaker: UInt64 = UInt64.random(in: 1 ... UInt64.max),
         nominationPolicy: ICEPairNominationPolicy = .nominateFirstSuccessful,
+        iceTransportPolicy: ICETransportPolicy = .all,
         localCredentials: @escaping @Sendable () -> ICECredentials? = { nil },
         handshaker: any DTLSSRTPHandshaking,
         consentFreshnessPolicy: ICEConsentFreshnessPolicy = .standard,
@@ -87,7 +88,12 @@ struct RoomMediaStartupConfiguration: Sendable {
                 let turnRelayCandidates = turnRelayContexts.map {
                     LocalICEUDPSocketCandidate(candidate: $0.candidate, socket: $0.socket)
                 }
-                let allCandidates = localCandidateSockets + serverReflexiveCandidates + turnRelayCandidates
+                let allCandidates = switch iceTransportPolicy {
+                case .all:
+                    localCandidateSockets + serverReflexiveCandidates + turnRelayCandidates
+                case .relay:
+                    turnRelayCandidates
+                }
                 candidateStore.replace(with: allCandidates, turnRelayContexts: turnRelayContexts)
                 return allCandidates.map(\.candidate)
             },
@@ -121,6 +127,7 @@ struct RoomMediaStartupConfiguration: Sendable {
         iceRole: ICEAgentRole = .controlling,
         tieBreaker: UInt64 = UInt64.random(in: 1 ... UInt64.max),
         nominationPolicy: ICEPairNominationPolicy = .nominateFirstSuccessful,
+        iceTransportPolicy: ICETransportPolicy = .all,
         localCredentials: @escaping @Sendable () -> ICECredentials? = { nil },
         handshaker: any DTLSSRTPHandshaking,
         consentFreshnessPolicy: ICEConsentFreshnessPolicy = .standard,
@@ -135,6 +142,7 @@ struct RoomMediaStartupConfiguration: Sendable {
             iceRole: iceRole,
             tieBreaker: tieBreaker,
             nominationPolicy: nominationPolicy,
+            iceTransportPolicy: iceTransportPolicy,
             localCredentials: localCredentials,
             handshaker: handshaker,
             consentFreshnessPolicy: consentFreshnessPolicy,
@@ -151,6 +159,7 @@ struct RoomMediaStartupConfiguration: Sendable {
         iceRole: ICEAgentRole = .controlling,
         tieBreaker: UInt64 = UInt64.random(in: 1 ... UInt64.max),
         nominationPolicy: ICEPairNominationPolicy = .nominateFirstSuccessful,
+        iceTransportPolicy: ICETransportPolicy = .all,
         localCredentials: @escaping @Sendable () -> ICECredentials? = { nil },
         handshaker: any DTLSSRTPHandshaking = OpenSSLDTLSSRTPHandshaker(),
         consentFreshnessPolicy: ICEConsentFreshnessPolicy = .standard,
@@ -161,7 +170,8 @@ struct RoomMediaStartupConfiguration: Sendable {
             candidateStore: candidateStore,
             hostCandidateAddresses: hostCandidateAddresses,
             bindAddress: bindAddress,
-            receiveTimeoutMilliseconds: receiveTimeoutMilliseconds
+            receiveTimeoutMilliseconds: receiveTimeoutMilliseconds,
+            iceTransportPolicy: iceTransportPolicy
         )
 
         return Self(
@@ -200,6 +210,7 @@ struct RoomMediaStartupConfiguration: Sendable {
         iceRole: ICEAgentRole = .controlling,
         tieBreaker: UInt64 = UInt64.random(in: 1 ... UInt64.max),
         nominationPolicy: ICEPairNominationPolicy = .nominateFirstSuccessful,
+        iceTransportPolicy: ICETransportPolicy = .all,
         localCredentials: @escaping @Sendable () -> ICECredentials? = { nil },
         identity: DTLSSRTPIdentity = .generated(),
         receiveAttemptLimit: Int = 64,
@@ -213,7 +224,8 @@ struct RoomMediaStartupConfiguration: Sendable {
             candidateStore: candidateStore,
             hostCandidateAddresses: hostCandidateAddresses,
             bindAddress: bindAddress,
-            receiveTimeoutMilliseconds: receiveTimeoutMilliseconds
+            receiveTimeoutMilliseconds: receiveTimeoutMilliseconds,
+            iceTransportPolicy: iceTransportPolicy
         )
         let datagramFactory = LocalICEUDPSocketMediaDatagramTransportFactory(
             candidateStore: candidateStore,
@@ -259,19 +271,22 @@ private final class DefaultRoomMediaStartupLocalCandidateProvider: @unchecked Se
     private let hostCandidateAddresses: @Sendable () -> [ICEInterfaceAddress]
     private let bindAddress: String
     private let receiveTimeoutMilliseconds: Int
+    private let iceTransportPolicy: ICETransportPolicy
     private let lock = NSLock()
     private var hostCandidates: [LocalICEUDPSocketCandidate]?
 
     init(
         candidateStore: LocalICEUDPSocketCandidateStore,
         hostCandidateAddresses: @escaping @Sendable () -> [ICEInterfaceAddress],
         bindAddress: String,
-        receiveTimeoutMilliseconds: Int
+        receiveTimeoutMilliseconds: Int,
+        iceTransportPolicy: ICETransportPolicy = .all
     ) {
         self.candidateStore = candidateStore
         self.hostCandidateAddresses = hostCandidateAddresses
         self.bindAddress = bindAddress
         self.receiveTimeoutMilliseconds = receiveTimeoutMilliseconds
+        self.iceTransportPolicy = iceTransportPolicy
     }
 
     func localCandidates(iceServers: [ICEServer]) -> [ICECandidate] {
@@ -286,7 +301,12 @@ private final class DefaultRoomMediaStartupLocalCandidateProvider: @unchecked Se
             let turnRelayCandidates = turnRelayContexts.map {
                 LocalICEUDPSocketCandidate(candidate: $0.candidate, socket: $0.socket)
             }
-            let candidates = hostCandidates + serverReflexiveCandidates + turnRelayCandidates
+            let candidates = switch iceTransportPolicy {
+            case .all:
+                hostCandidates + serverReflexiveCandidates + turnRelayCandidates
+            case .relay:
+                turnRelayCandidates
+            }
             candidateStore.replace(with: candidates, turnRelayContexts: turnRelayContexts)
             return candidates.map(\.candidate)
         }
@@ -732,12 +752,14 @@ public final class Room: @unchecked Sendable {
             subscriberPeerConnection: subscriberPeerConnection,
             publisherPeerConnection: publisherPeerConnection,
             subscriberMediaStartupConfiguration: .defaultLiveMediaData(
+                iceTransportPolicy: options.iceTransportPolicy,
                 localCredentials: {
                     subscriberPeerConnection.configuration.iceCredentials
                 },
                 identity: subscriberDTLSIdentity
             ),
             publisherMediaStartupConfiguration: .defaultLiveMediaData(
+                iceTransportPolicy: options.iceTransportPolicy,
                 localCredentials: {
                     publisherPeerConnection.configuration.iceCredentials
                 },