net/http: document when a Transport will not automatically upgrade to a HTTP/2 Transport

[noblehng]

Please answer these questions before submitting your issue. Thanks!

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

go version go1.7.1 linux/amd64

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

amd64

What did you do?

I'm trying to pinning a TLS cert for a HTTP/2 server, so I have a custom http.Transport with its TLSClientConfig set like:

 TLSClientConfig: &tls.Config{
     RootCAs:    pool,
     NextProtos: []string{"h2", "http/1.1"},
},

What did you expect to see?

From current documentation, TLSNextProto is nil, so the transport should be upgraded to HTTP/2 automatically and the request to the server should success.

What did you see instead?

The request failed with:

http2: server: error reading preface from client 127.0.0.1:36682: bogus greeting "GET / HTTP/1.1\r\nHost: 12"

It still use a http/1.1 transport after negotiated for h2.

It turns out that after the change with #14275, if either TLSClientConfig or Dial or DialTLS is set for a http.Transport, the automatically upgrade will not happen. But the current documentation of http.Transport doesn't mention this.

[gopherbot]

CL https://golang.org/cl/33094 mentions this issue.