net/http: docs for Dial and DialContext should indicate concurrency properties

[jsha]

In Go 1.10.1, a user of the net/http package can specify a custom RoundTripper. That RoundTripper can define a custom Dial and/or DialContext. When running Client.Do, the Dial or DialContext function is run on a separate goroutine. If the function has side effects (for instance, recording its results in a shared slice), this can cause race conditions. For a real-world example, see letsencrypt/boulder#3109.

I think the documentation should be updated to mention that Dial and DialContext may be run concurrently with the function calling Client.Do. Here's the current documenation:

https://godoc.org/net/http#Transport

// DialContext specifies the dial function for creating unencrypted TCP connections.
// If DialContext is nil (and the deprecated Dial below is also nil),
// then the transport dials using package net.
DialContext func(ctx context.Context, network, addr string) (net.Conn, error)

// Dial specifies the dial function for creating unencrypted TCP connections.
//
// Deprecated: Use DialContext instead, which allows the transport
// to cancel dials as soon as they are no longer needed.
// If both are set, DialContext takes priority.
Dial func(network, addr string) (net.Conn, error)

Thanks!

[ianlancetaylor]

CC @bradfitz @tombergan

[gopherbot]

Change https://golang.org/cl/116375 mentions this issue: net/http: document Transport.Dial concurrency