net/http/httptrace: Provide direction in the documentation for ClientTrace on safety of request mutations

[thesilentg]

The documentation for ClientTrace provides no guidance on if it is safe to modify the request from within any of the trace functions. It mentions that the functions within ClientTrace may be called concurrently, but does not comment on if these functions are permitted to modify the request. In contrast, the documentation for RoundTripper explicitly calls out the expected behavior:

    // RoundTrip should not modify the request, except for
    // consuming and closing the Request's Body. RoundTrip may
    // read fields of the request in a separate goroutine. Callers
    // should not mutate or reuse the request until the Response's
    // Body has been closed.

This concern was originally raised when attempting to use GotConn to modify the request Header to add the amount of time remaining until the request's context deadline, for use in distributed tracing. I would like to be able to modify certain properties in the request (Headers, Body, ...) in response to ClientTrace data, but need to understand if that behavior will continue to be supported.

This issue has two components:

1. Provide guidance on if the functions within ClientTrace are permitted to modify the request
2. If the functions within ClientTrace are permitted to modify the request, promise this expectation will continue in the future by updating the documentation to reflect this

[cagedmantis]

/cc @bradfitz @bcmills

[thesilentg]

@cagedmantis Hi Carlos, just wanted to check in and see if there was anyone else you think would be able to help answer this. It's been about a month at this point, and even just getting general directional guidance with regards to mutability would be helpful. Thanks!

[thesilentg]

@cagedmantis @bcmills Just wanted to check in and see if there was anyone else you think would be able to help answer this. It's been about a year at this point, and even just getting general directional guidance with regards to mutability would be helpful. Thanks!

[thesilentg]

@cagedmantis @bcmills Do you think it will be possible to get an answer on this?

[thesilentg]

@cagedmantis @bcmills Will it be possible to get an answer here?

[bcmills]

(attn @neild)