net/http: fix and normalize the [Server.][ListenAnd]Serve[TLS] docs

The only inaccurate part was the HTTP/2 caveat in Server.ServeTLS, which
only applies to the plain Serve variant.

The restriction implemented in shouldConfigureHTTP2ForServe is not on
the setupHTTP2_ServeTLS codepath because ServeTLS owns the tls.Listener,
so we fix it for the user instead of disabling HTTP/2.

Fixes #24607

Change-Id: Ie5f207d0201f09db27bf81b75535e5f6fdaf91e2
Reviewed-on: https://go-review.googlesource.com/103815
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/net/http/example_test.go b/src/net/http/example_test.go
index 9de0893e8739b7d5c942fb983fdc8af41f81e454..53fb0bbb4e104d920dad06d55b1e4c0ea72cd42f 100644 (file)
--- a/src/net/http/example_test.go
+++ b/src/net/http/example_test.go
@@ -137,3 +137,25 @@ func ExampleServer_Shutdown() {
 
        <-idleConnsClosed
 }
+
+func ExampleListenAndServeTLS() {
+       http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
+               io.WriteString(w, "Hello, TLS!\n")
+       })
+
+       // One can use generate_cert.go in crypto/tls to generate cert.pem and key.pem.
+       log.Printf("About to listen on 8443. Go to https://127.0.0.1:8443/")
+       err := http.ListenAndServeTLS(":8443", "cert.pem", "key.pem", nil)
+       log.Fatal(err)
+}
+
+func ExampleListenAndServe() {
+       // Hello world, the web server
+
+       helloHandler := func(w http.ResponseWriter, req *http.Request) {
+               io.WriteString(w, "Hello, world!\n")
+       }
+
+       http.HandleFunc("/hello", helloHandler)
+       log.Fatal(http.ListenAndServe(":8080", nil))
+}

diff --git a/src/net/http/server.go b/src/net/http/server.go
index 0e34b72320f515d1ebddefad7989eaa18bd4a794..f501a65d0abd6641f04f9b81e232fa885606991c 100644 (file)
--- a/src/net/http/server.go
+++ b/src/net/http/server.go
@@ -2419,8 +2419,7 @@ func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
 // creating a new service goroutine for each. The service goroutines
 // read requests and then call handler to reply to them.
 //
-// The handler is typically nil, in which case the DefaultServeMux is
-// used.
+// The handler is typically nil, in which case the DefaultServeMux is used.
 //
 // HTTP/2 support is only enabled if the Listener returns *tls.Conn
 // connections and they were configured with "h2" in the TLS
