net/url: better handling or documentation of IPv6 addresses in url.URL.Host

[jjlin]

What did you do?

https://go.dev/play/p/Lypv_o9VMRf

host := "fc00::121:0:2:27"
url := url.URL{
	Scheme: "https",
	Host:   host,
	Path:   "/some/path",
}
fmt.Println(url.String())

What did you expect to see?

https://[fc00::121:0:2:27]/some/path

What did you see instead?

https://fc00::121:0:2:27/some/path

This ends up being interpreted as https://[fc00::121:0:2]:27/some/path.

The documentation for url.URL.Host is host or host:port, which leaves it unclear as to how a literal IPv6 address would be treated.

I think it makes more sense to treat a literal IPv6 address as just that, and require the user to specify [<ipv6-address>]:<port> if that's what they actually wanted, though I appreciate that there would be backward compatibility issues with that.

So at this point, it's probably best to just clarify the docs and add a reference to net.JoinHostPort. This could perhaps be done via #61093.

[cherrymui]

cc @neild @rsc

[neild]

The documentation probably could be better here.

URL.Host is the host or host:port from the authority component of the URL. (https://www.rfc-editor.org/rfc/rfc3986#section-3.2) When the host subcomponent contains square brackets, the square brackets are present in URL.Host.

So, yes, if you want an IPv6 address in a URL, you need to set URL.Host to [<ipv6-address>] or [<ipv6-address>]:<port>.

In retrospect, perhaps URL should have had separate Host and Port fields.

[gopherbot]

Change https://go.dev/cl/508976 mentions this issue: net/url: document requirements for IPv6 addresses in URL.Host