fix the silent fallback to random ports issue when invalid,privileged or already in use ports specified (#3176)

Signed-off-by: RayyanSeliya <rayyanseliya786@gmail.com>

Author: RayyanSeliya

cmd/run.go

@@ -252,6 +252,34 @@ Or if you have an existing function:
 	// configured to build/run the language of the function.
 	job, err := client.Run(cmd.Context(), f, fn.RunWithAddress(cfg.Address))
 	if err != nil {
+		// Catch port unavailable errors and provide helpful CLI guidance
+		var portErr *fn.ErrPortUnavailableError
+		if errors.As(err, &portErr) {
+			if portErr.IsPermissionDenied() {
+				return fmt.Errorf(`cannot choose port
+
+Cannot bind to port %s: permission denied.
+
+Port %s is a privileged port and requires administrator/root permissions.
+
+Try this:
+  sudo func run --address %s        Run with elevated permissions
+  func run --address 127.0.0.1:8080          Use non-privileged port
+
+For more options, run 'func run --help'`, portErr.Port, portErr.Port, cfg.Address)
+			}
+			return fmt.Errorf(`cannot choose port
+
+Port %s is not available.
+
+The port may be in use by another process, or you may not have permission to bind to it.
+
+Try this:
+  func run --address 127.0.0.1:8080          Use a different port
+  lsof -i :%s                                Check if port is in use (Linux/Mac)
+
+For more options, run 'func run --help'`, portErr.Port, portErr.Port)
+		}
 		return
 	}
 	defer func() {
@@ -388,6 +416,50 @@ func (c runConfig) Validate(cmd *cobra.Command, f fn.Function) (err error) {
 		}
 	}
 
+	// Validate address port if provided
+	if c.Address != "" {
+		host, port, err := net.SplitHostPort(c.Address)
+		if err != nil {
+			// Invalid address format will be caught by runner
+			return nil // Let runner handle address format errors
+		}
+
+		// Warn about port-only addresses (missing host)
+		if host == "" {
+			return fmt.Errorf(`invalid address format '%s': address must include both host and port
+
+Address format: host:port
+
+Examples:
+  127.0.0.1:8080    Localhost only
+  0.0.0.0:8080      All interfaces (IPv4)
+  [::]:8080         All interfaces (IPv6)
+
+For more options, run 'func run --help'`, c.Address)
+		}
+
+		// Validate port range (1-65535)
+		portNum, err := strconv.Atoi(port)
+		if err != nil {
+			return fmt.Errorf(`invalid port '%s': port must be a number between 1 and 65535
+
+Examples:
+  func run --address 127.0.0.1:8080
+  func run --address 0.0.0.0:9090
+
+For more options, run 'func run --help'`, port)
+		}
+		if portNum < 1 || portNum > 65535 {
+			return fmt.Errorf(`invalid port '%d': port must be between 1 and 65535
+
+Examples:
+  func run --address 127.0.0.1:8080
+  func run --address 0.0.0.0:9090
+
+For more options, run 'func run --help'`, portNum)
+		}
+	}
+
 	if f.Build.Builder == "host" && !oci.IsSupported(f.Runtime) {
 		return fmt.Errorf("the %q runtime currently requires being run in a container", f.Runtime)
 	}

pkg/functions/errors.go

@@ -3,6 +3,7 @@ package functions
 import (
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 )
 
@@ -90,3 +91,31 @@ type ErrEnvNotExist struct {
 func (e ErrEnvNotExist) Error() string {
 	return fmt.Sprintf("environment variable %q does not exist", e.Name)
 }
+
+// ErrPortUnavailableError indicates that a port cannot be bound
+type ErrPortUnavailableError struct {
+	Port string
+	Err  error
+}
+
+func (e *ErrPortUnavailableError) Error() string {
+	if e.Err != nil {
+		return fmt.Sprintf("port %s is not available: %v", e.Port, e.Err)
+	}
+	return fmt.Sprintf("port %s is not available", e.Port)
+}
+
+func (e *ErrPortUnavailableError) Unwrap() error {
+	return e.Err
+}
+
+// IsPermissionDenied checks if the underlying error is a permission error
+func (e *ErrPortUnavailableError) IsPermissionDenied() bool {
+	if e.Err == nil {
+		return false
+	}
+	errStr := strings.ToLower(e.Err.Error())
+	return strings.Contains(errStr, "permission denied") ||
+		strings.Contains(errStr, "access denied") ||
+		strings.Contains(errStr, "operation not permitted")
+}

pkg/functions/runner.go

@@ -45,6 +45,7 @@ func (r *defaultRunner) Run(ctx context.Context, f Function, address string, sta
 	// Parse address if provided, otherwise use defaults
 	host := defaultRunHost
 	port := defaultRunPort
+	explicitPort := address != ""
 
 	if address != "" {
 		var err error
@@ -54,7 +55,7 @@ func (r *defaultRunner) Run(ctx context.Context, f Function, address string, sta
 		}
 	}
 
-	port, err = choosePort(host, port)
+	port, err = choosePort(host, port, explicitPort)
 	if err != nil {
 		return nil, fmt.Errorf("cannot choose port: %w", err)
 	}
@@ -332,25 +333,35 @@ func isReady(ctx context.Context, uri string, timeout time.Duration, verbose boo
 	return true, nil
 }
 
-// choosePort returns an unused port on the given interface (host)
-// Note this is not fool-proof becase of a race with any other processes
+// choosePort returns an unused port on the given interface (host).
+// If explicitPort is true and the preferred port cannot be bound, an error is returned.
+// If explicitPort is false (default port), it falls back to an OS-chosen port if the preferred port is unavailable.
+// Note this is not fool-proof because of a race with any other processes
 // looking for a port at the same time.  If that is important, we can implement
 // a check-lock-check via the filesystem.
 // Also note that TCP is presumed.
-func choosePort(iface, preferredPort string) (string, error) {
+func choosePort(iface, preferredPort string, explicitPort bool) (string, error) {
 	var (
 		port = preferredPort
 		l    net.Listener
 		err  error
 	)
 
-	// Try preferred
+	// Try preferred port
 	if l, err = net.Listen("tcp", net.JoinHostPort(iface, port)); err == nil {
-		l.Close() // note err==nil
+		l.Close()
 		return port, nil
 	}
 
-	// OS-chosen
+	// If user explicitly provided a port and it's unavailable, return typed error
+	if explicitPort {
+		return "", &ErrPortUnavailableError{
+			Port: port,
+			Err:  err,
+		}
+	}
+
+	// For default ports, fall back to OS-chosen port
 	if l, err = net.Listen("tcp", net.JoinHostPort(iface, "")); err != nil {
 		return "", fmt.Errorf("cannot bind tcp: %w", err)
 	}