Implement TCP candidate priority with offsets

By default it is UDP one minus 27 (except relay).
It is can be configured using AgentConfig.

Author: ashellunts

agent.go

@@ -73,6 +73,8 @@ type Agent struct {
 	prflxAcceptanceMinWait time.Duration
 	relayAcceptanceMinWait time.Duration
 
+	tcpPriorityOffset uint16
+
 	portMin uint16
 	portMax uint16
 

agent_config.go

@@ -41,6 +41,10 @@ const (
 	// defaultMaxBindingRequests is the maximum number of binding requests before considering a pair failed
 	defaultMaxBindingRequests = 7
 
+	// TCPPriorityOffset is a number which is subtracted from the default (UDP) candidate type preference
+	// for host, srflx and prfx candidate types.
+	defaultTCPPriorityOffset = 27
+
 	// maxBufferSize is the number of bytes that can be buffered before we start to error
 	maxBufferSize = 1000 * 1000 // 1MB
 
@@ -177,6 +181,12 @@ type AgentConfig struct {
 
 	// Include loopback addresses in the candidate list.
 	IncludeLoopback bool
+
+	// TCPPriorityOffset is a number which is subtracted from the default (UDP) candidate type preference
+	// for host, srflx and prfx candidate types. It helps to configure relative preference of UDP candidates
+	// against TCP ones. Relay candidates for TCP and UDP are always 0 and not affected by this setting.
+	// When this is nil, defaultTCPPriorityOffset is used.
+	TCPPriorityOffset *uint16
 }
 
 // initWithDefaults populates an agent and falls back to defaults if fields are unset
@@ -211,6 +221,12 @@ func (config *AgentConfig) initWithDefaults(a *Agent) {
 		a.relayAcceptanceMinWait = *config.RelayAcceptanceMinWait
 	}
 
+	if config.TCPPriorityOffset == nil {
+		a.tcpPriorityOffset = defaultTCPPriorityOffset
+	} else {
+		a.tcpPriorityOffset = *config.TCPPriorityOffset
+	}
+
 	if config.DisconnectedTimeout == nil {
 		a.disconnectedTimeout = defaultDisconnectedTimeout
 	} else {

candidate_base.go

@@ -355,7 +355,13 @@ func (c *candidateBase) Priority() uint32 {
 	// candidates for a particular component for a particular data stream
 	// that have the same type, the local preference MUST be unique for each
 	// one.
-	return (1<<24)*uint32(c.Type().Preference(c.networkType)) +
+
+	var tcpPriorityOffset uint16 = defaultTCPPriorityOffset
+	if c.agent() != nil {
+		tcpPriorityOffset = c.agent().tcpPriorityOffset
+	}
+
+	return (1<<24)*uint32(c.Type().Preference(c.networkType, tcpPriorityOffset)) +
 		(1<<8)*uint32(c.LocalPreference()) +
 		uint32(256-c.Component())
 }

candidate_test.go

@@ -78,7 +78,7 @@ func TestCandidatePriority(t *testing.T) {
 					tcpType:       TCPTypeSimultaneousOpen,
 				},
 			},
-			WantPriority: 1658847231,
+			WantPriority: 1407188991,
 		},
 		{
 			Candidate: &CandidatePeerReflexive{
@@ -89,7 +89,7 @@ func TestCandidatePriority(t *testing.T) {
 					tcpType:       TCPTypeActive,
 				},
 			},
-			WantPriority: 1654652927,
+			WantPriority: 1402994687,
 		},
 		{
 			Candidate: &CandidatePeerReflexive{
@@ -100,7 +100,7 @@ func TestCandidatePriority(t *testing.T) {
 					tcpType:       TCPTypePassive,
 				},
 			},
-			WantPriority: 1650458623,
+			WantPriority: 1398800383,
 		},
 		{
 			Candidate: &CandidateServerReflexive{

candidatetype.go

@@ -38,32 +38,24 @@ func (c CandidateType) String() string {
 // The RECOMMENDED values are 126 for host candidates, 100
 // for server reflexive candidates, 110 for peer reflexive candidates,
 // and 0 for relayed candidates.
-func (c CandidateType) Preference(networkType NetworkType) uint16 {
-	if networkType == NetworkTypeTCP4 || networkType == NetworkTypeTCP6 {
-		switch c {
-		case CandidateTypeHost:
-			return 99
-		case CandidateTypePeerReflexive:
-			return 98
-		case CandidateTypeServerReflexive:
-			return 97
-		case CandidateTypeRelay, CandidateTypeUnspecified:
-			return 0
-		}
-	}
-
-	// UDP candidates
+func (c CandidateType) Preference(networkType NetworkType, tcpOffset uint16) uint16 {
+	var result uint16
 	switch c {
 	case CandidateTypeHost:
-		return 126
+		result = 126
 	case CandidateTypePeerReflexive:
-		return 110
+		result = 110
 	case CandidateTypeServerReflexive:
-		return 100
+		result = 100
 	case CandidateTypeRelay, CandidateTypeUnspecified:
 		return 0
+	default:
+		return 0
+	}
+	if networkType.IsTCP() {
+		return result - tcpOffset
 	}
-	return 0
+	return result
 }
 
 func containsCandidateType(candidateType CandidateType, candidateTypeList []CandidateType) bool {

candidatetype_test.go

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2023 The Pion community <https://pion.ly>
+// SPDX-License-Identifier: MIT
+
+package ice
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestCandidateTypePreference(t *testing.T) {
+	r := require.New(t)
+
+	hostDefaultPreference := uint16(126)
+	prflxDefaultPreference := uint16(110)
+	srflxDefaultPreference := uint16(100)
+	relayDefaultPreference := uint16(0)
+	unspecifiedDefaultPreference := uint16(0)
+
+	tcpOffsets := []uint16{0, 10}
+
+	for _, tcpOffset := range tcpOffsets {
+		for _, networkType := range supportedNetworkTypes() {
+			if networkType.IsTCP() {
+				r.Equal(hostDefaultPreference-tcpOffset, CandidateTypeHost.Preference(networkType, tcpOffset))
+				r.Equal(prflxDefaultPreference-tcpOffset, CandidateTypePeerReflexive.Preference(networkType, tcpOffset))
+				r.Equal(srflxDefaultPreference-tcpOffset, CandidateTypeServerReflexive.Preference(networkType, tcpOffset))
+			} else {
+				r.Equal(hostDefaultPreference, CandidateTypeHost.Preference(networkType, tcpOffset))
+				r.Equal(prflxDefaultPreference, CandidateTypePeerReflexive.Preference(networkType, tcpOffset))
+				r.Equal(srflxDefaultPreference, CandidateTypeServerReflexive.Preference(networkType, tcpOffset))
+			}
+		}
+	}
+	for _, tcpOffset := range tcpOffsets {
+		for _, networkType := range supportedNetworkTypes() {
+			r.Equal(relayDefaultPreference, CandidateTypeRelay.Preference(networkType, tcpOffset))
+			r.Equal(unspecifiedDefaultPreference, CandidateTypeUnspecified.Preference(networkType, tcpOffset))
+		}
+	}
+}