Go: Split host and port without breaking IPv6 addresses
An IPv6 address contains colons, so splitting an endpoint at every colon loses its structure. net.SplitHostPort understands bracketed IPv6 host syntax. Port validation remains a separate application decision.
Set up
Tested on Linux amd64 with Go 1.26.10. Use Bash with Go on your PATH, a text editor, and the mktemp, rm, and rmdir utilities. The example uses only the standard library. Keep the same terminal through cleanup, and stop if setup fails before saving the source.
start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1Run the example
Save as go-net-splithostport-ipv6-boundary.go:
package main
import (
"fmt"
"net"
"strconv"
)
func endpoint(text string) (string, uint16, error) {
host, portText, err := net.SplitHostPort(text)
if err != nil {
return "", 0, fmt.Errorf("invalid host:port syntax")
}
if host == "" {
return "", 0, fmt.Errorf("host required")
}
port, err := strconv.ParseUint(portText, 10, 16)
if err != nil || port == 0 {
return "", 0, fmt.Errorf("port must be 1..65535")
}
return host, uint16(port), nil
}
func main() {
for _, text := range []string{"example.test:443", "[2001:db8::1]:443", "2001:db8::1:443", ":443", "host:0", "host:65536", "host:https"} {
host, port, err := endpoint(text)
fmt.Printf("%q: host=%q port=%d error=%v\n", text, host, port, err)
}
host, port, err := endpoint("[2001:db8::1]:443")
if host != "2001:db8::1" || port != 443 || err != nil {
panic("IPv6 endpoint")
}
fmt.Println("joined:", net.JoinHostPort(host, strconv.Itoa(int(port))))
}Run:
go run go-net-splithostport-ipv6-boundary.goObserved output:
"example.test:443": host="example.test" port=443 error=<nil>
"[2001:db8::1]:443": host="2001:db8::1" port=443 error=<nil>
"2001:db8::1:443": host="" port=0 error=invalid host:port syntax
":443": host="" port=0 error=host required
"host:0": host="" port=0 error=port must be 1..65535
"host:65536": host="" port=0 error=port must be 1..65535
"host:https": host="" port=0 error=port must be 1..65535
joined: [2001:db8::1]:443Read the result
The bracketed address returns a host without brackets. JoinHostPort adds the appropriate brackets when rebuilding the endpoint. An unbracketed IPv6 literal is rejected by the split operation.
The application also rejects an empty host, port zero, named services and numbers outside the 16-bit range. Those restrictions are additional to splitting: a syntactically separated port string is not necessarily a permitted numeric port.
Apply it carefully
This function does not resolve DNS, validate the hostname or authorize a network destination. It opens no connection. A nonempty host is insufficient for security decisions such as restricting outbound requests; those require a policy covering resolution and the actual connection. The documentation address and test domain are examples only. Other applications may deliberately permit an empty bind host, named services or port zero, so keep those decisions explicit rather than attributing them to the splitter.
See the Go standard-library reference.
Clean up
Remove the saved source and the empty scratch directory. Go manages its build cache separately. If the directory is not empty, inspect its contents before removing anything else.
rm -- go-net-splithostport-ipv6-boundary.go
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dirAcknowledgements
This post was created with assistance from AI.