Add an option to preserve existing Authorization header

[artuross]

This library currently always sets the Authorization header, even if request already has one.

Problem

To illustrate why that is a problem, lets say that I have a Client like this:

type Client struct {
  httpClient *http.Client
}

that, for all but one endpoint, uses oauth2 library for setting Authorization token. If I want to provide my own, custom Authorization header value to that single endpoint, I have two choices:

1. Configure new HTTP client:

   httpClient := &http.Client{Timeout: 2 * time.Second}
   ctx = context.WithValue(ctx, oauth2.HTTPClient, httpClient)

   This approach is impractical, because it may lead to inconsistent behavior. For example, if I had another RoundTripper that would further enhance outgoing requests, it's easy to miss that detail (for example Open Telemetry instrumentation).

2. Pass another HTTP client to Client

   type Client struct {
     httpClient            *http.Client
     httpClientWithoutAuth *http.Client
   }

   then use either like

   res, err := c.httpClientWithoutAuth.Do(req)

   or perhaps even stranger

   ctx = context.WithValue(ctx, oauth2.HTTPClient, c.httpClientWithoutAuth)
   req, err := http.NewRequestWithContext(ctx, ...)
   // ...
   
   res, err := c.httpClient.Do(req)

   Regardless of which would be better, this is just very awkward way of achieving it and I think also leads to potential inconsistencies, as the developer must ensure both clients have equivalent Transports (except for oauth2 obviously).

Proposed solution

In my view, this library should either preserve existing Authorization header out of the box (big, breaking change) or provide a way to instruct the library of the desired behavior, for example with context:

ctx = context.WithValue(ctx, oauth2.PreserveExistingHeader, true)

in which case the library would simply not retrieve token and not set the header if one is already set.