http

Documentation

Index

• Variables
• func Drain(body io.ReadCloser)
• func RedactHTTPQueryValuesFromError(err error) error
• func RedactHTTPQueryValuesFromString(surl string) string
• func RedactHTTPQueryValuesFromURL(url *url.URL)
• type AuthClient
  • func NewAuthClient(authHandler AuthHandler, opts ...AuthClientOpt) (*AuthClient, error)
  • func (ac *AuthClient) Client() *rhttp.Client
  • func (ac *AuthClient) CloneWithNewClient(client *rhttp.Client) *AuthClient
  • func (ac *AuthClient) Do(req *http.Request) (*http.Response, error)
  • func (ac *AuthClient) RoundTrip(req *http.Request) (*http.Response, error)
  • func (ac *AuthClient) StandardClient() *http.Client
• type AuthClientOpt
  • func WithAuthPolicy(policy AuthPolicy) AuthClientOpt
  • func WithAuthRequestCtxFunc(arc AuthReqContextFunc) AuthClientOpt
  • func WithHeader(header http.Header) AuthClientOpt
  • func WithRetryableClient(client *rhttp.Client) AuthClientOpt
• type AuthHandler
• type AuthPolicy
• type AuthReqContextFunc

Variables

var (
	ErrMissingAuthHandler       = errors.New("missing auth handler")
	ErrFailedToAuthorizeRequest = errors.New("failed to authorize request")
	ErrFailedToHandleChallenge  = errors.New("failed to handle challenge")
)

var DefaultAuthPolicy = func(resp *http.Response) bool {
	return resp.StatusCode == http.StatusUnauthorized
}

DefaultAuthPolicy defines the default AuthPolicy, where by only a "401 Unauthorized" warrants authentication.

var DefaultAuthReqContext = func(reqCtx context.Context) context.Context {
	return context.Background()
}

DefaultAuthReqContext is the default AuthReqContextFunc. It returns an entirely new context.

Functions

func Drain

func Drain(body io.ReadCloser)

Drain tries to read and close the response body so the connection can be reused. See https://pkg.go.dev/net/http#Response for more information. Since it consumes the response body, this should only be used when the response body is no longer needed.

func RedactHTTPQueryValuesFromError

func RedactHTTPQueryValuesFromError(err error) error

RedactHTTPQueryValuesFromError is a log utility to parse an error as a URL error and redact HTTP query values to prevent leaking sensitive information like encoded credentials or tokens.

func RedactHTTPQueryValuesFromString

func RedactHTTPQueryValuesFromString(surl string) string

RedactHTTPQueryValuesFromURL redacts HTTP query values from a string.

func RedactHTTPQueryValuesFromURL

func RedactHTTPQueryValuesFromURL(url *url.URL)

RedactHTTPQueryValuesFromURL redacts HTTP query values from a URL.

Types

type AuthClient

type AuthClient struct {
	// contains filtered or unexported fields
}

AuthClient provides a HTTP client that is capable of authenticating with origin servers. It contains an AuthHandler type that is responsible for preparing valid responses/answers to challenges as well authenticating requests. It wraps an inner retryable client, that is uses to send requests.

Note: The AuthClient does not directly provide a mechanism for caching credentials/tokens. Ideally, this should be handled by the underlying AuthHandler.

func NewAuthClient

func NewAuthClient(authHandler AuthHandler, opts ...AuthClientOpt) (*AuthClient, error)

NewAuthClient creates a new AuthClient given an AuthHandler.

An AuthHandler must be provided. If no retryable client is provided a default one will be created. If no AuthPolicy is provided the DefaultAuthPolicy will be used. If no AuthReqCtxFunc is provided the DefaultAuthReqContext is used.

func (*AuthClient) Client

func (ac *AuthClient) Client() *rhttp.Client

Client returns the inner retryable client.

func (*AuthClient) CloneWithNewClient

func (ac *AuthClient) CloneWithNewClient(client *rhttp.Client) *AuthClient

CloneWithNewClient returns a clone of the AuthClient with a new inner retryable client. The new AuthClient will share the same headers, auth handler and auth policy.

func (*AuthClient) Do

func (ac *AuthClient) Do(req *http.Request) (*http.Response, error)

Do sends a request using the underlying retryable client. If no error is returned and the AuthPolicy deems that the response warrants authentication, it will invoke the AuthHandler to handle the challenge, re-authorize and re-send the request.

func (*AuthClient) RoundTrip

func (ac *AuthClient) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip calls the AuthClient's underlying Do method. It exists so that the AuthClient can satisfy the http.RoundTripper interface.

func (*AuthClient) StandardClient

func (ac *AuthClient) StandardClient() *http.Client

StandardClient returns a standard http.Client with the AuthClient set as its inner Transport.

Consumers should use this when dealing with API's that strictly accept http.Client's.

type AuthClientOpt

type AuthClientOpt func(*AuthClient)

func WithAuthPolicy

func WithAuthPolicy(policy AuthPolicy) AuthClientOpt

WithAuthPolicy attaches an AuthPolicy to the AuthClient.

func WithAuthRequestCtxFunc

func WithAuthRequestCtxFunc(arc AuthReqContextFunc) AuthClientOpt

WithAuthRequestCtxFunc attaches a AuthReqContextFunc to the AuthClient.

func WithHeader

func WithHeader(header http.Header) AuthClientOpt

WithHeader adds a http.Header to the AuthClient that will be attached to every request.

func WithRetryableClient

func WithRetryableClient(client *rhttp.Client) AuthClientOpt

WithRetryableClient attaches a retryable client to the AuthClient.

type AuthHandler

type AuthHandler interface {
	// HandleChallenge is responsible for parsing the challenge defined
	// by the origin server and preparing a valid response/answer.
	HandleChallenge(context.Context, *http.Response) error
	// AuthorizeRequest is responsible for authorizing the request to be
	// sent to the origin server.
	AuthorizeRequest(context.Context, *http.Request) (*http.Request, error)
}

AuthHandler defines an interface for handling challenge-response based HTTP authentication.

See: https://datatracker.ietf.org/doc/html/rfc9110#section-11

type AuthPolicy

type AuthPolicy func(*http.Response) bool

AuthPolicy defines an authentication policy. It takes a response and determines whether or not it warrants authentication.

type AuthReqContextFunc

type AuthReqContextFunc func(reqCtx context.Context) context.Context

AuthReqContextFunc takes the original request context and returns a context that will be used by the new authenticated request.