Response header hooks

[apparentlymart]

The API for this client library is focused on returning the primary data associated with each API response, which typically means just the body of the response.

Sometimes clients will also need to react to cross-cutting metadata such as expiration times, cache control guidance, and rate limiting information, which isn't a direct part of the data being requested but can nonetheless affect the behavior of the client. This information is typically returned in HTTP response header fields.

To give access to this information without a breaking change to the API, this uses the context.Context API to allow the rare caller that needs it to register a hook through which it will be notified about the response header in any case where the request succeeded enough for there to be one.

Most clients will not need this facility, which justifies the light abuse of the context.Context API for passing in this optional hook, even though this isn't the sort of cross-cutting concern context.Context should typically be used for.

---

The goal of introducing this now is to improve hashicorp/terraform#32983 so that the Terraform Cloud / Enterprise API can return a new response header signaling its preferred state snapshot interval, thereby creating a compromise between creating no intermediate snapshots at all vs. creating so many intermediate snapshots as to overwhelm the storage of Terraform Enterprise customers and run across potential race conditions in Terraform Cloud.

This is a compromise to have a sort of relief valve in case of problems. This does not necessarily replace other efforts to store and present intermediate snapshots in a better way in Terraform Cloud, although it could potentially allow working on those with less urgency.

[apparentlymart]

I can see that the "errcheck" lint has failed, but the failure doesn't seem to have generated any information about the source location of the problem. 🤔

It looks like the job is intended to generate annotations for the source code to mark where the problems are -- I see it asking the tool to generate its results in a GitHub Actions-specific format -- but no annotations have appeared. I'm not sure what exactly that lint failure is referring to.

[brandonc]

This is a nice solution! A test infrastructure dependency (run tasks mock) is down right now so I will merge this manually once the linter passes

[github-actions]

Reminder to the contributor that merged this PR: if your changes have added important functionality or fixed a relevant bug, open a follow-up PR to update CHANGELOG.md with a note on your changes.