feat(go): [DRAFT] Add support for response headers

[amckinney]

Overview

This proposes the design for surfacing HTTP headers from the Go SDK. Similar to the approach used in TypeScript, Python, and Java, this adds a WithRawResponse field on each generated client so that the user can opt-in to receiving more raw HTTP data alongside the decoded response body.

UX

Standard call

movie, err := client.Imdb.CreateMovie(...)
if err != nil {
  return nil, err
}
fmt.Println("Got movie: ", movie)

Call with response headers

response, err := client.Imdb.WithRawResponse.CreateMovie(...)
if err != nil {
  return nil, err
}
var (
  header = response.Header
  movie  = response.Body
)
fmt.Println("Got header: ", header)
fmt.Println("Got movie: ", movie)

Alternatives considered

Instead, we could roll out a new RequestOption that can be used to catch the *http.Response like so:

var httpResponse *http.Response
movie, err := client.Imdb.CreateMovie(
  ...
  option.WithRawResponse(httpResponse),
)
if err != nil {
  return nil, err
}
fmt.Println("Got header: ", httpResponse.Header)

This feels worse for a few reasons:

1. The request option breaks the typical Go pattern where return values tell the complete story.
2. The feature is less discoverable.
3. The full *http.Response type is exposed, including the already-closed response body. This is a footgun.