Documentation
¶
Overview ¶
Package httpx is the HTTP transport the Jira, forge and messaging clients share: the one-method Doer seam they accept, and a client that refuses redirects so a credential never follows one.
Index ¶
- Variables
- func Client(timeout time.Duration) *http.Client
- func ClientOver(next http.RoundTripper, timeout time.Duration) *http.Client
- func OnThisMachine(host string) bool
- func RateLimited(header http.Header) error
- func Read(body io.Reader, limit int64) ([]byte, error)
- func ShowingRedirect(ctx context.Context) context.Context
- func Streaming(ctx context.Context) context.Context
- func Unreachable(unreachable error, base string, err error) error
- type Doer
- type RateLimitError
Constants ¶
This section is empty.
Variables ¶
var ErrAnswerTooLarge = errors.New("the answer was larger than the most that is read")
ErrAnswerTooLarge reports an answer longer than the most a client reads.
var ErrRateLimited = errors.New("rate limited; wait and try again")
ErrRateLimited reports a server that asked the caller to wait: a 429 Too Many Requests, or a forge's 403 whose headers ask for a wait. It is its own error so a caller is told to wait rather than that its credential was refused, which a shared 403/429 branch would say.
var ErrRedirected = errors.New("refused to follow a redirect")
ErrRedirected reports a redirect this client declined to follow.
var ErrTimedOut = errors.New("the server took too long to answer")
ErrTimedOut reports a server that took longer to answer than the client waits.
Functions ¶
func Client ¶
Client is the transport a credential may travel over, each request bounded by timeout: whole, or part by part for a Streaming one. It sends through Go's default transport; see ClientOver.
func ClientOver ¶ added in v0.9.0
ClientOver is Client sending through next, for a caller that sends some other way, as a test does, keeping all Client holds a request to.
It refuses redirects, and that is the point rather than a convenience: Go's default client forwards the Authorization header to any redirect target sharing a HOSTNAME, ignoring both the port and the scheme. A service behind a misconfigured proxy that redirects HTTPS to HTTP on the same host would hand the token to the plaintext hop with nothing in the code looking wrong.
func OnThisMachine ¶ added in v0.9.0
OnThisMachine reports a host name, without its port, that only this machine answers to: localhost, or a loopback address. A credential is sent over plain http only to such a host, where it never crosses a network.
func RateLimited ¶
RateLimited reports a rate limit, naming how long to wait when the server said so in a Retry-After header. The header's other, HTTP-date form — which these APIs do not use for a rate limit — and a missing or unreadable value fall back to the bare ErrRateLimited, so a caller always gets an error that errors.Is matches.
func Read ¶ added in v0.9.0
Read reads an answer's body whole when it holds no more than limit bytes. Past that it reads one byte more, to tell, and reports ErrAnswerTooLarge: cut at the limit, an answer would decode as broken JSON, which says the server sent nonsense rather than that it sent too much.
func ShowingRedirect ¶ added in v0.5.0
ShowingRedirect is ctx for a request that is shown a redirect, its status and Location, rather than having it refused — for a caller that follows it itself, deciding what the next request carries. Nothing is followed for it.
func Streaming ¶ added in v0.9.0
Streaming is ctx for a request whose answer may take longer than the client's timeout to arrive in full, so long as no part of it is longer than that in coming — a long log, read to its end. An answer is otherwise bounded whole, from the request to the last byte of its body.
func Unreachable ¶
Unreachable turns a transport error into a message that reads the way what happened warrants. A refused redirect means the server DID answer — with a redirect this client declines to follow — so it is not "could not reach"; it is reported as ErrRedirected. Anything else wraps the caller's own unreachable sentinel (whose noun names the service). base is named when non-empty; a client whose address is itself a credential — a Slack webhook — passes "".
Types ¶
type Doer ¶
Doer sends one HTTP request. *http.Client's Do method satisfies it.
A function type rather than an interface because it is a single method, which is the seam shape this project prefers; it exists so a caller can supply the redirect-refusing, deadline-bearing client below rather than the default one.
type RateLimitError ¶ added in v0.5.0
RateLimitError is a rate limit that named how long to wait, so a caller that can wait knows how long. It is ErrRateLimited to errors.Is.
func (*RateLimitError) Error ¶ added in v0.5.0
func (e *RateLimitError) Error() string
Error says to wait, and how long.
func (*RateLimitError) Unwrap ¶ added in v0.5.0
func (e *RateLimitError) Unwrap() error
Unwrap is ErrRateLimited.
Source Files