net/http: doc: Clarify that Server.ServeTLS enables http2, but Server.Serve does not

[tliron]

What version of Go are you using (go version)?

1.16.5

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

amd64 linux

What did you expect to see?

I expected that Server.Serve would support http2 when I provided it with my customer listener. My expectation was based on this statement in the documentation:

Starting with Go 1.6, the http package has transparent support for the HTTP/2 protocol when using HTTPS.

After a full day of trying to debug this issue I found out that only Server.ServeTLS (and the functions that call it) supports http2 because it makes sure to fix the tls.Config by (smartly) adding the default protocols. Server.Serve does not, because of course it does not have access to any tls.Config.

For those interested, here is a one-liner workaround when creating your listener:

tlsConfig.NextProtos = []string{"h2", "http/1.1"}

I'm not sure what the best way to fix the documentation would be! But I think it should state that: Server.Serve does not support http2 by default and even suggest my one-liner above as a workaround.

The above blanket statement about "transparent support" should also be modified with specifics on which codepaths enable http2.

[cherrymui]

cc @neild

[neild]

The documentation for Serve states:

HTTP/2 support is only enabled if the Listener returns *tls.Conn connections and they were configured with "h2" in the TLS Config.NextProtos.

Do you have a suggestion on how that can be made clearer?

[tliron]

My suggestions:

1. Change "Starting with Go 1.6, the http package has transparent support for the HTTP/2 protocol when using HTTPS" to something else.
2. For "Serve" I think adding example code, such as I provided, would help a lot.

[ivanduka]

I wasted a lot of time investigating why my app stubbornly uses http1.1 instead of http2.
Apparently, the reason is because I am using Server.Serve and it does NOT use http2 protocol by default.