net/http: document internal error errServerClosedIdle more

Updates #19943

Change-Id: Iea249be51a7af3264bee9ee2b28dbd91043275fc
Reviewed-on: https://go-review.googlesource.com/86375
Reviewed-by: Ian Lance Taylor <iant@golang.org>

1 files changed, 6 insertions, 1 deletions

diff --git a/src/net/http/transport.go b/src/net/http/transport.go
index 7c38ac4464..c9758e9b38 100644
--- a/src/net/http/transport.go
+++ b/src/net/http/transport.go
@@ -655,9 +655,14 @@ var (
 	errTooManyIdleHost    = errors.New("http: putIdleConn: too many idle connections for host")
 	errCloseIdleConns     = errors.New("http: CloseIdleConnections called")
 	errReadLoopExiting    = errors.New("http: persistConn.readLoop exiting")
-	errServerClosedIdle   = errors.New("http: server closed idle connection")
 	errIdleConnTimeout    = errors.New("http: idle connection timeout")
 	errNotCachingH2Conn   = errors.New("http: not caching alternate protocol's connections")
+
+	// errServerClosedIdle is not seen by users for idempotent requests, but may be
+	// seen by a user if the server shuts down an idle connection and sends its FIN
+	// in flight with already-written POST body bytes from the client.
+	// See https://github.com/golang/go/issues/19943#issuecomment-355607646
+	errServerClosedIdle = errors.New("http: server closed idle connection")
 )
 
 // transportReadFromServerError is used by Transport.readLoop when the