net/http: document when (RoundTripper).RoundTrip may return a nil *Response

[bcmills]

(Factored out from #37598.)

The net/http.RoundTripper interface is currently ambiguous about what happens in case of errors.

Its documentation says:

    // RoundTrip executes a single HTTP transaction, returning
    // a Response for the provided Request.

but:

    // … RoundTrip must return err == nil if it obtained
    // a response, regardless of the response's HTTP status code.
    // A non-nil err should be reserved for failure to obtain a
    // response.

Unfortunately, it does not specify whether “failure to obtain a response” may correspond to a nil *Response, or only one that is only partially populated.

CC @bradfitz @rsc

[bcmills]

The answer appears to be that RoundTrip should return a nil *Response if (and only if) it returns a non-nil error.

go/src/net/http/client.go

Lines 252 to 257 in c436ead

	resp, err = rt.RoundTrip(req)
	if err != nil {
	stopTimer()
	if resp != nil {
	log.Printf("RoundTripper returned a response & error; ignoring response")
	}

[gopherbot]

Change https://golang.org/cl/230740 mentions this issue: net/http: document when (RoundTripper).RoundTrip may return a nil *Response