@@ -2436,12 +2435,14 @@ func Serve(l net.Listener, handler Handler) error {
 // creating a new service goroutine for each. The service goroutines
 // read requests and then call handler to reply to them.
 //
-// Handler is typically nil, in which case the DefaultServeMux is used.
+// The handler is typically nil, in which case the DefaultServeMux is used.
 //
 // Additionally, files containing a certificate and matching private key
 // for the server must be provided. If the certificate is signed by a
 // certificate authority, the certFile should be the concatenation
 // of the server's certificate, any intermediates, and the CA's certificate.
+//
+// ServeTLS always returns a non-nil error.
 func ServeTLS(l net.Listener, handler Handler, certFile, keyFile string) error {
        srv := &Server{Handler: handler}
        return srv.ServeTLS(l, certFile, keyFile)
@@ -2751,8 +2752,11 @@ func (sh serverHandler) ServeHTTP(rw ResponseWriter, req *Request) {
 // ListenAndServe listens on the TCP network address srv.Addr and then
 // calls Serve to handle requests on incoming connections.
 // Accepted connections are configured to enable TCP keep-alives.
+//
 // If srv.Addr is blank, ":http" is used.
-// ListenAndServe always returns a non-nil error.
+//
+// ListenAndServe always returns a non-nil error. After Shutdown or Close,
+// the returned error is ErrServerClosed.
 func (srv *Server) ListenAndServe() error {
        if srv.shuttingDown() {
                return ErrServerClosed
@@ -2867,10 +2871,6 @@ func (srv *Server) Serve(l net.Listener) error {
 // certFile should be the concatenation of the server's certificate,
 // any intermediates, and the CA's certificate.
 //
-// For HTTP/2 support, srv.TLSConfig should be initialized before
-// calling ServeTLS and must contain the string "h2" in its NextProtos
-// field.
-//
 // ServeTLS always returns a non-nil error. After Shutdown or Close, the
 // returned error is ErrServerClosed.
 func (srv *Server) ServeTLS(l net.Listener, certFile, keyFile string) error {
@@ -3000,32 +3000,11 @@ func logf(r *Request, format string, args ...interface{}) {
        }
 }
 
-// ListenAndServe listens on the TCP network address addr
-// and then calls Serve with handler to handle requests
-// on incoming connections.
+// ListenAndServe listens on the TCP network address addr and then calls
+// Serve with handler to handle requests on incoming connections.
 // Accepted connections are configured to enable TCP keep-alives.
-// Handler is typically nil, in which case the DefaultServeMux is
-// used.
-//
-// A trivial example server is:
-//
-//     package main
-//
-//     import (
-//             "io"
-//             "net/http"
-//             "log"
-//     )
 //
-//     // hello world, the web server
-//     func HelloServer(w http.ResponseWriter, req *http.Request) {
-//             io.WriteString(w, "hello, world!\n")
-//     }
-//
-//     func main() {
-//             http.HandleFunc("/hello", HelloServer)
-//             log.Fatal(http.ListenAndServe(":12345", nil))
-//     }
+// The handler is typically nil, in which case the DefaultServeMux is used.
 //
 // ListenAndServe always returns a non-nil error.
 func ListenAndServe(addr string, handler Handler) error {
@@ -3038,36 +3017,13 @@ func ListenAndServe(addr string, handler Handler) error {
 // matching private key for the server must be provided. If the certificate
 // is signed by a certificate authority, the certFile should be the concatenation
 // of the server's certificate, any intermediates, and the CA's certificate.
-//
-// A trivial example server is:
-//
-//     import (
-//             "log"
-//             "net/http"
-//     )
-//
-//     func handler(w http.ResponseWriter, req *http.Request) {
-//             w.Header().Set("Content-Type", "text/plain")
-//             w.Write([]byte("This is an example server.\n"))
-//     }
-//
-//     func main() {
-//             http.HandleFunc("/", handler)
-//             log.Printf("About to listen on 10443. Go to https://127.0.0.1:10443/")
-//             err := http.ListenAndServeTLS(":10443", "cert.pem", "key.pem", nil)
-//             log.Fatal(err)
-//     }
-//
-// One can use generate_cert.go in crypto/tls to generate cert.pem and key.pem.
-//
-// ListenAndServeTLS always returns a non-nil error.
 func ListenAndServeTLS(addr, certFile, keyFile string, handler Handler) error {
        server := &Server{Addr: addr, Handler: handler}
        return server.ListenAndServeTLS(certFile, keyFile)
 }
 
 // ListenAndServeTLS listens on the TCP network address srv.Addr and
-// then calls Serve to handle requests on incoming TLS connections.
+// then calls ServeTLS to handle requests on incoming TLS connections.
 // Accepted connections are configured to enable TCP keep-alives.
 //
 // Filenames containing a certificate and matching private key for the
@@ -3110,8 +3066,8 @@ func (srv *Server) setupHTTP2_ServeTLS() error {
 
 // setupHTTP2_Serve is called from (*Server).Serve and conditionally
 // configures HTTP/2 on srv using a more conservative policy than
-// setupHTTP2_ServeTLS because Serve may be called
-// concurrently.
+// setupHTTP2_ServeTLS because Serve is called after tls.Listen,
+// and may be called concurrently. See shouldConfigureHTTP2ForServe.
 //
 // The tests named TestTransportAutomaticHTTP2* and
 // TestConcurrentServerServe in server_test.go demonstrate some