Skip connectivity checks in lite mode

Author: erivni

selection.go

@@ -435,11 +435,10 @@ func (s *controlledSelector) HandleBindingRequest(message *stun.Message, local,
 			return
 		}
 
-		if pair.state == CandidatePairStateSucceeded {
-			// If the state of this pair is Succeeded, it means that the check
-			// previously sent by this pair produced a successful response and
-			// generated a valid pair (Section 7.2.5.3.2).  The agent sets the
-			// nominated flag value of the valid pair to true.
+		if pair.state == CandidatePairStateSucceeded || s.agent.lite {
+			// For full agents: pair reached Succeeded via a triggered check (RFC 8445 §7.3.1.5).
+			// For lite agents: RFC 8445 §7.3.2 — the lite agent directly constructs the pair,
+			// places it in the valid list, and sets the nominated flag; no triggered check needed.
 			selectedPair := s.agent.getSelectedPair()
 			if s.shouldSwitchSelectedPair(pair, selectedPair, nominationValue) {
 				s.log.Tracef("Accepting nomination for pair %s", pair)
@@ -462,12 +461,13 @@ func (s *controlledSelector) HandleBindingRequest(message *stun.Message, local,
 
 	s.agent.sendBindingSuccess(message, local, remote)
 
-	// Only send a triggered check during ICE checking phase (RFC 8445 §7.3.1.4).
+	// Lite agents only act as STUN servers and MUST NOT generate connectivity checks (RFC 8445 §7).
+	// For full agents: only send a triggered check during ICE checking phase (RFC 8445 §7.3.1.4).
 	// Once the pair is established (succeeded + selected), sending a triggered check
 	// on every inbound request creates a ping-pong busy loop: the remote side responds
 	// and sends its own request, which triggers another check here, repeating at 1/RTT.
 	// After connection, consent freshness is maintained by checkKeepalive() on a timer.
-	if pair.state != CandidatePairStateSucceeded || s.agent.getSelectedPair() == nil {
+	if !s.agent.lite && (pair.state != CandidatePairStateSucceeded || s.agent.getSelectedPair() == nil) {
 		s.PingCandidate(local, remote)
 	}
 

selection_test.go

@@ -1491,3 +1491,182 @@ func TestControllingSideRenomination(t *testing.T) {
 			"Controlling agent should NOT switch with standard nomination when pair already selected")
 	})
 }
+
+// ---------------------------------------------------------------------------
+// Lite mode tests
+// ---------------------------------------------------------------------------
+
+// TestLiteControlledSelector_NoPingCandidate verifies that a lite controlled
+// agent NEVER sends triggered connectivity checks (PingCandidate), regardless
+// of the pair state. Per RFC 8445 §7, a lite implementation only acts as a
+// STUN server and does not generate connectivity checks.
+func TestLiteControlledSelector_NoPingCandidate(t *testing.T) {
+	buildMsg := func(t *testing.T, a *Agent) *stun.Message {
+		t.Helper()
+		msg, err := stun.Build(stun.BindingRequest,
+			stun.TransactionID,
+			stun.NewUsername(a.localUfrag+":"+a.remoteUfrag),
+			stun.NewShortTermIntegrity(a.localPwd),
+			stun.Fingerprint,
+		)
+		require.NoError(t, err)
+
+		return msg
+	}
+
+	setupAgent := func(t *testing.T) (*Agent, *pingNoIOCand, *pingNoIOCand, *CandidatePair) {
+		t.Helper()
+		liteAgent := bareAgentForPing()
+		liteAgent.log = logging.NewDefaultLoggerFactory().NewLogger("test")
+		liteAgent.remoteUfrag = selectionTestRemoteUfrag
+		liteAgent.localUfrag = selectionTestLocalUfrag
+		liteAgent.remotePwd = selectionTestPassword
+		liteAgent.localPwd = selectionTestPassword
+		liteAgent.tieBreaker = 1
+		liteAgent.lite = true
+		liteAgent.isControlling.Store(false)
+		liteAgent.onConnected = make(chan struct{})
+		liteAgent.setSelector()
+
+		local := newPingNoIOCand()
+		local.candidateBase.networkType = NetworkTypeUDP4
+		local.candidateBase.resolvedAddr = &net.UDPAddr{IP: net.ParseIP("192.168.1.1"), Port: 10000}
+
+		remote := newPingNoIOCand()
+		remote.candidateBase.networkType = NetworkTypeUDP4
+		remote.candidateBase.resolvedAddr = &net.UDPAddr{IP: net.ParseIP("192.168.1.2"), Port: 20000}
+
+		pair := liteAgent.addPair(local, remote)
+
+		return liteAgent, local, remote, pair
+	}
+
+	t.Run("NoTriggeredCheckWhileChecking", func(t *testing.T) {
+		// Pair is in Waiting state (ICE checking phase). A full controlled agent
+		// would send a triggered check here; a lite one must not.
+		agent, local, remote, pair := setupAgent(t)
+
+		ls, ok := agent.getSelector().(*liteSelector)
+		require.True(t, ok, "expected liteSelector as top-level selector")
+		_, ok = ls.pairCandidateSelector.(*controlledSelector)
+		require.True(t, ok, "expected controlledSelector inside liteSelector")
+
+		sentBefore := pair.RequestsSent()
+		msg := buildMsg(t, agent)
+
+		for range 5 {
+			ls.HandleBindingRequest(msg, local, remote)
+		}
+
+		assert.Equal(t, sentBefore, pair.RequestsSent(),
+			"lite controlled agent must not send triggered checks during ICE checking")
+	})
+
+	t.Run("NoTriggeredCheckWhenSucceededAndSelected", func(t *testing.T) {
+		// Pair is Succeeded and selected. Even a full agent suppresses checks here,
+		// but we verify the lite path also stays clean.
+		agent, local, remote, pair := setupAgent(t)
+		pair.state = CandidatePairStateSucceeded
+		agent.setSelectedPair(pair)
+
+		ls, ok := agent.getSelector().(*liteSelector)
+		require.True(t, ok)
+
+		sentBefore := pair.RequestsSent()
+		msg := buildMsg(t, agent)
+		ls.HandleBindingRequest(msg, local, remote)
+
+		assert.Equal(t, sentBefore, pair.RequestsSent(),
+			"lite controlled agent must not send triggered checks when pair is connected")
+	})
+
+	t.Run("NominationStillAccepted", func(t *testing.T) {
+		// A lite agent must still accept USE-CANDIDATE and set the selected pair
+		// (RFC 8445 §7.3.2), even though it never sends its own checks.
+		agent, local, remote, pair := setupAgent(t)
+		pair.state = CandidatePairStateSucceeded
+
+		ls, ok := agent.getSelector().(*liteSelector)
+		require.True(t, ok)
+
+		assert.Nil(t, agent.getSelectedPair(), "no pair selected yet")
+
+		msg, err := stun.Build(stun.BindingRequest,
+			stun.TransactionID,
+			stun.NewUsername(agent.localUfrag+":"+agent.remoteUfrag),
+			UseCandidate(),
+			stun.NewShortTermIntegrity(agent.localPwd),
+			stun.Fingerprint,
+		)
+		require.NoError(t, err)
+
+		ls.HandleBindingRequest(msg, local, remote)
+
+		assert.Equal(t, pair, agent.getSelectedPair(),
+			"lite controlled agent must accept nomination and set selected pair")
+		// Still no triggered check emitted
+		assert.Equal(t, uint64(0), pair.RequestsSent())
+	})
+}
+
+// TestLiteMode_FullToLite_Integration is an end-to-end test for the most common
+// lite mode deployment: a full ICE agent (controlling) connects to a lite agent
+// (controlled). The full agent performs connectivity checks and nominates; the
+// lite agent responds to STUN but never generates checks of its own.
+func TestLiteMode_FullToLite_Integration(t *testing.T) {
+	defer test.CheckRoutines(t)()
+	defer test.TimeOut(time.Second * 30).Stop()
+
+	oneHour := time.Hour
+	keepaliveInterval := time.Millisecond * 20
+
+	// Full agent — will become the controlling agent (Dial).
+	fullNotifier, fullConnected := onConnected()
+	fullAgent, err := NewAgent(&AgentConfig{
+		NetworkTypes:      []NetworkType{NetworkTypeUDP4},
+		MulticastDNSMode:  MulticastDNSModeDisabled,
+		KeepaliveInterval: &keepaliveInterval,
+		CheckInterval:     &oneHour,
+	})
+	require.NoError(t, err)
+	require.NoError(t, fullAgent.OnConnectionStateChange(fullNotifier))
+	t.Cleanup(func() { require.NoError(t, fullAgent.Close()) })
+
+	// Lite agent — will become the controlled agent (Accept).
+	liteNotifier, liteConnected := onConnected()
+	liteAgent, err := NewAgent(&AgentConfig{
+		NetworkTypes:      []NetworkType{NetworkTypeUDP4},
+		MulticastDNSMode:  MulticastDNSModeDisabled,
+		KeepaliveInterval: &keepaliveInterval,
+		CheckInterval:     &oneHour,
+		Lite:              true,
+		CandidateTypes:    []CandidateType{CandidateTypeHost},
+	})
+	require.NoError(t, err)
+	require.NoError(t, liteAgent.OnConnectionStateChange(liteNotifier))
+	t.Cleanup(func() { require.NoError(t, liteAgent.Close()) })
+
+	// fullAgent.Accept / liteAgent.Dial => fullAgent=controlled, liteAgent=controlling.
+	// We want fullAgent=controlling, so we use connect() which calls
+	// aAgent.Accept (=fullAgent controlled) and bAgent.Dial (=liteAgent controlling).
+	// Swap: pass liteAgent as aAgent (Accept=controlled) and fullAgent as bAgent (Dial=controlling).
+	liteConn, fullConn := connect(t, liteAgent, fullAgent)
+
+	<-fullConnected
+	<-liteConnected
+
+	// Verify the lite agent never sent its own connectivity checks.
+	err = liteAgent.loop.Run(liteAgent.loop, func(_ context.Context) {
+		for _, pair := range liteAgent.checklist {
+			assert.Equal(t, uint64(0), pair.RequestsSent(),
+				"lite agent must not send any connectivity checks")
+		}
+	})
+	require.NoError(t, err)
+
+	// Both agents should be able to exchange data.
+	require.True(t, sendUntilDone(t, fullConn, liteConn, 100))
+	require.True(t, sendUntilDone(t, liteConn, fullConn, 100))
+
+	closePipe(t, liteConn, fullConn)
+}