chttp

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: GPL-3.0 Imports: 17 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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

func Explain(err error) error

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

func IsNotFound(err error) bool

IsNotFound reports whether err is a 404 from the server.

func KeepCredentialsOnHost added in v0.4.0

func KeepCredentialsOnHost(headers ...string) func(req *http.Request, via []*http.Request) error

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

func MarkRetrySafe(req *http.Request) *http.Request

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

func NewHTTPClient(name string) *http.Client

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

func Preview(body []byte) string

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

func RedactError(err error, also ...string) error

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

func RedactURL(raw string, also ...string) string

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

func StatusCode(err error) int

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.

func (*RetryTransport) RoundTrip

func (t *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.

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.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL