net/url: mention net.JoinHostPort for constructing url.URL.Host

[dsnet]

In #16142, we add read support for extracting out the hostname and port.

However, that API is lacking the ability to write a host:port pair. Unfortunately, this is not as trivial as concatenating the host and port with a ":" in-between in the case of IPv6, which requires wrapping the entire host with "[" and "]" characters.

I propose the addition of:

// JoinHostnamePort joins a hostname and a port, separating them with a colon.
// If the hostname is an IPv6 address, then it is wrapped with brackets.
// If the port is empty, then the hostname alone is returned.
func JoinHostnamePort(hostname, port string) string

Example outputs:

JoinHostnamePort("carbonite.digitalstatic.ts.net", "")              // carbonite.digitalstatic.ts.net
JoinHostnamePort("carbonite.digitalstatic.ts.net", "9200")          // carbonite.digitalstatic.ts.net:9200
JoinHostnamePort("100.109.51.95", "")                               // 100.109.51.95
JoinHostnamePort("100.109.51.95", "9200")                           // 100.109.51.95:9200
JoinHostnamePort("fd7a:115c:a1e0:ab12:4843:cd96:626d:335f", "")     // fd7a:115c:a1e0:ab12:4843:cd96:626d:335f
JoinHostnamePort("fd7a:115c:a1e0:ab12:4843:cd96:626d:335f", "9200") // [fd7a:115c:a1e0:ab12:4843:cd96:626d:335f]:9200

Considerations:

• It's called JoinHostnamePort instead of JoinHostPort to be consistent with the url.URL.Hostname method.
• The port is a string to be consistent with url.URL.Port
• A standalone function that returns a string is consistent with top-level string-only transformers like JoinPath, PathEscape, PathUnescape, QueryEscape, QueryUnescape.
• What happens if the hostname contains colons but is not an IPv6 or the port is not a valid integer? We'll just concatenate the host and port with a colon in-between even if the result is ambiguous to parse. Alternatively, we could modify the API of JoinHostnamePort to return an error, but I personally like the simplicity of an error-less result.

\cc @bradfitz

[seankhliao]

is the only difference with net.JoinHostPort the handling of an empty port string?

[dsnet]

is the only difference with net.JoinHostPort the handling of an empty port string?

No, it has proper handling for IPv6 addresses by wrapping them in a pair of "[" and "]".

See RFC 2732, section 3:

It defines a syntax for IPv6 addresses and allows the use of "[" and "]" within a URI explicitly for this reserved purpose.

[seankhliao]

The net version also does it: https://go.dev/play/p/l0Wu3N4SJWS
outputs from your example

carbonite.digitalstatic.ts.net:
carbonite.digitalstatic.ts.net:9200
100.109.51.95:
100.109.51.95:9200
[fd7a:115c:a1e0:ab12:4843:cd96:626d:335f]:
[fd7a:115c:a1e0:ab12:4843:cd96:626d:335f]:9200

[dsnet]

I had no idea the "net" package has this. I'd be okay downgrading this issue to just documentation in the "url" package to point towards net.JoinHostPort.

I personally, find it odd that JoinHostPort is in "net", rather than "url", since the whole handling of brackets for IPv6 seems to only exist for URLs.

Edit: I guess, it makes sense to be in "net" since Dial relies on host:port pairs.

[mateenbagheri]

Hello. I came across this documentation issue and I would like to contribute by addressing it. I would be happy to work on this issue and provide a PR. Could you please assign it to me?
Thank you

[mateenbagheri]

Hi @dsnet! I was looking into issue #61093 regarding the addition detail regarding how JoinHostPort needs doc change for net package. While reading through the discussion, I noticed your comment mentioning that something in the net package needs to be changed and there is no need to mention this in url package when you said:

"I guess, it makes sense to be in "net" since Dial relies on host:port pairs."

I would like to understand better what specific changes you think are necessary in the net package. Could you please provide more details or point me to the relevant code/documentation that needs attention?
Thank you in advance for your help!

[jjlin]

The net version also does it: https://go.dev/play/p/l0Wu3N4SJWS outputs from your example

carbonite.digitalstatic.ts.net:
carbonite.digitalstatic.ts.net:9200
100.109.51.95:
100.109.51.95:9200
[fd7a:115c:a1e0:ab12:4843:cd96:626d:335f]:
[fd7a:115c:a1e0:ab12:4843:cd96:626d:335f]:9200

net.JoinHostPort leaves a trailing colon when the port is empty, though. Is that technically allowed? Even if it is, I expect it would break some code out there that doesn't know how to handle that.