procnet: align /proc/net docs and tighten startup validation

The package, type, and scanListeners doc comments said the scanner
reads /proc/net/{tcp,udp} only. In fact procnettcp.ParseFiles reads
all four files; the IPv6 entries are dropped one layer deeper, in
addValidProtoEntryToPortMap's Kind switch. Update the three
comments to match the code path and name the actual filter site.

Move the tap-interface IP validation from inside the procnet
goroutine to the top of runAgent. The same flag drives both
NewAPITracker and NewProcNetScanner; failing fast lets both
consumers surface the malformed value at the same point instead
of running through tracker setup before the lazy procnet check
fires.

Document the rollback invariant at the publish loop: every binding
under a nat.Port carries the same HostPort (addEntryToPortMap
derives both from entry.Port), so forwarder.Add sees one key and
the rollback unwinds at most one listener.

Add EADDRINUSE coverage to the loopback forwarder by binding
bindIP:port from outside before calling forwarder.Add, for both
TCP and UDP.

Signed-off-by: Jan Dubois <jan.dubois@suse.com>

Author: jandubois

src/go/guestagent/main.go

@@ -115,6 +115,11 @@ func runAgent(
 	adminInstall bool,
 	k8sAPIPort, tapIfaceIP string,
 ) error {
+	bindIP := net.ParseIP(tapIfaceIP)
+	if bindIP == nil {
+		return fmt.Errorf("invalid tap interface IP %q", tapIfaceIP)
+	}
+
 	groupCtx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 	group, ctx := errgroup.WithContext(groupCtx)
@@ -238,10 +243,6 @@ func runAgent(
 	}
 
 	group.Go(func() error {
-		bindIP := net.ParseIP(tapIfaceIP)
-		if bindIP == nil {
-			return fmt.Errorf("invalid tap interface IP %q", tapIfaceIP)
-		}
 		procScanner, err := procnet.NewProcNetScanner(ctx, portTracker, bindIP, procNetScanInterval)
 		if err != nil {
 			return fmt.Errorf("scanning /proc/net/{tcp, udp} failed: %w", err)

src/go/guestagent/pkg/procnet/loopback_forwarder_linux.go

@@ -40,6 +40,11 @@ import (
 	"github.com/containers/gvisor-tap-vsock/pkg/services/forwarder"
 )
 
+const (
+	protoTCP = "tcp"
+	protoUDP = "udp"
+)
+
 type loopbackForwarder struct {
 	bindIP net.IP
 	dialer net.Dialer
@@ -80,21 +85,21 @@ func (f *loopbackForwarder) Add(ctx context.Context, proto string, port uint16)
 	defer f.mu.Unlock()
 
 	switch proto {
-	case "tcp":
+	case protoTCP:
 		if _, ok := f.tcp[k]; ok {
 			return nil
 		}
-		lis, err := net.ListenTCP("tcp", &net.TCPAddr{IP: f.bindIP, Port: int(port)})
+		lis, err := net.ListenTCP(protoTCP, &net.TCPAddr{IP: f.bindIP, Port: int(port)})
 		if err != nil {
 			return fmt.Errorf("listen %s: %w", k, err)
 		}
 		f.tcp[k] = lis
 		go f.acceptTCP(ctx, lis, port)
-	case "udp":
+	case protoUDP:
 		if _, ok := f.udp[k]; ok {
 			return nil
 		}
-		pc, err := net.ListenUDP("udp", &net.UDPAddr{IP: f.bindIP, Port: int(port)})
+		pc, err := net.ListenUDP(protoUDP, &net.UDPAddr{IP: f.bindIP, Port: int(port)})
 		if err != nil {
 			return fmt.Errorf("listen %s: %w", k, err)
 		}
@@ -106,7 +111,7 @@ func (f *loopbackForwarder) Add(ctx context.Context, proto string, port uint16)
 		// scanner's lifetime context); a request-scoped or per-tick
 		// ctx would silently break new-flow dialing once cancelled.
 		proxy, err := forwarder.NewUDPProxy(pc, func() (net.Conn, error) {
-			return f.dialer.DialContext(ctx, "udp", target)
+			return f.dialer.DialContext(ctx, protoUDP, target)
 		})
 		if err != nil {
 			_ = pc.Close()
@@ -125,12 +130,12 @@ func (f *loopbackForwarder) Remove(proto string, port uint16) error {
 	f.mu.Lock()
 	defer f.mu.Unlock()
 	switch proto {
-	case "tcp":
+	case protoTCP:
 		if lis, ok := f.tcp[k]; ok {
 			delete(f.tcp, k)
 			return lis.Close()
 		}
-	case "udp":
+	case protoUDP:
 		if proxy, ok := f.udp[k]; ok {
 			delete(f.udp, k)
 			return proxy.Close()
@@ -212,7 +217,7 @@ func (f *loopbackForwarder) acceptTCP(ctx context.Context, lis net.Listener, por
 func (f *loopbackForwarder) pipeTCP(ctx context.Context, in net.Conn, port uint16) {
 	defer in.Close()
 	addr := net.JoinHostPort("127.0.0.1", strconv.Itoa(int(port)))
-	out, err := f.dialer.DialContext(ctx, "tcp", addr)
+	out, err := f.dialer.DialContext(ctx, protoTCP, addr)
 	if err != nil {
 		log.Debugf("loopback forwarder dial tcp/%d: %s", port, err)
 		return

src/go/guestagent/pkg/procnet/loopback_forwarder_linux_test.go

@@ -128,6 +128,48 @@ func TestForwarderAddIsIdempotent(t *testing.T) {
 	}
 }
 
+// Hold bindIP:port from outside the forwarder so the forwarder's
+// own Listen returns EADDRINUSE on Add.
+func TestForwarderAddFailsWhenPortInUse(t *testing.T) {
+	bindIP := net.ParseIP("127.0.0.99")
+	cases := []struct {
+		proto string
+		grab  func(*testing.T) (uint16, func())
+	}{
+		{"tcp", func(t *testing.T) (uint16, func()) {
+			t.Helper()
+			var lc net.ListenConfig
+			ln, err := lc.Listen(context.Background(), "tcp", "127.0.0.99:0")
+			if err != nil {
+				t.Skipf("listen via 127.0.0.99 failed (loopback aliases unavailable): %v", err)
+			}
+			return uint16(ln.Addr().(*net.TCPAddr).Port), func() { _ = ln.Close() }
+		}},
+		{"udp", func(t *testing.T) (uint16, func()) {
+			t.Helper()
+			var lc net.ListenConfig
+			pc, err := lc.ListenPacket(context.Background(), "udp", "127.0.0.99:0")
+			if err != nil {
+				t.Skipf("listen via 127.0.0.99 failed: %v", err)
+			}
+			return uint16(pc.LocalAddr().(*net.UDPAddr).Port), func() { _ = pc.Close() }
+		}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.proto, func(t *testing.T) {
+			port, stop := tc.grab(t)
+			defer stop()
+
+			fwd := newLoopbackForwarder(bindIP)
+			defer fwd.Close()
+
+			if err := fwd.Add(context.Background(), tc.proto, port); err == nil {
+				t.Fatalf("forwarder.Add succeeded on busy port; expected EADDRINUSE")
+			}
+		})
+	}
+}
+
 // startUDPEcho binds a UDP listener on 127.0.0.1:0 that echoes every
 // received datagram back to the sender. Returns the chosen port and a
 // stop function.

src/go/guestagent/pkg/procnet/scanner_linux.go

@@ -12,7 +12,7 @@ limitations under the License.
 */
 
 /*
-Package procnet scans /proc/net/{tcp,udp} for listeners the
+Package procnet scans /proc/net for IPv4 TCP and UDP listeners the
 container-engine events handler does not publish -- mainly
 --network=host containers binding 127.0.0.1 -- and exposes them to
 host-switch via the API tracker. For loopback listeners it also opens
@@ -22,8 +22,10 @@ two-scan stability gate filters out the transient reservation socket
 nerdctl's OCI createRuntime hook opens before CNI installs its
 iptables rules.
 
-IPv6 limitation: the scanner reads /proc/net/{tcp,udp} only, not the
-tcp6/udp6 variants. A --network=host container that listens
+IPv6 limitation: procnettcp.ParseFiles returns entries from
+/proc/net/{tcp,tcp6,udp,udp6}, but addValidProtoEntryToPortMap
+dispatches only on the TCP and UDP Kinds and silently drops the
+TCP6 and UDP6 entries. A --network=host container that listens
 exclusively on [::1]:port is invisible to the scanner and is not
 reachable from Windows. Containers that bind dual-stack
 (e.g. [::]:port with IPV6_V6ONLY=0, the Go and Python default) are
@@ -63,9 +65,10 @@ type loopbackController interface {
 	Close() error
 }
 
-// ProcNetScanner polls /proc/net/{tcp,udp} and reconciles the
-// observed listener set against the API tracker and a userspace
-// loopback forwarder. See the package comment for the design.
+// ProcNetScanner polls /proc/net for IPv4 TCP and UDP listeners
+// and reconciles the observed set against the API tracker and a
+// userspace loopback forwarder. See the package comment for the
+// design, including the IPv6 limitation.
 type ProcNetScanner struct {
 	ctx          context.Context
 	tracker      tracker.Tracker
@@ -206,6 +209,9 @@ func (p *ProcNetScanner) publish(port nat.Port, bindings []nat.PortBinding) erro
 	// forwarder; the tracker entry alone keeps the port reachable from
 	// Windows.
 	if !hasWildcardBinding(bindings) {
+		// Every binding under a given nat.Port carries the same HostPort
+		// (addEntryToPortMap derives both from entry.Port), so forwarder.Add
+		// sees one key and rollback unwinds at most one listener.
 		for _, b := range bindings {
 			if b.HostIP != loopbackIP {
 				continue
@@ -275,8 +281,9 @@ func (p *ProcNetScanner) unpublish(port nat.Port, bindings []nat.PortBinding) {
 	}
 }
 
-// scanListeners parses /proc/net/{tcp,udp} into a snapshot suitable
-// for Tick. See entriesToPortMap for the filter that drops the
+// scanListeners parses /proc/net/{tcp,tcp6,udp,udp6} via
+// procnettcp.ParseFiles. See addValidProtoEntryToPortMap for the
+// IPv6 drop and entriesToPortMap for the filter that drops the
 // forwarder's own sockets.
 func (p *ProcNetScanner) scanListeners() (nat.PortMap, error) {
 	entries, err := procnettcp.ParseFiles()