Documentation
¶
Overview ¶
Package chttp provides the HTTP client every katbyte tool talks to APIs with: trace-level request/response logging through clog, per-attempt timeouts so a stalled server fails fast, and retries for transient failures that are careful never to re-send a mutation whose outcome is unknown.
Index ¶
- Constants
- func Explain(err error) error
- func IsNotFound(err error) bool
- func KeepCredentialsOnHost(headers ...string) func(req *http.Request, via []*http.Request) error
- func MarkRetrySafe(req *http.Request) *http.Request
- func NewBaseTransport() http.RoundTripper
- func NewHTTPClient(name string) *http.Client
- func Preview(body []byte) string
- func RedactError(err error, also ...string) error
- func RedactURL(raw string, also ...string) string
- func StatusCode(err error) int
- type RetryTransport
- type StatusError
- type Transport
Constants ¶
const DefaultMaxRetry = 3
DefaultMaxRetry is how many attempts NewHTTPClient makes before giving up: enough to ride through a blip or a single rate-limit window without turning an outage into a minutes-long hang.
const MaxRetryAfter = 60 * time.Second
MaxRetryAfter caps how long a Retry-After header can make a retry wait. A server asking for more than this is telling an interactive tool to come back later, not to sit there.
const PreviewLen = 300
PreviewLen is how much of a response body a StatusError carries.
Variables ¶
This section is empty.
Functions ¶
func Explain ¶ added in v0.4.0
Explain adds, to the error of a request that never got an answer, what the operating system may be doing about it where that is known: a dial a Mac refused with "no route to host" is usually its Local Network privacy, which no retry and no server fixes, and the bare error sends its reader to the network. The error keeps what it wraps. One there is nothing to say about, and one already explained, comes back as it was.
Transport does this for every request it carries; Explain is for a client built on another transport.
func IsNotFound ¶ added in v0.4.0
IsNotFound reports whether err is a 404 from the server.
func KeepCredentialsOnHost ¶ added in v0.4.0
KeepCredentialsOnHost is a redirect policy, for an http.Client's CheckRedirect: a redirect is followed (up to Go's usual ten), but one that leaves the first request's host, or goes from https down to http, reaches its target without the credentials.
Go itself drops only Authorization on the way to another domain, and keeps it for a subdomain; a token an API takes in a header of its own it would hand to whatever host a redirect names. This drops Authorization and the headers named. Another port on the same host is the same machine, and is left alone.
func MarkRetrySafe ¶
MarkRetrySafe declares a request safe to re-send even though its method is not idempotent: a GraphQL or JQL query is a read that happens to travel as a POST. Reads with idempotent methods (GET, HEAD, OPTIONS) need no mark.
func NewBaseTransport ¶
func NewBaseTransport() http.RoundTripper
NewBaseTransport returns http.DefaultTransport tuned with per-attempt timeouts so a stalled connection or unresponsive server fails fast and gets retried by RetryTransport instead of hanging the command. It is exported so callers that must build their own client (oauth2, for one) can still start from the same transport.
func NewHTTPClient ¶
NewHTTPClient returns a client that trace-logs every exchange under name and retries transient failures up to DefaultMaxRetry times. name appears in the logs so a tool talking to two APIs can tell their traffic apart.
func Preview ¶ added in v0.4.0
Preview is the start of a response body for an error to carry: the space around it gone, cut at PreviewLen bytes on a whole character, with "..." to say there was more.
func RedactError ¶ added in v0.4.0
RedactError hides the credentials in the URL a failed request names. A request that gets no answer (a timeout, a refused connection) fails with a *url.Error that prints its whole URL, and a key sent in the query is in it, so it would reach a log or a tool's answer. The error keeps its type and what it wraps; only the URL it prints changes (see RedactURL).
It is for the place the error is first seen: a message already built around the error (fmt.Errorf with %w) keeps the text it was built with.
func RedactURL ¶ added in v0.4.0
RedactURL replaces the value of every credential query parameter in a URL with REDACTED, and any password in it, leaving the rest as it was sent: the parameters around it, their order and a fragment. The parameters are the common ones (api_key, apikey, api_token, access_token, token) and whatever also names, compared without case.
func StatusCode ¶ added in v0.4.0
StatusCode is the status of a *StatusError in err's chain, or 0.
Types ¶
type RetryTransport ¶
type RetryTransport struct {
// contains filtered or unexported fields
}
RetryTransport wraps an http.RoundTripper with retry logic for transient failures: 429 (rate limited) for every request, plus connection errors and 5xx (server error) responses for retry-safe requests only (see MarkRetrySafe). Attempts back off exponentially (1s, 2s, 4s, ...), a 429's Retry-After header is honoured up to MaxRetryAfter, and a cancelled request context aborts the wait.
func NewRetryTransport ¶
func NewRetryTransport(name string, next http.RoundTripper, maxRetry int) *RetryTransport
NewRetryTransport wraps next with up to maxRetry attempts under name. A maxRetry below 1 is treated as 1: every request is sent at least once.
type StatusError ¶ added in v0.4.0
type StatusError struct {
Method string
Path string
// StatusCode is the status the server answered with
StatusCode int
// Expected are the statuses the request takes as success, when it
// names them
Expected []int
// Body is the start of the response body (see Preview)
Body string
// Tries is how many times the request was sent, when more than once
Tries int
// Note is what the caller knows about this status on this API: which
// key to check for a 401, what permission a 403 wants
Note string
}
StatusError is an answer with a status the request did not ask for.
func (*StatusError) Error ¶ added in v0.4.0
func (e *StatusError) Error() string
type Transport ¶
type Transport struct {
// contains filtered or unexported fields
}
Transport is an http.RoundTripper that dumps each request and response to clog.Log at TRACE, with JSON bodies pretty-printed. The dumps include headers, so they are only produced when TRACE is actually enabled. A request that gets no answer comes back with what the operating system may be doing about it, where that is known (see Explain).
func NewTransport ¶
func NewTransport(name string, next http.RoundTripper) *Transport
NewTransport wraps next with trace logging under name.