feat: select random host port for containers (#865)

Co-authored-by: taskbot <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

pkg/container/docker/client.go

@@ -362,6 +362,40 @@ func (c *Client) createIngressContainer(ctx context.Context, containerName strin
 
 }
 
+func extractFirstPort(options *runtime.DeployWorkloadOptions) (int, error) {
+	var firstPort string
+	if len(options.ExposedPorts) == 0 {
+		return 0, fmt.Errorf("no exposed ports specified in options.ExposedPorts")
+	}
+	for port := range options.ExposedPorts {
+		firstPort = port
+
+		// need to strip the protocol
+		firstPort = strings.Split(firstPort, "/")[0]
+		break // take only the first one
+	}
+	firstPortInt, err := strconv.Atoi(firstPort)
+	if err != nil {
+		return 0, fmt.Errorf("failed to convert port %s to int: %v", firstPort, err)
+	}
+	return firstPortInt, nil
+}
+
+func extractFirstPortBinding(portBindings map[string][]runtime.PortBinding) (int, error) {
+	var firstHostPort string
+	for _, bindings := range portBindings {
+		if len(bindings) > 0 {
+			firstHostPort = bindings[0].HostPort
+			break // we only want the first item in the map
+		}
+	}
+	hostPortInt, err := strconv.Atoi(firstHostPort)
+	if err != nil {
+		return 0, fmt.Errorf("failed to convert host port %s to int: %v", firstHostPort, err)
+	}
+	return hostPortInt, nil
+}
+
 // DeployWorkload creates and starts a workload.
 // It configures the workload based on the provided permission profile and transport type.
 // If options is nil, default options will be used.
@@ -465,38 +499,24 @@ func (c *Client) DeployWorkload(
 		return containerId, 0, nil
 	}
 
-	firstPortInt, err := extractFirstPort(options)
+	// extract the first port binding
+	firstHostPort, err := extractFirstPortBinding(options.PortBindings)
 	if err != nil {
-		return "", 0, err // extractFirstPort already wraps the error with context.
+		return "", 0, err
 	}
-
 	if isolateNetwork {
-		firstPortInt, err = c.createIngressContainer(ctx, name, firstPortInt, attachStdio, externalEndpointsConfig)
+		// just extract the first exposed port
+		firstPortInt, err := extractFirstPort(options)
+		if err != nil {
+			return "", 0, err // extractFirstPort already wraps the error with context.
+		}
+		firstHostPort, err = c.createIngressContainer(ctx, name, firstPortInt, attachStdio, externalEndpointsConfig)
 		if err != nil {
 			return "", 0, fmt.Errorf("failed to create ingress container: %v", err)
 		}
 	}
 
-	return containerId, firstPortInt, nil
-}
-
-func extractFirstPort(options *runtime.DeployWorkloadOptions) (int, error) {
-	var firstPort string
-	if len(options.ExposedPorts) == 0 {
-		return 0, fmt.Errorf("no exposed ports specified in options.ExposedPorts")
-	}
-	for port := range options.ExposedPorts {
-		firstPort = port
-
-		// need to strip the protocol
-		firstPort = strings.Split(firstPort, "/")[0]
-		break // take only the first one
-	}
-	firstPortInt, err := strconv.Atoi(firstPort)
-	if err != nil {
-		return 0, fmt.Errorf("failed to convert port %s to int: %v", firstPort, err)
-	}
-	return firstPortInt, nil
+	return containerId, firstHostPort, nil
 }
 
 // ListWorkloads lists workloads

pkg/networking/port.go

@@ -23,7 +23,7 @@ const (
 // IsAvailable checks if a port is available
 func IsAvailable(port int) bool {
 	// Check TCP
-	tcpAddr, err := net.ResolveTCPAddr("tcp", fmt.Sprintf(":%d", port))
+	tcpAddr, err := net.ResolveTCPAddr("tcp", fmt.Sprintf("127.0.0.1:%d", port))
 	if err != nil {
 		return false
 	}
@@ -38,7 +38,7 @@ func IsAvailable(port int) bool {
 	}
 
 	// Check UDP
-	udpAddr, err := net.ResolveUDPAddr("udp", fmt.Sprintf(":%d", port))
+	udpAddr, err := net.ResolveUDPAddr("udp", fmt.Sprintf("127.0.0.1:%d", port))
 	if err != nil {
 		return false
 	}
@@ -128,11 +128,16 @@ func FindOrUsePort(port int) (int, error) {
 			return 0, fmt.Errorf("could not find an available port")
 		}
 		return port, nil
-	} else if port > 0 && !IsAvailable(port) {
-		// Check if the provided port is available
-		return 0, fmt.Errorf("port %d is already in use", port)
 	}
 
-	// Port is available
-	return port, nil
+	if IsAvailable(port) {
+		return port, nil
+	}
+
+	// Requested port is busy — find an alternative
+	alt := FindAvailable()
+	if alt == 0 {
+		return 0, fmt.Errorf("failed to find an alternative port after requested port %d was unavailable", port)
+	}
+	return alt, nil
 }

pkg/runner/config.go

@@ -321,7 +321,6 @@ func (c *RunConfig) WithPorts(port, targetPort int) (*RunConfig, error) {
 	if err != nil {
 		return c, err
 	}
-	logger.Infof("Using host port: %d", selectedPort)
 	c.Port = selectedPort
 
 	// Select a target port for the container if using SSE or Streamable HTTP transport

pkg/transport/http.go

@@ -9,6 +9,7 @@ import (
 	"github.com/stacklok/toolhive/pkg/container"
 	rt "github.com/stacklok/toolhive/pkg/container/runtime"
 	"github.com/stacklok/toolhive/pkg/logger"
+	"github.com/stacklok/toolhive/pkg/networking"
 	"github.com/stacklok/toolhive/pkg/permissions"
 	"github.com/stacklok/toolhive/pkg/transport/errors"
 	"github.com/stacklok/toolhive/pkg/transport/proxy/transparent"
@@ -129,11 +130,17 @@ func (t *HTTPTransport) Setup(ctx context.Context, runtime rt.Runtime, container
 	containerPortStr := fmt.Sprintf("%d/tcp", t.targetPort)
 	containerOptions.ExposedPorts[containerPortStr] = struct{}{}
 
+	// bind to a random host port
 	// Create host port bindings (configurable through the --host flag)
+	hostPort := networking.FindAvailable()
+	if hostPort == 0 {
+		return fmt.Errorf("could not find an available port")
+	}
+
 	portBindings := []rt.PortBinding{
 		{
 			HostIP:   t.host,
-			HostPort: fmt.Sprintf("%d", t.targetPort),
+			HostPort: fmt.Sprintf("%d", hostPort),
 		},
 	}
 
@@ -148,8 +155,6 @@ func (t *HTTPTransport) Setup(ctx context.Context, runtime rt.Runtime, container
 	// Set the port bindings
 	containerOptions.PortBindings[containerPortStr] = portBindings
 
-	logger.Infof("Exposing container port %d", t.targetPort)
-
 	// For SSE transport, we don't need to attach stdio
 	containerOptions.AttachStdio = false