net/http: update HTTP/2 documentation to reference new config features

Update the package docs to point users at the modern HTTP/2
configuration APIs.

Mention in the TLSNextProto documentation that this field is
superseded by the Protocols field for most user-facing purposes.

Change-Id: I30cd9a85a27e1174338f0d6b887f98c28eac5b5d
Reviewed-on: https://go-review.googlesource.com/c/go/+/709797
Reviewed-by: Nicholas Husin <nsh@golang.org>
Reviewed-by: Nicholas Husin <husin@google.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/net/http/doc.go b/src/net/http/doc.go
index f7ad3ae762fb6c8669ee28c2425a97bdb41eb672..24e07352ca726ddf35d764c18d3e63715b6afc01 100644 (file)
--- a/src/net/http/doc.go
+++ b/src/net/http/doc.go
@@ -84,27 +84,26 @@ custom Server:
 
 # HTTP/2
 
-Starting with Go 1.6, the http package has transparent support for the
-HTTP/2 protocol when using HTTPS. Programs that must disable HTTP/2
-can do so by setting [Transport.TLSNextProto] (for clients) or
-[Server.TLSNextProto] (for servers) to a non-nil, empty
-map. Alternatively, the following GODEBUG settings are
-currently supported:
+The http package has transparent support for the HTTP/2 protocol.
+
+[Server] and [DefaultTransport] automatically enable HTTP/2 support
+when using HTTPS. [Transport] does not enable HTTP/2 by default.
+
+To enable or disable support for HTTP/1, HTTP/2, and/or unencrypted HTTP/2,
+see the [Server.Protocols] and [Transport.Protocols] configuration fields.
+
+To configure advanced HTTP/2 features, see the [Server.HTTP2] and
+[Transport.HTTP2] configuration fields.
+
+Alternatively, the following GODEBUG settings are currently supported:
 
        GODEBUG=http2client=0  # disable HTTP/2 client support
        GODEBUG=http2server=0  # disable HTTP/2 server support
        GODEBUG=http2debug=1   # enable verbose HTTP/2 debug logs
        GODEBUG=http2debug=2   # ... even more verbose, with frame dumps
 
-Please report any issues before disabling HTTP/2 support: https://golang.org/s/http2bug
-
-The http package's [Transport] and [Server] both automatically enable
-HTTP/2 support for simple configurations. To enable HTTP/2 for more
-complex configurations, to use lower-level HTTP/2 features, or to use
-a newer version of Go's http2 package, import "golang.org/x/net/http2"
-directly and use its ConfigureTransport and/or ConfigureServer
-functions. Manually configuring HTTP/2 via the golang.org/x/net/http2
-package takes precedence over the net/http package's built-in HTTP/2
-support.
+The "omithttp2" build tag may be used to disable the HTTP/2 implementation
+contained in the http package.
 */
+
 package http

diff --git a/src/net/http/server.go b/src/net/http/server.go
index 4078c89906140997b7917f3690d5443fbc9ee57a..02554d1a201afd329f1e8ff09323b9e12e6fc10b 100644 (file)
--- a/src/net/http/server.go
+++ b/src/net/http/server.go
@@ -3066,6 +3066,9 @@ type Server struct {
        // automatically closed when the function returns.
        // If TLSNextProto is not nil, HTTP/2 support is not enabled
        // automatically.
+       //
+       // Historically, TLSNextProto was used to disable HTTP/2 support.
+       // The Server.Protocols field now provides a simpler way to do this.
        TLSNextProto map[string]func(*Server, *tls.Conn, Handler)
 
        // ConnState specifies an optional callback function that is
@@ -3094,9 +3097,6 @@ type Server struct {
        ConnContext func(ctx context.Context, c net.Conn) context.Context
 
        // HTTP2 configures HTTP/2 connections.
-       //
-       // This field does not yet have any effect.
-       // See https://go.dev/issue/67813.
        HTTP2 *HTTP2Config
 
        // Protocols is the set of protocols accepted by the server.

diff --git a/src/net/http/transport.go b/src/net/http/transport.go
index 5cef9be487a4e2e697fd97bf07d69c2dc9e9c5d9..a560765d331d6503ad6c78fbccfaf89f69a652bf 100644 (file)
--- a/src/net/http/transport.go
+++ b/src/net/http/transport.go
@@ -249,6 +249,9 @@ type Transport struct {
        // must return a RoundTripper that then handles the request.
        // If TLSNextProto is not nil, HTTP/2 support is not enabled
        // automatically.
+       //
+       // Historically, TLSNextProto was used to disable HTTP/2 support.
+       // The Transport.Protocols field now provides a simpler way to do this.
        TLSNextProto map[string]func(authority string, c *tls.Conn) RoundTripper
 
        // ProxyConnectHeader optionally specifies headers to send to
@@ -296,9 +299,6 @@ type Transport struct {
        ForceAttemptHTTP2 bool
 
        // HTTP2 configures HTTP/2 connections.
-       //
-       // This field does not yet have any effect.
-       // See https://go.dev/issue/67813.
        HTTP2 *HTTP2Config
 
        // Protocols is the set of protocols supported by the transport.